openBEB is a software framework developed to support correlative measurements for systems biology, with focus on single cell analysis. It provides a software framework for
- Instrument control
- Data registration
- Synchronization with a data-base, such as openBIS.
openBEB consists of two components:
- A CORE program providing tools for
- Data-managment; handles arbitrary types of data
- Meta-data handling
- Unified, hierarchical coordinate (HC) system
- Macro parser for the coordination of individual openBEB modules and plugins
- Update mechanism
- Plug-ins providing technology-specific tools
- Instrument controls, e.g., for microfluidics, can be easily programmed in LabView.
- Viewports for visualization
Although it is currently optimized for visual proteomics, the plug-in structure has been designed to be easily extensible to support other technologies. The standard plug-in for database connectivity communicates with openBIS.
This short Tutorial provides a step-by-step introduction to openBEB. It will show:
- The graphical user interface of the openBEB software
- How data are organised
- How data can be imported from the file-system
- How data can be annotated and visualised.
See also the screen casts listed here.
You need a working openBEB installation to follow this Tutorial.
Starting up openBEB
- Start-up the software:
- Mac os X: The CORE application is located in the /Application folder
- Windows 7: Start menu -> all programs -> openBEB windows -> openBEB
- Windows 8: No idea about the most efficient way at the moment.
The software starts, with standard settings, the CORE program checks for updates.
With standard settings, openBEB checks for updates during start-up. The extensions (including the plugins) are automatically updated without additional user interactions. If the CORE program needs an update, an installer is downloaded ind the suer can update the complete openBEB system. The openBEB program needs to be restarted afterwards. The text-field provides some latest information for the openBEB system.
- Press OK and the plugins are loaded:
- After start-up, the main window is shown in full-screen mode.
Main window user interface
- The main openBEB window can be used in two modes.To toggle between the two modes, press button (A):
- Full-screen mode. OpenBEB switches to this mode after start-up. Press button (A) ">><<" to change to window mode.
- Window mode. Press button (A) "<<>>" to change to full-screen mode.
- In window mode, you can resize the window (C)
- Panel (B) shows the management tools. Here you can create new data collections, open them and trigger plug-ins for data-acquisition.
For more information, see the page https://wiki-bsse.ethz.ch/x/SgmBBQ.
OpenBEB offers help by two means:
- A online help webpage www.openBEB.org.
- The context help.
To get help help, you can use the openBEB menu:
- Open menu "openBEB". the Two help options are shown.
- "Open Help" opens the online help.
- "Context help" opens a small window displaying context sensitive information, dependent on the mouse pointer.
OpenBEB organizes data in collections, containers that can but do not have to host a series of raw datasets and associated metadata files. In the simplest case, a collection only consists of a metadata file. Collections can contain other collections, and can thus be organized in a hierarchical structure. The upmost collection, the root of the collection hierarchy, is called a “bundle”. Note that collections are always linked to protocols. Protocols are predefined metadata descriptions of the contents of a collection.
For more information see also the page: How data are organised.
We will now create a bundle containing a collection. The bundle will be linked to a protocol describing a project, the sub-collection of the bundle will contain the results of a simple imaging experiment by electron microscopy.
- In the management panel, press button "New bundle".
- The following dialog panel is opened:
- Select the parent folder, where the new bundle should be saved.
- Provide a name for the bundle. Note, that many special characters are not allowed to enable cross-platform compatibility, e.g., ":", "?", "._", "\" or "/". This name is also used in the file system and must be cross-platform compatible.
- Provide your institutional e-mail address.
- Each collection is associated with a protocol. Protocols are predefined descriptions of collections and data-sets. Here, our bundle is the begin of a new project, therefore we select the protocol "main project". Information about the selected protocol is shown. A protocol also sets some standard data-set property information, which can be changed. Here, we do not want to store any data in the bundle-collection itself, therefore the "Meta-data only" option is selected.
- In annotations, you can provide some arbitrary information about the collection (bundle).
- Pressing OK creates the bundle.
- Select the newly created bundle in the management panel by clicking once on the name of the new bundle:
To create a new collection to host our datasets we want to import, select the collection, in which the new collection should be created. Since we only created a collection hierarchy root ("bundle"), we select the newly created bundle (see also step 3).
- Press the button "New collection…"
- A dialog is shown allowing you to create a new collection:
- Provide a name for the the new collection. Note, that many special characters are not allowed to enable cross-platform compatibility, e.g., ":", "?", "._", "\" or "/".
- Provide your institutional e-mail address and adjust the date.
- Select the protocol: In our case, we use the protocol "Data acquisition - Electron Microscopy - Cryo - SingleParticle".
- Select the file-type and file extension. We will import some MRC image files from in the following section (extension *.mrc).
- Press OK to create the new collection.
Of course you can "open" existing bundles by attaching them to openBEB. However, due the differences between the Windows and the Mac OS there are some differences:
On windows, bundles are normal folders with the name BundleName.bundle:
- Press button "Attach Bundle…".
- Navigate to the bundle location.
- On windows, open the bundle (e.g., by double click).
- Press button "Select this folder" (here in german: "Ordner Auswählen"):
The bundle is attached.
Mac OS X
On the mac, the bundles are displayed and handled by the operating system like files. However, on the loewer level, they are normal folder with a "bundle flag".
- Press button "Attach Bundle…".
- Navigate to the bundle location.
- Select the bundle:
- Press "open"
The bundle is attached.
Importing data from the file system
The following section imports some simple image data into the newly created collection from the file-system.
- Download the following test images (MRC file format from Cryo electron microscopy).
- Unzip the test data files.
- Select the newly created collection.
- Select an import wizard. These are plugins for instrument control and data import. The standard openBEB plugin "ImportFromFileSystem" allows the import of data from the file system. We need to select this:
- Select the files you downloaded and unzipped in step 1 and 2 using the "+ files" button:
- Press "OK". An import window is displayed. Note, that during this operation the collection can not be accessed as shown by the symbol:
- Press "OK". Once you have done this, the data is imported and processed.
The next section explains how to to open a collection and browse the contents.
Browsing and visualising data in a collection
Opening the collection and Browsing data
- Now you can open a collection (or the bundle) by double clicking a collection in the management panel. The open collection is indicated by an open folder:
Note, that you you can open one collection at a time.
- The collection is opened and the first dataset is displayed in the viewport (left from the management panel). Note, that depending of the settings, another viewport might be used when you open a collection the first time. See step 4 and the info box below.
You can adjust the way, how the image is displayed using the histogram tool or by changing the grayscale lookup table (LUT). You can also enlarge regions of interests by opening a magnifier window (Press "New loupe") and clicking in the image. Note, that these options are specific for the data visualisation plugin called "image".
- You can use the browsing options, to see your images in the collection:
- Previous / next image.
- Viewport selection. See and select different plug-ins for data-visualization.
- Select data-set by entering the data-set number.
- Light table: Display window with data-set thumbnails.
- To use another visualisation plugin, you can select another viewport, e.g., the power spectrum viewport:
The power spectrum is calculated and displayed in the viewport.
- To see thumbnails of all images in the collection, press the button "Light table". A window with thumbnail representations of the images is displayed:
You can open another image by double-clicking on an image thumbnail, pressing the arrow buttons ("<-", "->") or typing the image number to display in the data-set number field.
Selecting standard viewport
When you open a collection for the first time, the standard viewport for the correpsonding data-type is used. This can be changed in the plugin settings:
- To select the standard viewport for images, open the plugin manager: "openBEB" menu and "Manage plug-ins":
- The plugin manager is opened. Note, depending of sour local installation, different sets of plugins might be displayed:
We imported image data files. Images, can be visualised by various plugins, such as standard images or powerspectras (Fourier transform). We want to browse our images using the normal image plug-in after opening a new collection. To this end, we must configure the image viewportType plug-in. Select the plug-in "image" in the viewportType section.
- Select "Plugin settings" in the right panel.
- Select "Image" in the Standard Viewport menu. Changes in this settings are immediately stored permanently.
- Close the plug-in browser by pressing "OK".
The next section with explain the meta-data system of openBEB and how to graphically annotate data.
Annotation of data-sets
The metadata of openBEB are organised on different levels:
- Collection metadata.
- Data-set metadata, containing:
- Data description.
- openBEB Metadata, including the "protocol".
- Embedded metadata. This is information extracted from the data-set file. This information is stored along with the other met data information.
- Frame annotation for multi-dimensional data sets, e.g., stacks of images.
Furthermore, openBEB allows the relation between different collection and data-sets to be recorded, using a hierarchical coordinate system (not discussed in this tutorial, see https://wiki-bsse.ethz.ch/x/Fw3PBQ).
- To see the collection metadata, select the collection tab:
Collection metadata consists of two parts: First, the standard annotations (such as operator, or simply free text notes) and a rating system. Second, by the protocol selected during collection creation.
- To edit the protocol, double click an entry. Depending on the data-type of the entry, different options are displayed:
Here, a predefined list of options can be selected.
- Similar metadata are displayed for the data-set. Press the "Data" tab:
Three metadata section are visible
- The standard operator and annotation section, identical to the corresponding section in the collection panel.
- A protocol (bottom).
- A dataset property panel. This provides information about the dataset (e.g. spacing and memory type). Normally, you should not need to edit this section, but you can do so by double clicking:
Warning: Changing these properties can mess up the data-set visualisation! We do not do this here.
For a tutorial to manage and create protocols, see this screen-cast.
OpenBEB also allows to annotate the data graphically:
- Select tab "Views".
- Press button "Save view". A window for graphical annotation is displayed:
Press button "Undo", if you want to remove last changes. Press "OK" to store the view.
- The new graphical annotation is now shown in the view panel:
You can change the view by pressing the button "edit". However, you ably can add graphical annotations, not delete or change existing annotations.
- To close the openBEB program, select "openBEB" -> "Quit openBEB…":
The quit macro is started and after a conformation dialog openBEB is closed.