MoBIE collection tables

MoBIE collection tables provide a convenient human editable way to define large (correlative) image data sets, including images, segmentation images, segmentation annotations and annotated spots.

• The below example collection tables demonstrate a number of use cases, such as:
  • Inspection of a set of locally stored (i.e. on your computer) images with segmented objects and corresponding object measurements
  • Visualisation of correlative light and transmission and tomography electron microscopy data, where the data is hosted remotely at the BioImage Archive
  • Visualisation of a set of segmented 3D electron microscopy datasets from the open organelle project, hosted remotely at the Janelia Research Farm
  • Visualisation of 3-D spatial transcriptomics data

• You may skip the below explanations and immediately try it out using the below quick start section.

• Watch the last part of this video to obtain a brief overview (the URL already starts at the relevant time point); or check out the corresponding slide deck (starting from slide 9).

Collection table specification

Each row specifies one dataset, which can be configured by one of these columns:

• uri (mandatory): defines the location of a dataset
  • allowed values: absolute or relative file paths or URL to an intensity image, label mask image, or spots table
• type: defines the type of a dataset; this column can be omitted if all data are intensity images.
  • allowed values:
    • intensities (default): normal images
    • labels: label mask (segmentation) images
    • spots: a table with annotated spots
  • example collection containing all three types
• channel: the index of the channel that should be opened; necessary to load an image with multiple channels, please add one row per channel (note that MoBIE works with a single channel data model and thus each channel of an image must be loaded individually); this column can be omitted if all your data only has a single channel (e.g. EM data)
  • allowed values: zero based integers
  • example collection with multiple channels
• color: supports various encodings, e.g.
  • r(0)-g(255)-b(0)-a(255)
  • white, red, etc.
• blend:
  • sum (default): image intensities will be displayed in an additive manner
  • alpha: images that are displayed later will be rendered “on top” of the previous images; the corresponding opacity can be configured in the user interface
  • example collection with alpha blending
• view: free text
  • datasets that are part of the same view (i.e., same free text in the table cell) will be shown together
  • useful to show images together that have been acquired in the same physical coordinate system, e.g. using a tiled acquisition or multi-modal imaging of the same specimen
• display: free text
  • all datasets that have the same (non-empty) entry will have a shared display settings UI item
  • useful if you want show several images together in the same view that have been acquired with the same microscope settings, e.g. a tiled acquisition of GFP images (in which case you could use “GFP” as the table cell entry)
  • also useful for grid layouts (s.b.) where all images may have been acquired with comparable settings
  • example collection with display column
• affine: row-packed affine transform.
  • e.g., shift along x-axis: (1,0,0,-105.34,0,1,0,0,0,0,1,0)
  • example table with affine transforms
  • example prompt for AI chat models to learn more: “please explain 3d affine transforms in a 3x4 matrix form, give a few simple examples (translation, rotation, scaling) and explain its row packed serialisation”
• thin_plate_spline: BigWarp JSON text pasted into the table cell
  • applies a thin plate spline transformation to the dataset
  • example colletion with thin plate spline transform
• elastix_bspline_uri: location of a elastix b-spline transformation file
  • applies the b-spline transformation to the image
  • note that this currently will ignore initial transformations that may be specified in this transformation file; if these initial transformations are important, you need to convert them to an affine transformation and add them via the “affine” column.
• displacement_field_uri: location of a displacement field transformation file
  • applies the displacement field transformation to the image
  • the specification for this file is currently specific to MoBIE; currently, the only convenient way to create such a file is via the following Fiji menu entry: Plugins > MoBIE > Create > Create Inverse Displacement Field From Elastix BSpline…
• exclusive:
  • true: when displaying the dataset all other currently displayed datasets will be removed
  • false (default): when displaying the dataset it will be shown on top of already displayed datasets
• name: free text
  • defines the name of the dataset in the MoBIE user interface
  • necessary if two datasets have the same file name
• group: free text
  • creates a new drop-down in the MoBIE UI
  • useful to group data together
• labels_table: path to a labels table
  • only considerd in conjuction with type: labels
  • example labels table
  • supported labels table column naming schemes
• contrast_limits: (min,max) or auto
  • e.g., (10,240) or (1000,38000)
  • changes the initial display settings
  • auto will trigger an auto-contrast algorithm
• grid: free text
  • if non-empty, all datasets with the same entry will be layed out into a 2-D grid
  • example collection with a grid
• grid_position: (x,y)
  • e.g., (0,0), (1,0), (5,2)
  • defines where the dataset is layed out in the grid
  • only considered in conjuction with a non-empty grid entry.
  • useful to put several datasets (e.g., image and corresponding labels) into the same grid position
  • example collection with grid positions
• format:
  • OmeZarr: needed if the path to the OME-Zarr does not contain .ome.zarr
  • all other entries will be ignored as the file types will be auto-determined
• spot_radius: number larger than zero
  • defines the rendering radius of spots
  • only considered in for a dataset of type spots
• bounding_box: configures the size of a spot image. E.g., (0.0,0,0)-(200.5,200,50.3)
  • only considered in for a dataset of type spots

The only required column is uri, which must contain a valid path to that dataset. This path can be local (File system) or in the cloud (S3 or HTTP).

For a more complete specification of all columns please read the comments in the code.

In addition to the specified columns, the table may contain an arbitrary number of additional columns, where you can annotate your respective data sets.

Opening a collection table in Fiji/MoBIE

Within the Fiji menu select: Plugins > MoBIE > Open > Open Collection Table...

A user interface will pop up with the following fields:

