Getting started with openBIS

A. Start servers

The installation has completed successfully. To start openBIS launch the following script:
${INSTALL_BIN_PATH}/allup.sh
This command might take several minutes on the inital startup, depending on the performance of your server!
After the completion of the above command openBIS will be available at https://${HOSTNAME}:8443/openbis

Note: by default, openBIS expects to be able to connect your PostgreSQL database as superuser 'postgres' without a password. This is because openBIS needs to create its database users and schemas. If this assumption does not hold, the following commands print the SQL scripts that can be used to create the required databases manually:
openBIS application server database:
${INSTALL_BIN_PATH}/init_database.sh openbis_prod openbis
DSS pathinfo database:
${INSTALL_BIN_PATH}/init_database.sh pathinfo_prod openbis
Imaging database (required only if technology 'screening' is enabled)
${INSTALL_BIN_PATH}/init_database.sh imaging_prod openbis
Proteomics database (required only if technology 'proteomics' is enabled)
${INSTALL_BIN_PATH}/init_database.sh proteomics_productive openbis
The first argument of script 'init_database.sh' defines the database name. The second argument defines the username that openBIS will be using to connect the corresponding database. Again, openBIS expects the user(s) can connect the database without a password. If this is not the case, the password needs to be set to service.properties. Consult openBIS documentation for details.

B. Importing test data

By now you have a fully functional openBIS instance, but it makes little sense if it has no data in it.

Generic

Here are the steps to register a file/folder as a data set into openBIS.

  1. Log in to openBIS as admin.
  2. Open the Experiment Browser by clicking on the menu item Browse -> Experiments and open the default experiment.
  3. Click on the Data Set Uploader tab and upload one or several files.
  4. Choose a data set type and press the button 'Create Data Set'.

Proteomics

Here are the steps to get an example prot.XML into openBIS.

  1. Log in to openBIS as admin.
  2. Open space browser by clicking on menu item Admin -> Spaces.
  3. Create a space named TEST by using Add Space button.
  4. Create a project named PROT inside space TEST by using menu item New -> Project.
  5. At the console execute the command:
    cp -R ${DSS_ROOT_DIR}/examples/test+prot ${DSS_ROOT_DIR}/incoming-ms-search
It will create an experiment in project /TEST/PROT which shows a list of proteins. We challenge you to go find it in the running application !

Screening

You could import a minimalistic example by doing the following:
  1. Log in to openBIS as admin.
  2. Open experiment type browser by clicking on menu item Admin -> Types -> Experiment Types.
  3. Create experiment type SIRNA_HCS.
  4. At the console execute the command:
    cp -R ${DSS_ROOT_DIR}/examples/PLATE1 ${DSS_ROOT_DIR}/incoming-hcs
It will create a plate with code PLATE with images data for one of its wells. We challenge you to go find it in the running application !

