Universal entry points

[AhmetCanSolak]

TASKLIST:

• ABC Universal reader output base classes #132
• OME-Zarr
• OME-TIFF
• ...

          > At this point I don't think a universal entry point for all the formats is strictly necessary.

I think that a limited version of a "universal entry point" for internal biohub formats is one the core value propositions of iohub. If we're requiring a user to know their data type and its corresponding API to access data/metadata, then I think adoption of iohub will be limited.

The current version of WaveorderReader in waveorder has been valuable to me because it serves as a universal entry point for compmicro's work. For example, when we started reading pycromanager datasets, @ieivanov added the PycromanagerReader class and adapted WaveorderReader to read these datasets with the existing API. I could continue to run WaveorderReader.shape and WaveorderReader.get_array with predictable results, and any unpredictable results were considered bugs and fixed.

I understand that there may be difficulty in the details. For example, PycromanagerReader.get_zarr might be incorrectly/poorly named, and some dataset types might support different lazy-loading operations (maybe .get_zarr is not one of the universal entry points?). But I still think that all of our datasets share some common properties and operations that users will want to perform regularly. I think this list of operations consists of

• what is the shape of the data in this dataset? (.shape)
• what is it's basic metadata? (if it's available) (.channel_names, .z_step_size, .dtype, etc)
• what are the actual values in this dataset? (.get_array)

Can we have a universal entry point that supports these operations?

Originally posted by @talonchandler in #31 (comment)

This deserves a dedicated discussion IMHO, that's why creating a separate issue here.

Moving forward I think we should find ways to engineer a solution that provides a more unified API to the end user. Particularly for adoption of iohub across Biohub, I think this is crucial. Providing list of aforementioned operations(by @talonchandler ) on each dataset is a great start. But I think there is more than that we can do. Like:

• Currently we are implementing readers and writers, but perhaps we can engineer a single dataset class that can handle reading and writing appropriately? and can help us removing redundancies like creating writers from readers and so on.
• We can provide functional APIs like imread/imwrite in skimage.io and help scripting users to adopt iohub quicker?
• We can provide a separated metadata API which can enable iohub to be used for inspection before reading different imaging datasets.

This is merely a starting point for universal entry points discussions, looking forward to read everyone's input.

[mattersoflight]

We do need a unified reader module for the diverse datasets we have, which may or may not be a universal entry point. We have accumulated significant technical debt in the form of a diversity of data formats. One way to prevent further accumulation of technical debt is to read the legacy formats (which typically vary in terms of the hierarchy of groups, order of dimensions in ND arrays, and metadata format), but write only with the new writer implemented in iohub.

@ziw-liu after #31, let's discuss how to integrate readers implemented in waveOrder and dexp in iohub.

We will need to divide and conquer the work of adding support for the different formats.

[ziw-liu]

@AhmetCanSolak Thanks for moving this discussion over.

I also mentioned the possibility of something like skimage.io.imread during an offline meeting. And I think this functional entry point may alleviate some of the OOP overhead/weirdness we currently have in the code base. With limited refactoring it can be a function that does the format guessing/dispatching and returns a format-specific reader object (whose type is a child of the abstract ReaderBase that provides a mostly uniform interface) as the WaveorderReader does, but without the extra layer of API delegation.

For the 'universal dataset class' I feel that it cannot and probably should not be feature-complete for the heterogeneous format space we have. And there is a lot to learn from aicsimageio, which attempts to provide a universal interface to many more biomedical imaging data formats.

[ziw-liu]

I've started working on the imread idea in #71. Still WIP but early-stage input is very welcome!

[talonchandler]

@ziw-liu and I just met to discuss our plan for imread, especially wrt #90. Should imread provide a universal entry point that returns different objects depending on the underlying file?

We're both concerned that this will lead to an API that is destined to change. If imread is a thin wrapper on the old reader.__init__ and the new open_ome_zarr, then iohub's users will need to handle both of these cases which removes most of the value of having a universal API.

We discussed the pathway to a universal API, and we agreed that there's a lot of engineering work remaining. @ziw-liu expects the ReaderBase class will need to be rewritten, and all of the child classes will need to be reworked before we can have an API that is anywhere close to universal.

Given these constraints and our release timeline, we're now leaning towards having iohub info be our human-readable "universal entry point". We can quite easily make iohub info work for every dataset, and in the iohub info output we can print two lines of code that show the user how to open the dataset in question. For example,

iohub info my.ome.tif

would print

***shape info here***

Open this data set with the following lines:
$ python
>>> from iohub.reader import Reader
>>> dataset = Reader('./my.ome.tif')
>>> tczyx_array = dataset.get_position(0) # or possibly an iteration through positions

while running

iohub info my.ome.zarr

would print

***shape info here***

Open this data set with:
$ python
>>> from iohub.ngff import open_ome_zarr
>>> dataset = open_ome_zarr'./my.ome.zarr')
>>> tczyx_array = dataset["0"] # or possibly an iteration through positions

In many ways this solution is a bandaid. But I think it provides the shortest and simplest path for users to (1) see if iohub will work for their dataset, and (2) find the relevant usage API that lets them access their data in a script/package. I also think that it is an appropriate solution for an 0.1 release that is attempting to unify a large existing codebase that is already supporting many use cases.

[AhmetCanSolak]

This and #92 can be great to talk on next iohub meeting, I will add to the agenda.