diff --git a/setup.cfg b/setup.cfg index 531b00e..d88f18d 100644 --- a/setup.cfg +++ b/setup.cfg @@ -56,7 +56,7 @@ where = src [options.extras_require] fractal-tasks = anndata - fractal-tasks-core==1.3.3 + fractal-tasks-core==1.3.4 plotting = anndata dask diff --git a/src/scmultiplex/__FRACTAL_MANIFEST__.json b/src/scmultiplex/__FRACTAL_MANIFEST__.json index cdd9d0b..900562e 100644 --- a/src/scmultiplex/__FRACTAL_MANIFEST__.json +++ b/src/scmultiplex/__FRACTAL_MANIFEST__.json @@ -9,6 +9,7 @@ "multiplexing", "2D" ], + "docs_info": "### Purpose\n- Links segmented objects between a reference and an alignment acquisition within a single well of an HCS OME-Zarr dataset. \n- Calculates object shifts using segmentation label maps, aligns objects, and identifies matching labels based on an Intersection over Union (IoU) cutoff threshold. \n- Generates a linking table that maps object labels from the reference acquisition to those in the alignment acquisition.\n\n### Outputs\n- A linking table stored in the alignment acquisition directory. \n- The table includes matched object pairs and their IoU scores.\n\n### Limitations\n- Only works for HCS OME-Zarr datasets where a **single well ROI** is used for linking. Multi-ROI processing (e.g., for FOV ROI tables) is not yet supported. \n- Requires segmentation label maps to be provided for both the reference and alignment acquisitions. \n- Matching is performed using an IoU threshold; objects below the threshold are not linked. \n- Pixel sizes must match between the reference and alignment acquisitions for accurate registration. \n", "executable_non_parallel": "fractal/_image_based_registration_hcs_init.py", "executable_parallel": "fractal/calculate_object_linking.py", "meta_non_parallel": { @@ -110,7 +111,6 @@ "type": "object", "title": "CalculateObjectLinking" }, - "docs_info": "## _image_based_registration_hcs_init\nInitialized calculate registration task\n\nThis task prepares a parallelization list of all zarr_urls that need to be\nused to calculate the registration between acquisitions (all zarr_urls\nexcept the reference acquisition vs. the reference acquisition).\nThis task only works for HCS OME-Zarrs for 2 reasons: Only HCS OME-Zarrs\ncurrently have defined acquisition metadata to determine reference\nacquisitions. And we have only implemented the grouping of images for\nHCS OME-Zarrs by well (with the assumption that every well just has 1\nimage per acqusition).\n## calculate_object_linking\nCalculate object linking based on segmentation label map images\n\nThis task consists of 4 parts:\n\n1. Load the object segmentation images for each well (paired reference and alignment round)\n2. Calculate the shift transformation for the image pair\n3. Apply shifts to image pair and identify matching object labels given an iou cutoff threshold\n3. Store the identified matches as a linking table in alignment round directory\n\nParallelization level: image\n", "docs_link": "https://github.com/fmi-basel/gliberal-scMultipleX" }, { @@ -122,6 +122,7 @@ "2D", "3D" ], + "docs_info": "### Purpose\n- Calculates a **consensus linking table** across all multiplexing rounds in an HCS OME-Zarr dataset. \n- Aligns object labels from all acquisitions to a reference acquisition, ensuring consistent object identities across rounds. \n- Stores the resulting consensus table in the reference acquisition directory.\n\n### Outputs\n- A **consensus linking table** that maps object labels from all rounds to a single, aligned consensus. \n- The table includes:\n - Original object labels from each round (e.g., `R0_label`, `R1_label`, ...). \n - A new consensus label (`consensus_label`) and index (`consensus_index`) for aligned objects.\n\n### Limitations\n- Requires pre-existing linking tables generated by a previous linking task (e.g., `Calculate Object Linking`). \n- Assumes that the input linking tables follow a consistent structure across rounds. \n", "executable_non_parallel": "fractal/_init_group_by_well_for_multiplexing.py", "executable_parallel": "fractal/calculate_linking_consensus.py", "meta_non_parallel": { @@ -208,7 +209,6 @@ "type": "object", "title": "CalculateLinkingConsensus" }, - "docs_info": "## _init_group_by_well_for_multiplexing\nFinds images for all acquisitions per well.\n\nReturns the parallelization_list to run `find_registration_consensus`.\n## calculate_linking_consensus\nApplies pre-calculated registration to ROI tables.\n\nApply pre-calculated registration such that resulting ROIs contain\nthe consensus align region between all cycles.\n\nParallelization level: well\n", "docs_link": "https://github.com/fmi-basel/gliberal-scMultipleX" }, { @@ -220,6 +220,7 @@ "2D", "3D" ], + "docs_info": "### Purpose\n- Relabels segmentation images and ROI tables in an OME-Zarr dataset based on a pre-calculated **consensus linking table**. \n- Aligns object labels across multiplexing rounds to ensure consistency with the consensus object identities. \n- Outputs new segmentation images and ROI tables with updated labels.\n- Requires a valid **consensus linking table** as input, typically generated by the `Calculate Linking Consensus` task. \n- Non-consensus objects are set to background and excluded from the outputs.\n\n### Outputs\n- A **new segmentation image** where object labels match the consensus labels. \n- A **relabelled ROI table** corresponding to the updated segmentation image, saved with a `_linked` suffix.\n\n### Limitations\n- Only supports **single well ROI tables**; multi-ROI processing (e.g., field of view ROIs) is not yet implemented. \n- Input segmentation images and ROI tables must match in terms of object labels; inconsistencies will cause errors. \n", "executable_non_parallel": "fractal/_image_based_registration_hcs_allrounds_init.py", "executable_parallel": "fractal/relabel_by_linking_consensus.py", "meta_non_parallel": { @@ -315,7 +316,6 @@ "type": "object", "title": "RelabelByLinkingConsensus" }, - "docs_info": "## _image_based_registration_hcs_allrounds_init\nInitialized calculate registration task\n\nSame as _image_based_registration_hcs_init.py only does not exclude reference round in zarr_url list;\nall rounds are processed.\n## relabel_by_linking_consensus\nRelabels image labels and ROI tables based on consensus linking.\n\nParallelization level: image\n", "docs_link": "https://github.com/fmi-basel/gliberal-scMultipleX" }, { @@ -326,6 +326,7 @@ "multiplexing", "3D" ], + "docs_info": "### Purpose\n- Calculates point-cloud-based registration between segmentation images using **PlatyMatch**. \n- Works well for **complex 3D registration**.\n- Aligns sub-objects (e.g., nuclei) that belong to parent objects (e.g., organoids) by calculating **affine** and optionally **free-form deformation** transformations. \n- Outputs linking tables of matched sub-objects and optionally saves transformation matrices to disk.\n\n### Outputs\n- A **linking table** that maps sub-objects between reference and alignment rounds using affine and/or free-form deformation (FFD) transformations. \n- Transformation matrices (optional), saved on disk for each object pair. \n\n### Limitations\n- Only supports **single well ROI tables**; multi-ROI processing (e.g., FOV ROIs) is not yet implemented. \n- Requires parent objects to be linked in a prior step using a **consensus linking table**. \n- Assumes consistent pixel sizes between reference and alignment rounds for accurate registration. \n- Relies on sufficient sub-object counts for alignment; regions with fewer than 3 sub-objects are skipped.", "executable_non_parallel": "fractal/_image_based_registration_hcs_init.py", "executable_parallel": "fractal/calculate_platymatch_registration.py", "meta_non_parallel": { @@ -480,7 +481,6 @@ "type": "object", "title": "CalculatePlatymatchRegistration" }, - "docs_info": "## _image_based_registration_hcs_init\nInitialized calculate registration task\n\nThis task prepares a parallelization list of all zarr_urls that need to be\nused to calculate the registration between acquisitions (all zarr_urls\nexcept the reference acquisition vs. the reference acquisition).\nThis task only works for HCS OME-Zarrs for 2 reasons: Only HCS OME-Zarrs\ncurrently have defined acquisition metadata to determine reference\nacquisitions. And we have only implemented the grouping of images for\nHCS OME-Zarrs by well (with the assumption that every well just has 1\nimage per acqusition).\n## calculate_platymatch_registration\nCalculate point-cloud-based registration with PlatyMatch.\n\nThis task consists of 4 parts:\n\n1. Load the sub-object segmentation images for each well (paired reference and alignment round)\n2. Select sub-objects that belong to object region by loading with object ROI table and mask by object mask.\n Object pair is defined by consensus linking. Filter the sub-objects to remove small debris that was segmented.\n3. Calculate affine and optionally the free-form deformation for each object pair\n4. Output: save the identified matches as a linking table in alignment round directory\n and optionally the transformation matrix on disk.\n\nParallelization level: image\n", "docs_link": "https://github.com/fmi-basel/gliberal-scMultipleX" }, { @@ -491,6 +491,7 @@ "3D", "mesh" ], + "docs_info": "### Purpose\n- Calculates **3D surface meshes** for parent objects (e.g., tissues, organoids) based on 3D child-level segmentation (e.g., nuclei). \n- Optionally applies **multiscale label fusion** to estimate a smooth parent shape by merging child objects. \n- Generates smoothened surface meshes using **VTK algorithms**, with optional mesh decimation for reduced complexity. \n- Outputs 3D meshes in `.stl` or `.vtp` format and a new well label map in the dataset.\n\n### Outputs\n- **Surface meshes** of parent objects, saved as `.stl` (single object) or `.vtp` (multi-object) files in the dataset\u2019s `meshes` folder. \n- A **new label map** containing fused child-level objects, saved in the OME-Zarr dataset (only if multiscale processing is enabled). \n- A **bounding-box ROI table** corresponding to the new label map.\n\n### Limitations\n- Requires pre-segmented child objects and a parent object ROI table. \n- Multiscale processing requires a **parent label** for accurate object grouping and fusion. \n- Label map outputs may have **overlaps clipped**, where higher-label IDs take precedence in dense regions. \n- Mesh quality can vary with complex geometries; manual tuning of smoothing parameters may be needed for optimal results.", "executable_non_parallel": "fractal/_init_group_by_well_for_multiplexing.py", "executable_parallel": "fractal/surface_mesh_multiscale.py", "meta_non_parallel": { @@ -666,7 +667,6 @@ "type": "object", "title": "SurfaceMeshMultiscale" }, - "docs_info": "## _init_group_by_well_for_multiplexing\nFinds images for all acquisitions per well.\n\nReturns the parallelization_list to run `find_registration_consensus`.\n## surface_mesh_multiscale\nCalculate 3D surface mesh of parent object (e.g. tissue, organoid)\nfrom 3D cell-level segmentation of children (e.g. nuclei)\n\nRecommended to run on child objects that have been filtered to remove debris and disconnected components\n(e.g. following cleanup_3d_segmentation task)\n\nThis task consists of 4 parts:\n\n1. Load the sub-object (e.g. nuc) segmentation images for each object of a given reference round; skip other rounds.\n Select sub-objects (e.g. nuc) that belong to parent object region by masking by parent.\n2. Perform label fusion and edge detection to generate surface label image.\n3. Calculate surface mesh of label image using vtkDiscreteFlyingEdges3D algorithm. Smoothing is applied with\n vtkWindowedSincPolyDataFilter and tuned with 4 task parameters: passband, smoothing_iterations, feature_angle,\n polynomial_degree (minimal effect).\n The number of triangles in the mesh is optionally reduced with vtkQuadricDecimation filter to form a good\n approximation to the original geometry and is tuned with task parameter target_reduction.\n4. Output: save the (1) meshes (.stl) per object id in meshes folder and (2) well label map as a new label in zarr.\n Note that label map output may be clipped for objects that are dense and have overlapping pixels.\n In this case, the 'winning' object in the overlap region is the one with higher label id.\n", "docs_link": "https://github.com/fmi-basel/gliberal-scMultipleX" }, { @@ -677,6 +677,7 @@ "Classical segmentation", "3D" ], + "docs_info": "### Purpose\n- Performs **full 3D object segmentation** of raw intensity images using intensity thresholding. \n- Combines two intensity channels, applies **Gaussian smoothing** and **Canny edge detection** for refined masks. \n- Filters out debris and neighboring objects by selecting the **largest connected component** within a masked region. \n- Outputs a new 3D segmentation label image and an updated masking ROI table.\n\n### Outputs\n- A **new 3D label image** stored in the dataset, with refined object segmentation. \n- A corresponding **bounding-box ROI table** saved as `{output_label_name}_ROI_table`. \n\n### Limitations\n- Requires pre-segmented 2D MIP-based ROI regions as input for masking. \n- Supports intensity thresholding with either **Otsu's method** or a user-defined threshold. \n- Assumes consistent image resolution and pixel intensities across channels. \n- Regions with extreme intensity variations or overlapping objects may require manual parameter tuning for optimal results.", "executable_non_parallel": "fractal/init_select_multiplexing_round.py", "executable_parallel": "fractal/segment_by_intensity_threshold.py", "meta_non_parallel": { @@ -906,7 +907,6 @@ "type": "object", "title": "SegmentByIntensityThreshold" }, - "docs_info": "## init_select_multiplexing_round\nFinds images for desired acquisition per well.\n\nReturns the parallelization_list.\n## segment_by_intensity_threshold\nCalculate full 3D object segmentation after 2D MIP-based segmentation using intensity thresholding of\nraw intensity image(s).\n\nThis task consists of 3 parts:\n\n1. Load the intensity images for selected channels using MIP-based segmentation ROIs.\n2. Generate 3D mask based on simple thresholding of the combined channel images. The thresholded image is\n smoothened using gaussian blurring followed by Canny edge detection. Optional z-illumination correctopn\n is applied on the fly. The MIP-based segmentation is used to mask\n the resulting label image to roughly exclude any neighboring organoids and debris. To further exclude\n neighboring organoids and debris, the largest connected component is selected as the final label image.\n3. Output: save the (1) new label image and (2) new masking ROI table in the selected zarr url.\n", "docs_link": "https://github.com/fmi-basel/gliberal-scMultipleX" }, { @@ -916,6 +916,7 @@ "tags": [ "3D" ], + "docs_info": "### Purpose\n- Computes **spherical harmonics** for 3D segmented objects in a label image using the **aics_shparam** library. \n- Calculates and analyzes the **shape features** of objects, including reconstruction error. \n- Outputs spherical harmonic coefficients and optionally saves reconstructed surface meshes.\n\n### Outputs\n- A **feature table** containing spherical harmonic coefficients and reconstruction error (**MSE**) per object. \n- Optionally, the **computed surface mesh** and the **reconstructed mesh** (from harmonics), saved as `.stl` files in a new `meshes` folder.\n\n### Limitations\n- Input label image must contain 3D segmented objects; neighboring objects are removed by masking. \n- The accuracy of spherical harmonics depends on the chosen **maximum degree (`lmax`)** and input label quality. \n- Mesh reconstruction might smooth out fine details in highly complex shapes.\n", "executable_non_parallel": "fractal/_init_group_by_well_for_multiplexing.py", "executable_parallel": "fractal/spherical_harmonics_from_labelimage.py", "meta_non_parallel": { @@ -1026,7 +1027,6 @@ "type": "object", "title": "SphericalHarmonicsFromLabelimage" }, - "docs_info": "## _init_group_by_well_for_multiplexing\nFinds images for all acquisitions per well.\n\nReturns the parallelization_list to run `find_registration_consensus`.\n## spherical_harmonics_from_labelimage\nCalculate spherical harmonics of 3D input label image using aics_shparam.\n\nThis task consists of 6 parts:\n\n1. Load 3D label image based on provided label name and ROI table\n2. Compute 3D mesh with vtkContourFilter using aics_shparam functions\n3. Compute spherical harmonics of mesh using aics_shparam\n4. Compute reconstruction error (mse) of computed harmonics\n5. Optionally generate reconstructed mesh from the calculated harmonics\n6. Output: save the (1) spherical harmonic coefficients and mse error as feature table\n (2) reconstructed meshes (.stl) per object id in a new meshes folder within zarr structure\n", "docs_link": "https://github.com/fmi-basel/gliberal-scMultipleX" }, { @@ -1038,6 +1038,7 @@ "mesh", "morphology" ], + "docs_info": "### Purpose\n- Extracts detailed **shape features** from 3D meshes, including volume, surface area, solidity, concavity, and aspect ratio. \n- Optionally calculates **Gaussian curvature** for mesh surfaces and **spherical harmonics** to decompose mesh geometry. \n- Outputs feature tables, curvature meshes, and optional harmonic-reconstructed meshes.\n\n### Outputs\n1. A **feature table** with extracted mesh measurements, including:\n - Volume, surface area, aspect ratio, concavity, normalized surface area-to-volume ratio, and more. \n2. Optional **spherical harmonic coefficients** and reconstruction error (MSE), saved as a separate table. \n3. Optional **reconstructed meshes** from spherical harmonics saved as `.stl`. \n4. Optional **Gaussian curvature meshes** saved as `.vtp` files in a new `curvature` folder. \n5. Optional **convex hull** and **bounding box** meshes saved as `.vtp` files.\n\n### Limitations\n- Requires pre-existing **.stl meshes** within the Zarr structure (e.g., generated by the **Surface Mesh Multiscale** task). \n- Mesh files must match the **object labels** specified in the ROI table. \n- Computational cost increases when enabling **Gaussian curvature** or **spherical harmonics** calculations. \n- Mesh quality and accuracy depend on the input segmentation and mesh generation parameters.", "executable_non_parallel": "fractal/_init_group_by_well_for_multiplexing.py", "executable_parallel": "fractal/scmultiplex_mesh_measurements.py", "meta_non_parallel": { @@ -1172,7 +1173,6 @@ "type": "object", "title": "ScmultiplexMeshMeasurements" }, - "docs_info": "## _init_group_by_well_for_multiplexing\nFinds images for all acquisitions per well.\n\nReturns the parallelization_list to run `find_registration_consensus`.\n## scmultiplex_mesh_measurements\nExtract shape features of 3D input meshes.\n\nThis task consists of 5 parts:\n\n1. Load meshes (.stl) from zarr structure that have been previously generated\n (e.g. using Surface Mesh Multiscale task)\n2. Extract mesh morphology measurements: volume, surface area, extent, solidity, concavity, asymmetry,\n aspect ratio, and normalized surface area to volume ratio. Units correspond to units of mesh. If mesh was\n generated with surface_mesh_multiscale task, units are physical units (um). For further details of features see\n scMultiplex FeatureFunctions.py\n3. Optionally calculate Gaussian curvature at each mesh point (set calculate_curvature = True)\n4. Optionally compute spherical harmonics of mesh using aics_shparam (set calculate_harmonics = True).\n Compute reconstruction error (mse) of computed harmonics and optionally generate reconstructed mesh from the\n calculated harmonics\n5. Output: save (1) extracted measurements as a new table (output_table_name), (2) optional spherical harmonic\n coefficients and mse error as a separate feature table ('output_table_name'_harmonics) (3) optional\n reconstructed meshes from spherical harmonics as .stl within zarr structure (3) optional convex hull\n and bounding box on disk as .vtp within zarr structure (4) optional curvature meshes on disk as .vtp within\n zarr structure.\n", "docs_link": "https://github.com/fmi-basel/gliberal-scMultipleX" }, { @@ -1183,6 +1183,7 @@ "morphology", "intensity" ], + "docs_info": "### Purpose\n- **Measures intensity and morphology features** from existing segmentation images in an OME-Zarr dataset. \n- Computes advanced 3D morphology metrics, including surface area, using extended `regionprops` measurements. \n- Supports both intensity-based and morphology-only measurements: \n - If no input intensity channels are provided, the task calculates morphology features only. \n - For intensity measurements, channels can be specified individually, allowing flexibility across different image inputs. \n- Enables **measurements within masked objects** (e.g., measuring nuclei properties within organoids) by specifying an `input_ROI_table` that defines parent regions, such as organoid ROIs.\n\n### Limitations\n- Currently tested only on image data in the **CZYX** format. \n- Measurement accuracy and performance may depend on the spacing and resolution of input images. \n- Does not support measurements at lower resolutions (e.g., beyond level 0).", "executable_parallel": "fractal/scmultiplex_feature_measurements.py", "meta_parallel": { "cpus_per_task": 4, @@ -1278,7 +1279,6 @@ "type": "object", "title": "ScmultiplexFeatureMeasurements" }, - "docs_info": "## scmultiplex_feature_measurements\nMeasurements of intensities and morphologies\n\nWrapper task for scmultiplex measurements for Fractal to generate\nmeasurements of intensities and morphologies\n", "docs_link": "https://github.com/fmi-basel/gliberal-scMultipleX" }, { @@ -1287,6 +1287,7 @@ "2D", "3D" ], + "docs_info": "### Purpose\n- Expands segmented **labels** in 2D or 3D images **without overlap**. \n- Supports expansion by a fixed pixel distance or dynamically based on **label size**. \n- Optionally masks expanded labels using **parent objects** to prevent spillover. \n- Outputs an expanded label image and preserves non-overlapping object boundaries.\n\n### Outputs\n- A new **expanded label image** saved with an `_expanded` suffix. \n\n### Limitations\n- If masking by parent is enabled, the parent object label image must be provided. \n- Expansion beyond object boundaries may be clipped, depending on the surrounding labels and image dimensions. ", "executable_parallel": "fractal/expand_labels.py", "meta_parallel": { "cpus_per_task": 4, @@ -1346,7 +1347,6 @@ "type": "object", "title": "ExpandLabels" }, - "docs_info": "## expand_labels\nExpand labels in 2D or 3D image without overlap.\n", "docs_link": "https://github.com/fmi-basel/gliberal-scMultipleX" } ], diff --git a/src/scmultiplex/dev/task_info/calculate_linking_consensus.md b/src/scmultiplex/dev/task_info/calculate_linking_consensus.md new file mode 100644 index 0000000..b30577e --- /dev/null +++ b/src/scmultiplex/dev/task_info/calculate_linking_consensus.md @@ -0,0 +1,14 @@ +### Purpose +- Calculates a **consensus linking table** across all multiplexing rounds in an HCS OME-Zarr dataset. +- Aligns object labels from all acquisitions to a reference acquisition, ensuring consistent object identities across rounds. +- Stores the resulting consensus table in the reference acquisition directory. + +### Outputs +- A **consensus linking table** that maps object labels from all rounds to a single, aligned consensus. +- The table includes: + - Original object labels from each round (e.g., `R0_label`, `R1_label`, ...). + - A new consensus label (`consensus_label`) and index (`consensus_index`) for aligned objects. + +### Limitations +- Requires pre-existing linking tables generated by a previous linking task (e.g., `Calculate Object Linking`). +- Assumes that the input linking tables follow a consistent structure across rounds. diff --git a/src/scmultiplex/dev/task_info/calculate_object_linking.md b/src/scmultiplex/dev/task_info/calculate_object_linking.md new file mode 100644 index 0000000..0e1b92f --- /dev/null +++ b/src/scmultiplex/dev/task_info/calculate_object_linking.md @@ -0,0 +1,14 @@ +### Purpose +- Links segmented objects between a reference and an alignment acquisition within a single well of an HCS OME-Zarr dataset. +- Calculates object shifts using segmentation label maps, aligns objects, and identifies matching labels based on an Intersection over Union (IoU) cutoff threshold. +- Generates a linking table that maps object labels from the reference acquisition to those in the alignment acquisition. + +### Outputs +- A linking table stored in the alignment acquisition directory. +- The table includes matched object pairs and their IoU scores. + +### Limitations +- Only works for HCS OME-Zarr datasets where a **single well ROI** is used for linking. Multi-ROI processing (e.g., for FOV ROI tables) is not yet supported. +- Requires segmentation label maps to be provided for both the reference and alignment acquisitions. +- Matching is performed using an IoU threshold; objects below the threshold are not linked. +- Pixel sizes must match between the reference and alignment acquisitions for accurate registration. diff --git a/src/scmultiplex/dev/task_info/calculate_platymatch_registration.md b/src/scmultiplex/dev/task_info/calculate_platymatch_registration.md new file mode 100644 index 0000000..c3076a0 --- /dev/null +++ b/src/scmultiplex/dev/task_info/calculate_platymatch_registration.md @@ -0,0 +1,15 @@ +### Purpose +- Calculates point-cloud-based registration between segmentation images using **PlatyMatch**. +- Works well for **complex 3D registration**. +- Aligns sub-objects (e.g., nuclei) that belong to parent objects (e.g., organoids) by calculating **affine** and optionally **free-form deformation** transformations. +- Outputs linking tables of matched sub-objects and optionally saves transformation matrices to disk. + +### Outputs +- A **linking table** that maps sub-objects between reference and alignment rounds using affine and/or free-form deformation (FFD) transformations. +- Transformation matrices (optional), saved on disk for each object pair. + +### Limitations +- Only supports **single well ROI tables**; multi-ROI processing (e.g., FOV ROIs) is not yet implemented. +- Requires parent objects to be linked in a prior step using a **consensus linking table**. +- Assumes consistent pixel sizes between reference and alignment rounds for accurate registration. +- Relies on sufficient sub-object counts for alignment; regions with fewer than 3 sub-objects are skipped. diff --git a/src/scmultiplex/dev/task_info/create_manifest.py b/src/scmultiplex/dev/task_info/create_manifest.py new file mode 100644 index 0000000..72a2d07 --- /dev/null +++ b/src/scmultiplex/dev/task_info/create_manifest.py @@ -0,0 +1,12 @@ +"""Generate JSON schemas for tasks and write them to the Fractal manifest.""" + +from fractal_tasks_core.dev.create_manifest import create_manifest + +if __name__ == "__main__": + PACKAGE = "scmultiplex" + AUTHORS = "Nicole Repina, Enrico Tagliavini, Tim-Oliver Buchholz, Joel Luethi" + docs_link = "https://github.com/fmi-basel/gliberal-scMultipleX" + if docs_link: + create_manifest(package=PACKAGE, authors=AUTHORS, docs_link=docs_link) + else: + create_manifest(package=PACKAGE, authors=AUTHORS) diff --git a/src/scmultiplex/dev/task_info/expand_labels.md b/src/scmultiplex/dev/task_info/expand_labels.md new file mode 100644 index 0000000..5d17513 --- /dev/null +++ b/src/scmultiplex/dev/task_info/expand_labels.md @@ -0,0 +1,12 @@ +### Purpose +- Expands segmented **labels** in 2D or 3D images **without overlap**. +- Supports expansion by a fixed pixel distance or dynamically based on **label size**. +- Optionally masks expanded labels using **parent objects** to prevent spillover. +- Outputs an expanded label image and preserves non-overlapping object boundaries. + +### Outputs +- A new **expanded label image** saved with an `_expanded` suffix. + +### Limitations +- If masking by parent is enabled, the parent object label image must be provided. +- Expansion beyond object boundaries may be clipped, depending on the surrounding labels and image dimensions. diff --git a/src/scmultiplex/dev/task_info/feature_measurements.md b/src/scmultiplex/dev/task_info/feature_measurements.md new file mode 100644 index 0000000..851fd07 --- /dev/null +++ b/src/scmultiplex/dev/task_info/feature_measurements.md @@ -0,0 +1,12 @@ +### Purpose +- **Measures intensity and morphology features** from existing segmentation images in an OME-Zarr dataset. +- Computes advanced 3D morphology metrics, including surface area, using extended `regionprops` measurements. +- Supports both intensity-based and morphology-only measurements: + - If no input intensity channels are provided, the task calculates morphology features only. + - For intensity measurements, channels can be specified individually, allowing flexibility across different image inputs. +- Enables **measurements within masked objects** (e.g., measuring nuclei properties within organoids) by specifying an `input_ROI_table` that defines parent regions, such as organoid ROIs. + +### Limitations +- Currently tested only on image data in the **CZYX** format. +- Measurement accuracy and performance may depend on the spacing and resolution of input images. +- Does not support measurements at lower resolutions (e.g., beyond level 0). diff --git a/src/scmultiplex/dev/task_info/mesh_measurements.md b/src/scmultiplex/dev/task_info/mesh_measurements.md new file mode 100644 index 0000000..363b60b --- /dev/null +++ b/src/scmultiplex/dev/task_info/mesh_measurements.md @@ -0,0 +1,18 @@ +### Purpose +- Extracts detailed **shape features** from 3D meshes, including volume, surface area, solidity, concavity, and aspect ratio. +- Optionally calculates **Gaussian curvature** for mesh surfaces and **spherical harmonics** to decompose mesh geometry. +- Outputs feature tables, curvature meshes, and optional harmonic-reconstructed meshes. + +### Outputs +1. A **feature table** with extracted mesh measurements, including: + - Volume, surface area, aspect ratio, concavity, normalized surface area-to-volume ratio, and more. +2. Optional **spherical harmonic coefficients** and reconstruction error (MSE), saved as a separate table. +3. Optional **reconstructed meshes** from spherical harmonics saved as `.stl`. +4. Optional **Gaussian curvature meshes** saved as `.vtp` files in a new `curvature` folder. +5. Optional **convex hull** and **bounding box** meshes saved as `.vtp` files. + +### Limitations +- Requires pre-existing **.stl meshes** within the Zarr structure (e.g., generated by the **Surface Mesh Multiscale** task). +- Mesh files must match the **object labels** specified in the ROI table. +- Computational cost increases when enabling **Gaussian curvature** or **spherical harmonics** calculations. +- Mesh quality and accuracy depend on the input segmentation and mesh generation parameters. diff --git a/src/scmultiplex/dev/task_info/relabel_by_linking_consensus.md b/src/scmultiplex/dev/task_info/relabel_by_linking_consensus.md new file mode 100644 index 0000000..fca138d --- /dev/null +++ b/src/scmultiplex/dev/task_info/relabel_by_linking_consensus.md @@ -0,0 +1,14 @@ +### Purpose +- Relabels segmentation images and ROI tables in an OME-Zarr dataset based on a pre-calculated **consensus linking table**. +- Aligns object labels across multiplexing rounds to ensure consistency with the consensus object identities. +- Outputs new segmentation images and ROI tables with updated labels. +- Requires a valid **consensus linking table** as input, typically generated by the `Calculate Linking Consensus` task. +- Non-consensus objects are set to background and excluded from the outputs. + +### Outputs +- A **new segmentation image** where object labels match the consensus labels. +- A **relabelled ROI table** corresponding to the updated segmentation image, saved with a `_linked` suffix. + +### Limitations +- Only supports **single well ROI tables**; multi-ROI processing (e.g., field of view ROIs) is not yet implemented. +- Input segmentation images and ROI tables must match in terms of object labels; inconsistencies will cause errors. diff --git a/src/scmultiplex/dev/task_info/segment_by_intensity_threshold.md b/src/scmultiplex/dev/task_info/segment_by_intensity_threshold.md new file mode 100644 index 0000000..24bc119 --- /dev/null +++ b/src/scmultiplex/dev/task_info/segment_by_intensity_threshold.md @@ -0,0 +1,15 @@ +### Purpose +- Performs **full 3D object segmentation** of raw intensity images using intensity thresholding. +- Combines two intensity channels, applies **Gaussian smoothing** and **Canny edge detection** for refined masks. +- Filters out debris and neighboring objects by selecting the **largest connected component** within a masked region. +- Outputs a new 3D segmentation label image and an updated masking ROI table. + +### Outputs +- A **new 3D label image** stored in the dataset, with refined object segmentation. +- A corresponding **bounding-box ROI table** saved as `{output_label_name}_ROI_table`. + +### Limitations +- Requires pre-segmented 2D MIP-based ROI regions as input for masking. +- Supports intensity thresholding with either **Otsu's method** or a user-defined threshold. +- Assumes consistent image resolution and pixel intensities across channels. +- Regions with extreme intensity variations or overlapping objects may require manual parameter tuning for optimal results. diff --git a/src/scmultiplex/dev/task_info/spherical_harmonics_from_label_image.md b/src/scmultiplex/dev/task_info/spherical_harmonics_from_label_image.md new file mode 100644 index 0000000..2c484ad --- /dev/null +++ b/src/scmultiplex/dev/task_info/spherical_harmonics_from_label_image.md @@ -0,0 +1,13 @@ +### Purpose +- Computes **spherical harmonics** for 3D segmented objects in a label image using the **aics_shparam** library. +- Calculates and analyzes the **shape features** of objects, including reconstruction error. +- Outputs spherical harmonic coefficients and optionally saves reconstructed surface meshes. + +### Outputs +- A **feature table** containing spherical harmonic coefficients and reconstruction error (**MSE**) per object. +- Optionally, the **computed surface mesh** and the **reconstructed mesh** (from harmonics), saved as `.stl` files in a new `meshes` folder. + +### Limitations +- Input label image must contain 3D segmented objects; neighboring objects are removed by masking. +- The accuracy of spherical harmonics depends on the chosen **maximum degree (`lmax`)** and input label quality. +- Mesh reconstruction might smooth out fine details in highly complex shapes. diff --git a/src/scmultiplex/dev/task_info/surface_mesh_multiscale.md b/src/scmultiplex/dev/task_info/surface_mesh_multiscale.md new file mode 100644 index 0000000..7dbbe97 --- /dev/null +++ b/src/scmultiplex/dev/task_info/surface_mesh_multiscale.md @@ -0,0 +1,16 @@ +### Purpose +- Calculates **3D surface meshes** for parent objects (e.g., tissues, organoids) based on 3D child-level segmentation (e.g., nuclei). +- Optionally applies **multiscale label fusion** to estimate a smooth parent shape by merging child objects. +- Generates smoothened surface meshes using **VTK algorithms**, with optional mesh decimation for reduced complexity. +- Outputs 3D meshes in `.stl` or `.vtp` format and a new well label map in the dataset. + +### Outputs +- **Surface meshes** of parent objects, saved as `.stl` (single object) or `.vtp` (multi-object) files in the dataset’s `meshes` folder. +- A **new label map** containing fused child-level objects, saved in the OME-Zarr dataset (only if multiscale processing is enabled). +- A **bounding-box ROI table** corresponding to the new label map. + +### Limitations +- Requires pre-segmented child objects and a parent object ROI table. +- Multiscale processing requires a **parent label** for accurate object grouping and fusion. +- Label map outputs may have **overlaps clipped**, where higher-label IDs take precedence in dense regions. +- Mesh quality can vary with complex geometries; manual tuning of smoothing parameters may be needed for optimal results. diff --git a/src/scmultiplex/dev/task_list.py b/src/scmultiplex/dev/task_list.py index 29c349a..4c331e5 100644 --- a/src/scmultiplex/dev/task_list.py +++ b/src/scmultiplex/dev/task_list.py @@ -26,6 +26,7 @@ category="Registration", modality="HCS", tags=["multiplexing", "2D"], + docs_info="file:task_info/calculate_object_linking.md", ), CompoundTask( name="scMultiplex Calculate Linking Consensus", @@ -36,6 +37,7 @@ category="Registration", modality="HCS", tags=["multiplexing", "2D", "3D"], + docs_info="file:task_info/calculate_linking_consensus.md", ), CompoundTask( name="scMultiplex Relabel by Linking Consensus", @@ -46,6 +48,7 @@ category="Registration", modality="HCS", tags=["multiplexing", "2D", "3D"], + docs_info="file:task_info/relabel_by_linking_consensus.md", ), CompoundTask( name="scMultiplex Calculate Platymatch Registration", @@ -56,6 +59,7 @@ category="Registration", modality="HCS", tags=["multiplexing", "3D"], + docs_info="file:task_info/calculate_platymatch_registration.md", ), CompoundTask( name="scMultiplex Surface Mesh Multiscale", @@ -66,6 +70,7 @@ category="Image Processing", modality="HCS", tags=["3D", "mesh"], + docs_info="file:task_info/surface_mesh_multiscale.md", ), CompoundTask( name="scMultiplex Segment by Intensity Threshold", @@ -76,6 +81,7 @@ category="Segmentation", modality="HCS", tags=["Classical segmentation", "3D"], + docs_info="file:task_info/segment_by_intensity_threshold.md", ), CompoundTask( name="scMultiplex Spherical Harmonics from Label Image", @@ -86,6 +92,7 @@ category="Measurement", modality="HCS", tags=["3D"], + docs_info="file:task_info/spherical_harmonics_from_label_image.md", ), CompoundTask( name="scMultiplex Mesh Measurements", @@ -96,6 +103,7 @@ category="Measurement", modality="HCS", tags=["3D", "mesh", "morphology"], + docs_info="file:task_info/mesh_measurements.md", ), ParallelTask( name="scMultiplex Feature Measurements", @@ -103,11 +111,13 @@ meta={"cpus_per_task": 4, "mem": 16000}, category="Measurement", tags=["regionprops", "morphology", "intensity"], + docs_info="file:task_info/feature_measurements.md", ), ParallelTask( name="scMultiplex Expand Labels", executable="fractal/expand_labels.py", meta={"cpus_per_task": 4, "mem": 16000}, tags=["2D", "3D"], + docs_info="file:task_info/expand_labels.md", ), ]