ngio for fractal-tasks-core: Overview

[jluethi]

This issue is meant as an overview for the effort to transition fractal-tasks-core to use ngio.

The overall strategy is:

1. Add an ngio dependency to fractal-tasks-core
2. Start using ngio in different tasks until all tasks depend on ngio for OME-Zarr reading & writing, label reading & writing & table reading & writing
3. Deprecate the respective library functions in fractal-tasks-core
4. Release a fractal-tasks-core 2.0.0 version where we remove those library functions

---

Nomenclature below: Top-level TODOs are the tasks. Fix sub-items are must fix issues in the task: We want to see that the ngio refactor fixes this issue. Review sub-items are minor issues we may be able to tackle during the refactor.

Tasks to transition to using ngio:

Converters

• Convert Cellvoyager to OME-Zarr
  • Review Normalize plate names in Cellvoyager converter #843
  • Review Update zenodo dataset, setting channel.active to True #823
• Convert Cellvoyager Multiplexing to OME-Zarr
  • Review Normalize plate names in Cellvoyager converter #843
  • Review Reproduce issue with file paths ending / for Convert Cellvoyager Multiplexing to OME-Zarr #845
  • Review Ensure correct ordering of acquisition in multiplexing converter #819

Tasks that write new OME-Zarr images

• Project Image (HCS Plate): in https://github.com/fractal-analytics-platform/fractal-tasks-core/blob/main/fractal_tasks_core/tasks/projection.py
  • Fix Make projection task work with zyx data #840
  • Review Review image-plate attribute of MIP task #841
  • Overwrite false not supported correctly in ngio
  • Improve how omero metadata is handled in ngio
  • Replace use of NgffImageMeta usage with ngio (load_NgffImageMeta)
  • Replace direct zarr operations (zarr.open_group etc.) with ngio
  • Replace dask operations for array access with ngio
  • Replace writing operations with ngio
  • Replace pyramid building with ngio
• Illumination Correction
  • Should be simple
• Apply Registration to Image
  • Replace use of NgffImageMeta usage with ngio (load_NgffImageMeta)
  • In write_registered_zarr, replace metadata access & image loading & writing with ngio
  • In write_registered_zarr, replace pyramid building with ngio
  • Careful with race condition handling (=> @lorenzocerrone & @jluethi review together first)

Tasks that write tables

• Calculate Registration (image-based)
  • Review Make calculate registration more robust in table column handling on reruns #851
  • Mostly simple, but complex well metadata parsing (ignore for initial transition)
• Find Registration Consensus
  • Should be simple

Other tasks:

• Import OME-Zarr
  • In _process_single_image: Replace use of NgffImageMeta usage with ngio
  • In _process_single_image: Replace ROI copying & table writing functionality with ngio

Not a goal for the moment: Handle the well & plate metadata with ngio

Currently blocked because we're waiting for feature X in ngio

Waiting for masking ROI writing

• Cellpose Segmentation
  • Fix [ngio] Refactor masked_loading_wrapper logic to do relabeling in the masking step #787
  • Review Make Cellpose task work for OME-Zarrs without pyramids #742
  • Remove overlap check that only generates a warning: Review/optimize use of get_overlapping_pairs_3D in Cellpose task #779

Task with other goals

• Napari Workflows Wrapper
  • Move napari workflows task into its own repo: Move napari workflows wrapper task into its own repository #849
  • Add a simpler scikit-image based measurement task to the fractal-tasks-core repo
  • Move these issue to new napari workflows repo:
    • [napari workflows] Review 2D & 3D image handling in napari workflows #411
    • [napari workflows] Support processing within masked ROIs for napari workflows #356
    • [napari workflows] Add napari-apoc to core task #352
    • [napari-workflows] Create bounding-box ROIs for napari-workflows-generated labels #349
    • [napari-workflows] Mixed 2D/3D workflows #186
    • [napari-workflows] Fix regionprops warning #183
    • [napari-workflows] Measurement function that only outputs selected labels #181

Additional issues:

• Review Move to anndata 0.11 #833 & Check anndata PendingDeprecationWarning #463
• Test e.g. in the Cellpose task that label upsampling of a masking label image works when the dimensions don't easily match: ROI upsampling issue when original image resolution is not divisible by 2 #771
• Review that table copying in illumination correction, apply registration etc. are now all using ngio features for this: Centralize copying of tables functionality #725
• Review Review NGFF models & Fractal OME-Zarr models #681
• Review that we're not sensitive to trailing slashes in zarr_urls anymore: Review whether zarr_urls have trailing slash or not #677 (maybe still an issue in some fractal-tasks-core helper functions?)
• Review how ROI tables & their indices now look: Masking ROI tables should use the labels as index of the table as well #672
• Test core tasks with OME-Zarrs that have singleton T dimensions: Better support for OME-Zarr with singleton T dimension #663
• Review that try-except error handling for Zarr operations has been moved into ngio: Remove zarr-errors handling from tasks #541
• Review that tasks support actual workflows with time data (e.g. run cellpose & measurements across all timepoints of an existing OME-Zarr with timepoints): Support time data #169
• How are we handling global scale transformations in ngio? Support global scale transformations at the multiscale level #50

Deprecate

• Deprecate prepare_label_group: Refactor prepare_label_group? #634
• Deprecate is_ROI_table_valid: Refactor is_ROI_table_valid #633
• Deprecate get_pixel_sizes_zyx: Improve error handling when get_pixel_sizes_zyx is called with a non-existing level  #577

Issues Joel needs to review further

Not sure yet what exactly is needed now to close these issues

• Update ROI_table_names argument of copy_ome_zarr #448
• Review that the masked loading now fulfills requirements described here: Make masked-loading helper functions more general #340
• Review mixed dimensionality support requirements: Support arrays of mixed-dimensionality #150

---

Issues related to ngio that should get tackled later (e.g. after 2.0.0 release):

• Parallel processing of ROIs within tasks: Options of processing ROIs in parallel within wells. #44
• Parallelize illumination correction across channels: Illumination Correction with Channel parallelisation #687 (either within the task or across a compound task)