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 (e.g., useful for browsing gene locations in spatial transcriptomics data).

• If you can’t wait to try this out, you may skip the explanations and immediately scroll to the below “Quick start” section.

• Watch the last part of this talk to obatin a short overview (the URL already starts at the relevant time point).

Collection table specification

Each row specifies one dataset, which can be further configured by a number of predefined columns.

Defined columns:

• uri (mandatory): file path or URL to an image, label mask, or spots table
  • defines the absolute or relative location of a dataset that can be visualised with MoBIE
• name: free text
  • defines the name of the dataset in the MoBIE user interface
  • necessary if two datasets have the same file name
• type:
  • intensities (default): normal images
  • labels: label mask images (aka segmentation images)
  • spots: a table with annotated spots
  • example collection containing all three types
• channel: zero based integers
  • necessary to load an image with multiple channels, please add one row per channel
  • 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
• 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
• thin_plate_spline: BigWarp JSON
  • applies a thin plate spline transformation to the dataset
  • example colletion with thin plate spline transform
• view: free text
  • datasets that are part of the same view (i.e., same text in the table cell) will be shown together
• 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
• 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)
  • e.g., (10,240) or (1000, 38000)
  • changes the initial display settings
• 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
• display: free text
  • all datasets that have the same (non-empty) entry will have a shared display settings UI item
  • useful for grid layouts where all images may have been acquired with comparable settings
  • example collection with display column
• 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: This is a mandatory field. Put here the 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: This is a mandatory field.
  • 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 ): This is an optional field. It is only considered if you chose UseBelowRootDataFolder above.
• Viewing mode: This is a mandatory field. It changes the browsing mode of BigDataViewer.
  • 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).
• ( S3 Access Key ) & ( S3 Secret Key ): These are optional fields. Use those if the uri column of the collection table points to data in a protected S3 bucket.

Example collection tables

Learning tips

• In the below example 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 show or go).
  • 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).
• For local image data, you can use Plugins > MoBIE > Create > Create MoBIE Collection Table... to get started and then modify or add columns

Local data

• Segmented nuclei with measurements tables
  • Segmentations and measurements tables have been created using this CellProfiler project
  • After download 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

Google sheets pointing to remote data

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
• ThinPlateSpline transformed EM volume

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
• ( Data Root Folder ): leave empty
• Viewing mode: ThreeDimensional
• ( S3 Access Key ): leave empty
• ( S3 Secret Key ): leave empty

Have fun browsing the data!

Note that you could use any of the URL of the above “Example collection tables” in the exact same way (just copy and paste the links into the Open Collection Table... command).

If you are unsure how to browse the data, this video should be helpful. More videos can be found in the MoBIE YouTube channel.

Troubleshooting