Illumina NGS (ETH BSSE Setup)

  1. A flow cell with flow lanes is created reading out two XML files provided by the Illumina sequencer:
    mkdir -p ${DSS_ROOT_DIR}/create-flowcell-hiseq/120420_SN792_0109_BC0P8LACXX/;
    cp -R ${DSS_ROOT_DIR}/examples/illumina-ngs/120420_SN792_0109_BC0P8LACXX/*.xml ${DSS_ROOT_DIR}/create-flowcell-hiseq/120420_SN792_0109_BC0P8LACXX;
    touch ${DSS_ROOT_DIR}/create-flowcell-hiseq/.MARKER_is_finished_120420_SN792_0109_BC0P8LACXX
  2. A flow cell output from a HiSeq2000 is registered as a data set of the sample 120420_SN792_0109_BC0P8LACXX.
    Additionally a data set is registered for each flow lane:
    rsync -a --exclude=Unaligned* ${DSS_ROOT_DIR}/examples/illumina-ngs/120420_SN792_0109_BC0P8LACXX ${DSS_ROOT_DIR}/register-flowcell-hiseq;
    touch ${DSS_ROOT_DIR}/register-flowcell-hiseq/.MARKER_is_finished_120420_SN792_0109_BC0P8LACXX;
  3. The sequencer is finished and we want to track this automatically. Therefore we sync the RTAComplete.txt in a drop box:
    mkdir -p ${DSS_ROOT_DIR}/read-rta-timestamp/120420_SN792_0109_BC0P8LACXX/; rsync ${DSS_ROOT_DIR}/examples/illumina-ngs/120420_SN792_0109_BC0P8LACXX/RTAComplete.txt ${DSS_ROOT_DIR}/read-rta-timestamp/120420_SN792_0109_BC0P8LACXX/RTAComplete.txt; touch ${DSS_ROOT_DIR}/read-rta-timestamp/.MARKER_is_finished_120420_SN792_0109_BC0P8LACXX
  4. For creating some samples we use the 'Sample Registration'. This is available under the 'Import' menu:
    Import -> Sample Registration -> Choose sample type '(multiple)' and browse to the file:
    ${DSS_ROOT_DIR}/examples/illumina-ngs/tsv-files/example_samples_with_parents.tsv
    Tick 'Update existing'and press the 'Save' button.
    This created several samples which can be viewed via Browse -> Samples. You might need to select the Sample Type 'all'
    and the Space 'all'.
    Note that the samples are in a parent-/child relationship indicated by the samples shown in the 'Parents' column.

  5. After the demultiplexing using the Illumina 'configureBclToFastq.pl' the FASTQ files are created and also some statistic files are provided.
    Let's register them as well in openBIS:
    mkdir ${DSS_ROOT_DIR}/register-unaligned/120420_SN792_0109_BC0P8LACXX;
    rsync -a ${DSS_ROOT_DIR}/examples/illumina-ngs/120420_SN792_0109_BC0P8LACXX/Unaligned* ${DSS_ROOT_DIR}/register-unaligned/120420_SN792_0109_BC0P8LACXX;
    touch ${DSS_ROOT_DIR}/register-unaligned/.MARKER_is_finished_120420_SN792_0109_BC0P8LACXX;

    The demultiplexed FASTQ files are a data set of the samples BSSE-QGF-LIBRARY-1 and BSSE-QGF-LIBRARY-2. Note that lane 1 and two
    contained both samples which results in two FASTQ data sets for each sample.

A short description of all drop boxes is also provided here: openBIS for Illumina NGS

ELN-LIMS

Here are the steps to create your first experimental step and register an image file as preview into the ELN-LIMS interface.

  1. Log in to ELN/LIMS interface as admin.
  2. Using the navigation tree on the left hand-side go to LAB NOTEBOOK -> DEFAULT_LAB_NOTEBOOK -> DEFAULT_PROJECT -> DEFAULT_EXPERIMENT.
  3. Click on the plus sign on the toolbar and create a new EXPERIMENTAL_STEP.
  4. After creating it, a new component will appear on the right hand-side. Select "ELN Preview Image" from the dropdown and drop an image file in the Files Uploader.
  5. Now you have a basic lab notebook with an experiment, experimental step and one image used as preview.

Microscopy

  1. At the console execute the command:
    cp -R ${DSS_ROOT_DIR}/examples/microscopy_example ${DSS_ROOT_DIR}/incoming-microscopy;
    touch ${DSS_ROOT_DIR}/incoming-microscopy/.MARKER_is_finished_microscopy_example
  2. Log in to openBIS as admin.
  3. Open Utilities -> Project viewer and find the example in project DEFAULT of space DEFAULT.

Flow Cytometry

  1. At the console execute the command:
    cp -R ${DSS_ROOT_DIR}/examples/flow_cytometry_example ${DSS_ROOT_DIR}/incoming-lsrfortessa;
    touch ${DSS_ROOT_DIR}/incoming-lsrfortessa/.MARKER_is_finished_flow_cytometry_example
  2. Log in to openBIS as admin.
  3. Open Utilities -> Project viewer and find the example in project DEFAULT of space DEFAULT.

Importing example data

To import example data please add plugin "[technology]-optional" to core-plugins.properties, where [technology] is "screening", "illumina-ngs" or "proteomics"


Customizing openBIS

In the scientific world there is no one-size-fits-them-all solutions. Your research data is certainly different from our example data. Luckily, openBIS provides an easy way to script the import process - the dropboxes. You can learn how to create your custom-tailored dropboxes here.