From 1ba98058e17913219016ebb6348def4cfd6529c4 Mon Sep 17 00:00:00 2001 From: Christian Tischer Date: Thu, 15 May 2025 17:04:45 +0200 Subject: [PATCH 1/3] Improve collection table description WIP --- tutorials/mobie_collection_table.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tutorials/mobie_collection_table.md b/tutorials/mobie_collection_table.md index a64cd31..ef3aaf9 100644 --- a/tutorials/mobie_collection_table.md +++ b/tutorials/mobie_collection_table.md @@ -11,6 +11,11 @@ The `Open Collection Table...` is designed to: - Support different viewing modes for data visualization. - Optionally handle access credentials for protected S3 buckets. +### Collection table examples + +- [Volume EM with segmentation and spots]() +- [CLEM](https://docs.google.com/spreadsheets/d/1d_khb5P-z1SHu09SHSS7HV0PmN_VK9ZkMKDuqF52KRg/edit?usp=sharing) + ### Parameters - Table Path: The file location of the collection table to be opened. The table must be a TAB-separated text file. From d5e13e8da7bf8bcf37d997fbc7ad07decfb90f3e Mon Sep 17 00:00:00 2001 From: Christian Tischer Date: Thu, 15 May 2025 18:58:37 +0200 Subject: [PATCH 2/3] Improve collection table description --- index.md | 18 ++++++++ tutorials/mobie_collection_table.md | 70 +++++------------------------ 2 files changed, 29 insertions(+), 59 deletions(-) diff --git a/index.md b/index.md index 40a2a3c..52e7e79 100644 --- a/index.md +++ b/index.md @@ -32,6 +32,24 @@ views, images and tables for your colleagues to explore - [Open a MoBIE project (expert mode)](./tutorials/expert_mode.md) - [Using MoBIE from the command line](./tutorials/cli.md) +### Supported file formats + +#### Table data formats + +- TSV +- Excel +- Google sheet links +- CSV + - We recommend quoting `".."` all values, because some may contain commas, which will break the format if not quoted +- Parquet + +#### Image data formats + +- Everything that Bio-Formats can open +- OME-Zarr +- BigDataViewer N5 +- ilastik HDF5 + ## Exploring image and segmentation data - [Exploring images](./tutorials/exploring_images.md) diff --git a/tutorials/mobie_collection_table.md b/tutorials/mobie_collection_table.md index ef3aaf9..6fa19af 100644 --- a/tutorials/mobie_collection_table.md +++ b/tutorials/mobie_collection_table.md @@ -1,69 +1,21 @@ -## Open image and segmentation collections +## MoBIE collection table -The `Open Collection Table...` command allows users to open a collection table containing references to multiple datasets, facilitating batch visualization. The command supports various viewing and grouping modes and data root configurations. +A MoBIE collection table is a very convenient way to specify how to open multiple images, segmentations or spots, potentially correlative, in MoBIE. -### Command Description +In a nutshell, each row specifies one dataset, where the only required column is called **uri**, which must contain a valid path to that dataset. This path can be local (File system) or in the cloud (S3 or HTTP). -The `Open Collection Table...` is designed to: +There are a few more reserved column names that can be used to specify how the data should be visualized in more detail. For example, the **affine** column that can be used to transform images into a common coordinate system, which is useful for correlative data. -- Open a collection table specified by the user. -- Configure data root paths based on absolute paths or relative paths. -- Support different viewing modes for data visualization. -- Optionally handle access credentials for protected S3 buckets. +[**Specification of supported columns.**](https://github.com/mobie/mobie-viewer-fiji/blob/main/src/main/java/org/embl/mobie/lib/table/columns/CollectionTableConstants.java). -### Collection table examples +In addition to the specified columns the table can contain arbitrary other columns that may contain interesting information about the respective data sets. Please make sure not to use column names that are part of the above specification. -- [Volume EM with segmentation and spots]() -- [CLEM](https://docs.google.com/spreadsheets/d/1d_khb5P-z1SHu09SHSS7HV0PmN_VK9ZkMKDuqF52KRg/edit?usp=sharing) +### Opening a collection table -### Parameters +A collection table can be opened via the `Open Collection Table...` command to be found within `Fiji: Plugins > MoBIE`. In addition to the required path to the collection table the command takes a few optional arguments such as S3 keys. -- Table Path: The file location of the collection table to be opened. The table must be a TAB-separated text file. -- Data Root: Specifies how the data URIs in the table are interpreted: -- PathsInTableAreAbsolute : Assume URIs are absolute paths. -- UseTableFolder : Use the folder containing the table as the root for relative paths. -- UseBelowDataRootFolder : Use a specified folder as the root for relative paths. -- Data Root Folder: Optional. Specify this if paths in the table are relative and you want to use a specific directory as the root. -- Viewing Mode: Determines the visualization mode: - - ThreeDimensional : Enables arbitrary plane slicing for volumetric viewing. - - Planar : Restricts browsing to the XY, YZ, or XZ planes. -- S3 Access Key: Optional. Access key for accessing data in a protected S3 bucket. -- S3 Secret Key: Optional. Secret key for accessing data in a protected S3 bucket. +### Supported collection table data formats -### Collection Table Specification - -The collection table must adhere to the following specifications, with exact column names given in brackets. - -#### Important notes - -- The table must be a **TAB-separated** text file - - You can create such a table, e.g., in Excel via "Save As..", choosing the "File Format" "Tab-delimited Text". -- Only the `uri` column must be present; all other columns are optional. -- Please see the [JavaDoc](https://github.com/mobie/mobie-viewer-fiji/blob/main/src/main/java/org/embl/mobie/lib/table/columns/CollectionTableConstants.java) for an up-to-date and a more comprehensive description. -- Please see this [folder](https://github.com/mobie/mobie-viewer-fiji/tree/main/src/test/resources/collections) for example tables. - -#### Columns - -This list just provides an overview. See the [JavaDoc](https://github.com/mobie/mobie-viewer-fiji/blob/main/src/main/java/org/embl/mobie/lib/table/columns/CollectionTableConstants.java) for more details and example entries. - -- URI Column (`uri`): Must contain valid URIs pointing to image or spots datasets. Supported formats include OME-Zarr, BDV XML, ilastik HDF5, Parquet, and others. -- Name Column (`name`): Optional. Determines the label for data display within MoBIE. If absent, a name is derived from the file name. -- Type Column (`type`): Optional. Specifies the pixel type ("intensities", "labels", "spots"). Defaults to "intensities" if absent or invalid. -- Channel Column (`channel`): Optional. Zero-based integer Determines which channel of a multi-channel dataset to load. Defaults to channel 0 if absent or invalid. -- Color Column (`color`): Optional. Specifies the lookup table coloring for intensities. Defaults to "white" if absent or invalid. -- Blend Column (`blend`): Optional. Determines the blending mode ("sum" or "alpha"). Defaults to "sum" if absent or invalid. -- Affine Column (`affine`): Optional. Specifies an affine transformation to apply upon display. -- View Column (`view`): Optional. Determines the view name for access in MoBIE UI. Defaults to the name from the Name column. -- Exclusive Column (`exclusive`): Optional. Determines if a view is exclusive ("true" or "false"). Defaults to "false". -- Group Column (`group`): Optional. Specifies a UI selection group for the view. Defaults to "views" if absent. -- Labels Table Column (`labels_table`): Optional. Used for "labels" type data, specifies a path to a segmentation table. -- Contrast Limits Column (`contrast_limits`): Optional. Specifies contrast limits for intensities. Defaults to auto-contrast if absent or invalid. -- Grid Column (`grid`): Optional. Groups data into a grid view. Defaults to no grid if absent. -- Format Column (`format`): Optional. Specifies the data format (e.g., OmeZarr). Defaults based on file ending if absent. - -### Usage - -- Provide the path to the collection table and configure the data root as needed. -- Choose the desired viewing mode for data visualization. -- Optionally, provide S3 access credentials if accessing protected data. +The collection table itself can be provided in a number of formats; notably also links to Google Sheets are supported. If you like to use the CSV file format we recommed quoting `"..."` the table cell values, because some of them may contain commas. +[**Supported table file formats.**](tutorials/index.md#table-data-formats) From 2fe71a43361a903f9485878992fe46896013ee16 Mon Sep 17 00:00:00 2001 From: Christian Tischer Date: Thu, 15 May 2025 19:18:44 +0200 Subject: [PATCH 3/3] Add example tables --- tutorials/mobie_collection_table.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/tutorials/mobie_collection_table.md b/tutorials/mobie_collection_table.md index 6fa19af..731c8b4 100644 --- a/tutorials/mobie_collection_table.md +++ b/tutorials/mobie_collection_table.md @@ -19,3 +19,12 @@ A collection table can be opened via the `Open Collection Table...` command to b The collection table itself can be provided in a number of formats; notably also links to Google Sheets are supported. If you like to use the CSV file format we recommed quoting `"..."` the table cell values, because some of them may contain commas. [**Supported table file formats.**](tutorials/index.md#table-data-formats) + +### Example collection tables + +Below are some examples. Those are all Google sheets, so those links could be directly opened in the above described command. + +- [Correlative 2-D EM, fluorescence and 3-D tomography data](https://docs.google.com/spreadsheets/d/1d_khb5P-z1SHu09SHSS7HV0PmN_VK9ZkMKDuqF52KRg/edit?gid=0#gid=0) +- [Grid view of many OpenOrganelle EM volumes](https://docs.google.com/spreadsheets/d/1trSQFm_4Nc42C_Fum8N_ZzEmPuML6ACKVmLlc862Rp8/edit?usp=sharing) +- [Grid view of a few OpenOrganelle EM volumes and organelle segmentations](https://docs.google.com/spreadsheets/d/1jEnl-0_pcOFQo8mm8SUtszoWewvjyFXY0icO7gPUaQk/edit?gid=0#gid=0) +- [Large volume EM data, annotated cell segmentation, and a few spots](https://docs.google.com/spreadsheets/d/1xZ4Zfpg0RUwhPZVCUrX_whB0QGztLN_VVNLx89_rZs4/edit?gid=0#gid=0) \ No newline at end of file