• Table Uri: Location of a MoBIE collection table.
  • This may be a path to a file on your computer or to a “cloud resource” such as an S3 object store, a GitHub URL, or a Google Sheet URL.
  • The collection table can be provided in a number of formats, including EXCEL, CSV, TSV and Google Sheets.
  • For Google Sheets simply copy and paste the link that shows in your browser or use the link that you obtain when using Google’s sharing functionality.
• Data Root:
  • PathsInTableAreAbsolute: Choose this if the uri column in the table contains absolute paths (for cloud resources that is always the case, for files on your computer it may be the case)
  • UseTableFolder: Choose this option if the paths in the uri column are relative to the location of the collection table. This supports the scenario, where you have all your data organised within some folder structure and the collection table is at the root of this folder structure. This is a very useful setup because it allows you to move or copy the whole folder structure and opening the data via the collection table will still work.
  • UseBelowRootDataFolder: Choose this option if the paths in the uri column are relative to the location of the root data folder that you can specify below. This supports the scenario, where you have all your data organised within some folder structure and the collection table is, for some reason, not at the root of this folder structure.
  • Note that in principle we could probably support a mix of local relative and cloud absolute paths; if you need this please get in touch.
• ( Data Root Folder ): path to a folder
  • This is an optional field. It is only considered if you chose UseBelowRootDataFolder above.
• Viewing mode:
  • ThreeDimensional: Choose this is your data also contains 3-D images.
  • TwoDimensional: Choose this if all your data is 2-D (it will make your life easier, because this mode avoids getting lost in 3-D while browsing in BigDataViewer).
• ( S3 Access Key ) & ( S3 Secret Key ): free text
  • These are optional fields. Use those if the uri column of the collection table points to data in a protected S3 bucket.

Defining complex views

The advantage of the collection table is that it is easy to create. A disadvantage as compared to a traditional MoBIE project is that you cannot define very complex views on your data.

However, you can do the following: After opening a collection table, you can configure a complex view and then right click in the BigDataViewer window and say “Save current view…”. It will ask you for the name of this view and importantly also for the file in which you want to save it. Please call this file “mobie-views.json” and save it in the same folder as your collection table. The next time you open the collection table, MoBIE will automatically pick it up and then you can look at the views defined in this file. Note that you can add several views to that file. So next time you want to save a view, simply select that file again as the destination. Please note that any changes in your collection table will probably invalidate those views! Thus, in practice, once you created such a mobie-views.json, you may not change the collection table anymore.

Example collection tables

Local data

• Segmented nuclei with measurements tables
  • Segmentations and measurements tables have been created using this CellProfiler project
  • Download and unzip the data
  • Plugins > MoBIE > Open > Open Collection Table...
    • Table Uri: Enter path to one-image-collection.csv or two-images-collection.csv
    • Data Root: UseTableFolder
    • Viewing Mode: TwoDimensional
    • Leave all other fields empty

Remote data

For remote data it is convenient to use Google Sheets as the collection table, as this will allow you to have an entirely cloud based solution that you can readily share with anyone.

Please note that the Google Sheet link must allow public read access.

Here are some Google Sheet collection tables that are pointing to remotely hosted data. They can be opened like this:

• Plugins > MoBIE > Open > Open Collection Table...
  • Table Uri: Paste link to the Google Sheet
  • Data Root: PathsInTableAreAbsolute
  • Viewing Mode: ThreeDimensional
  • Leave all other fields empty
• BioImage Archive hosted multi-channel OME-Zarr
• Correlative 2-D EM, fluorescence and 3-D tomography data
• Grid view of OpenOrganelle EM volumes
• Grid view of OpenOrganelle EM volumes and organelle segmentations
• Large volume EM data, annotated cell segmentation, and some annotated spots
• 3-D spatial transcriptomics (The genes are initially not visible, because they are in a different z-plane; click on one gene in the table to move the view.)
• ThinPlateSpline transformed EM volume

Learning tips

• In MoBIE collections tables only the uri column is mandatory. It can be instructive to remove some or all of the other columns and see what you get. You can then sequentially add back the other columns and observe how the visualisation changes (and/or errors appear).
  • Practically, you can “remove” a column by giving it a name that MoBIE does not recognise, e.g. renaming affine (recognised) to x_affine (not recognised).

Creating your own MoBIE collection tables

Manually

The motivation of using a table format to specify image collections was that it should be very easy to manually create such tables, for example in spreadsheet software like Excel. We recommend taking any of the above examples as a starting point and modify them according to your needs.

In Fiji

For local image data, you can use Plugins > MoBIE > Create > Create MoBIE Collection Table... to get started and then modify or add columns in the table.

Using python code

Here is a simple example of how to create a MoBIE collection table using pandas in python. The example is intended as an inspiration and does not cover every situation. Feel free to copy and adjust to your needs!

Quick start

Make sure to have MoBIE installed on your computer.

Within the Fiji menu select: Plugins > MoBIE > Open > Open Collection Table....

In the user interface that pops up choose:

• Table Uri: https://docs.google.com/spreadsheets/d/1xZ4Zfpg0RUwhPZVCUrX_whB0QGztLN_VVNLx89_rZs4/edit?gid=0#gid=0
• Data Root: PathsInTableAreAbsolute
• Viewing mode: ThreeDimensional
• Leave all other fields empty

Have fun browsing the data!

• You can use any of the URL of the above example collection tables in the exact same way.
• If you are unsure how to browse the data within MoBIE, this video should be helpful.
• More videos can be found in the MoBIE YouTube channel.
• General troubleshooting.