Universal API implementations for Micro-Manager OME-TIFF and NDTiff

.github/workflows/pr.yml

@@ -30,8 +30,8 @@ jobs:
           pip install black
       - name: Check code styling with Black
         run: |
-          black --diff -S -t py39 iohub
-          black --check -S -t py39 iohub
+          black --diff -S -t py310 iohub
+          black --check -S -t py310 iohub
 
   lint:
     name: Lint Check

.gitignore

@@ -81,6 +81,7 @@ instance/
 # Sphinx documentation
 docs/_build/
 docs/source/auto_examples/
+docs/source/sg_execution_times.rst
 
 # PyBuilder
 target/

README.md

@@ -100,9 +100,9 @@ and the [example scripts](https://github.com/czbiohub-sf/iohub/tree/main/example
 Read a directory containing a TIFF dataset:
 
 ```py
-from iohub import read_micromanager
+from iohub import read_images
 
-reader = read_micromanager("/path/to/data/")
+reader = read_images("/path/to/data/")
 print(reader.shape)
 ```
 

docs/source/api/mm_converter.rst

@@ -11,3 +11,4 @@ Convert TIFF to OME-Zarr
 
 .. autoclass:: TIFFConverter
    :members:
+   :special-members: __call__

docs/source/api/mm_ometiff_reader.rst

@@ -1,8 +1,12 @@
 Read MMStack OME-TIFF
 =====================
 
-.. currentmodule:: iohub.multipagetiff
+.. currentmodule:: iohub.mmstack
 
-.. autoclass:: MicromanagerOmeTiffReader
+.. autoclass:: MMStack
     :members:
     :inherited-members:
+
+.. autoclass:: MMOmeTiffFOV
+    :members:
+    :inherited-members:

docs/source/api/mm_reader.rst

@@ -1,6 +1,6 @@
-Read Micro-Manager datasets
-===========================
+Read multi-FOV datasets
+=======================
 
 .. currentmodule:: iohub
 
-.. autofunction:: read_micromanager
+.. autofunction:: read_images

docs/source/api/mm_sequence_reader.rst

@@ -1,7 +1,7 @@
 Read MM TIFF sequence
 =====================
 
-.. currentmodule:: iohub.singlepagetiff
+.. currentmodule:: iohub._deprecated.singlepagetiff
 
 .. autoclass:: MicromanagerSequenceReader
     :members:

docs/source/api/ndtiff.rst

@@ -3,6 +3,10 @@ Read NDTiff
 
 .. currentmodule:: iohub.ndtiff
 
-.. autoclass:: NDTiffReader
+.. autoclass:: NDTiffDataset
     :members:
     :inherited-members:
+
+.. autoclass:: NDTiffFOV
+    :members:
+    :inherited-members:

docs/source/api/ngff.rst

@@ -6,8 +6,6 @@ OME-NGFF (OME-Zarr)
 Convenience
 -----------
 
-`open_ome_zarr`
-^^^^^^^^^^^^^^^
 .. autofunction:: open_ome_zarr
 
 
@@ -16,25 +14,14 @@ NGFF Nodes
 
 .. currentmodule:: iohub.ngff
 
-
-`NGFFNode`
-^^^^^^^^^^
-
 .. autoclass:: NGFFNode
     :members:
 
-`Position`
-^^^^^^^^^^
 .. autoclass:: Position
     :members:
 
-
-`TiledPosition`
-^^^^^^^^^^^^^^^
 .. autoclass:: TiledPosition
     :members:
 
-`Plate`
-^^^^^^^
 .. autoclass:: Plate
     :members:

docs/source/api/upti.rst

@@ -1,7 +1,7 @@
 Read PTI TIFF
 =============
 
-.. currentmodule:: iohub.upti
+.. currentmodule:: iohub._deprecated.upti
 
 .. autoclass:: UPTIReader
     :members:

docs/source/conf.py

@@ -124,7 +124,15 @@
         "json_url": json_url,
         "version_match": version_match,
     },
-    "navbar_end": ["theme-switcher", "version-switcher", "navbar-icon-links"],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/czbiohub-sf/iohub",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+        }
+    ],
+    "navbar_end": ["theme-switcher", "navbar-icon-links", "version-switcher"],
 }
 
 # Add any paths that contain custom themes here, relative to this directory.

iohub/__init__.py

@@ -1,12 +1,22 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
+"""
+iohub
+=====
 
-"""iohub
 N-dimensional bioimaging data I/O with OME metadata in Python
 """
 
+import logging
+import os
 
 from iohub.ngff import open_ome_zarr
-from iohub.reader import read_micromanager
+from iohub.reader import read_images
+
+__all__ = ["open_ome_zarr", "read_images"]
+
+
+_level = os.environ.get("IOHUB_LOG_LEVEL", logging.INFO)
+if str(_level).isdigit():
+    _level = int(_level)
 
-__all__ = ["open_ome_zarr", "read_micromanager"]
+logging.basicConfig()
+logging.getLogger(__name__).setLevel(_level)

iohub/_deprecated/__init__.py

@@ -0,0 +1 @@
+"""Deprecated modules"""

iohub/reader_base.py → iohub/_deprecated/reader_base.py

@@ -30,17 +30,21 @@ def shape(self):
         return self.frames, self.channels, self.slices, self.height, self.width
 
     @property
-    def mm_meta(self):
+    def micromanager_metadata(self) -> dict | None:
         return self._mm_meta
 
-    @mm_meta.setter
-    def mm_meta(self, value):
+    @micromanager_metadata.setter
+    def micromanager_metadata(self, value):
         if not isinstance(value, dict):
             raise TypeError(
                 f"Type of `mm_meta` should be `dict`, got `{type(value)}`."
             )
         self._mm_meta = value
 
+    @property
+    def micromanager_summary(self) -> dict | None:
+        return self._mm_meta.get("Summary", None)
+
     @property
     def stage_positions(self):
         return self._stage_positions

iohub/singlepagetiff.py → iohub/_deprecated/singlepagetiff.py

@@ -9,7 +9,7 @@
 import tifffile as tiff
 import zarr
 
-from iohub.reader_base import ReaderBase
+from iohub._deprecated.reader_base import ReaderBase
 
 
 class MicromanagerSequenceReader(ReaderBase):
@@ -91,9 +91,9 @@ def _set_mm_meta(self, one_pos):
         # pull one metadata sample and extract experiment dimensions
         metadata_path = os.path.join(one_pos, "metadata.txt")
         with open(metadata_path, "r") as f:
-            self.mm_meta = json.load(f)
+            self._mm_meta = json.load(f)
 
-        mm_version = self.mm_meta["Summary"]["MicroManagerVersion"]
+        mm_version = self._mm_meta["Summary"]["MicroManagerVersion"]
         if mm_version == "1.4.22":
             self._mm1_meta_parser()
         elif "beta" in mm_version:
@@ -402,12 +402,12 @@ def _mm1_meta_parser(self):
         -------
 
         """
-        self.z_step_size = self.mm_meta["Summary"]["z-step_um"]
-        self.width = self.mm_meta["Summary"]["Width"]
-        self.height = self.mm_meta["Summary"]["Height"]
-        self.frames = self.mm_meta["Summary"]["Frames"]
-        self.slices = self.mm_meta["Summary"]["Slices"]
-        self.channels = self.mm_meta["Summary"]["Channels"]
+        self.z_step_size = self._mm_meta["Summary"]["z-step_um"]
+        self.width = self._mm_meta["Summary"]["Width"]
+        self.height = self._mm_meta["Summary"]["Height"]
+        self.frames = self._mm_meta["Summary"]["Frames"]
+        self.slices = self._mm_meta["Summary"]["Slices"]
+        self.channels = self._mm_meta["Summary"]["Channels"]
 
     def _mm2beta_meta_parser(self):
         """
@@ -418,14 +418,14 @@ def _mm2beta_meta_parser(self):
         -------
 
         """
-        self.z_step_size = self.mm_meta["Summary"]["z-step_um"]
+        self.z_step_size = self._mm_meta["Summary"]["z-step_um"]
         self.width = int(
-            self.mm_meta["Summary"]["UserData"]["Width"]["PropVal"]
+            self._mm_meta["Summary"]["UserData"]["Width"]["PropVal"]
         )
         self.height = int(
-            self.mm_meta["Summary"]["UserData"]["Height"]["PropVal"]
+            self._mm_meta["Summary"]["UserData"]["Height"]["PropVal"]
         )
-        self.time_stamp = self.mm_meta["Summary"]["StartTime"]
+        self.time_stamp = self._mm_meta["Summary"]["StartTime"]
 
     def _mm2gamma_meta_parser(self):
         """
@@ -436,18 +436,18 @@ def _mm2gamma_meta_parser(self):
         -------
 
         """
-        keys_list = list(self.mm_meta.keys())
+        keys_list = list(self._mm_meta.keys())
         if "FrameKey-0-0-0" in keys_list[1]:
-            roi_string = self.mm_meta[keys_list[1]]["ROI"]
+            roi_string = self._mm_meta[keys_list[1]]["ROI"]
             self.width = int(roi_string.split("-")[2])
             self.height = int(roi_string.split("-")[3])
         elif "Metadata-" in keys_list[2]:
-            self.width = self.mm_meta[keys_list[2]]["Width"]
-            self.height = self.mm_meta[keys_list[2]]["Height"]
+            self.width = self._mm_meta[keys_list[2]]["Width"]
+            self.height = self._mm_meta[keys_list[2]]["Height"]
         else:
             raise ValueError("Metadata file incompatible with metadata reader")
 
-        self.z_step_size = self.mm_meta["Summary"]["z-step_um"]
-        self.frames = self.mm_meta["Summary"]["Frames"]
-        self.slices = self.mm_meta["Summary"]["Slices"]
-        self.channels = self.mm_meta["Summary"]["Channels"]
+        self.z_step_size = self._mm_meta["Summary"]["z-step_um"]
+        self.frames = self._mm_meta["Summary"]["Frames"]
+        self.slices = self._mm_meta["Summary"]["Slices"]
+        self.channels = self._mm_meta["Summary"]["Channels"]

iohub/upti.py → iohub/_deprecated/upti.py

@@ -6,11 +6,10 @@
 import tifffile as tiff
 import zarr
 
-from iohub.reader_base import ReaderBase
+from iohub._deprecated.reader_base import ReaderBase
 
 
 class UPTIReader(ReaderBase):
-
     """
     Reader for UPTI raw data.
     Accepts both new live UPTI and older UPTI format.

iohub/zarrfile.py → iohub/_deprecated/zarrfile.py

@@ -9,11 +9,12 @@
 import numpy as np
 import zarr
 
-from iohub.reader_base import ReaderBase
+from iohub._deprecated.reader_base import ReaderBase
 
+_logger = logging.getLogger(__name__)
 
-class ZarrReader(ReaderBase):
 
+class ZarrReader(ReaderBase):
     """
     .. deprecated:: 0.0.1
         `ZarrReader` will be removed in future iohub releases,
@@ -30,7 +31,7 @@ def __init__(
     ):
         super().__init__()
 
-        logging.warning(
+        _logger.warning(
             DeprecationWarning(
                 "`iohub.zarrfile.ZarrReader` is deprecated "
                 "and will be removed in the future. "
@@ -94,7 +95,7 @@ def __init__(
         try:
             self._set_mm_meta()
         except TypeError:
-            self.mm_meta = dict()
+            self.micromanager_metadata = {}
 
         self._generate_hcs_meta()
 
@@ -187,37 +188,37 @@ def _set_mm_meta(self):
         -------
 
         """
-        self.mm_meta = self.root.attrs.get("Summary")
-        mm_version = self.mm_meta["MicroManagerVersion"]
+        self._mm_meta = self.root.attrs.get("Summary")
+        mm_version = self._mm_meta["MicroManagerVersion"]
 
         if mm_version != "pycromanager":
             if "beta" in mm_version:
-                if self.mm_meta["Positions"] > 1:
+                if self._mm_meta["Positions"] > 1:
                     self.stage_positions = []
 
-                    for p in range(len(self.mm_meta["StagePositions"])):
+                    for p in range(len(self._mm_meta["StagePositions"])):
                         pos = self._simplify_stage_position_beta(
-                            self.mm_meta["StagePositions"][p]
+                            self._mm_meta["StagePositions"][p]
                         )
                         self.stage_positions.append(pos)
 
             # elif mm_version == '1.4.22':
-            #     for ch in self.mm_meta['ChNames']:
+            #     for ch in self._mm_meta['ChNames']:
             #         self.channel_names.append(ch)
             else:
-                if self.mm_meta["Positions"] > 1:
+                if self._mm_meta["Positions"] > 1:
                     self.stage_positions = []
 
-                    for p in range(self.mm_meta["Positions"]):
+                    for p in range(self._mm_meta["Positions"]):
                         pos = self._simplify_stage_position(
-                            self.mm_meta["StagePositions"][p]
+                            self._mm_meta["StagePositions"][p]
                         )
                         self.stage_positions.append(pos)
 
-                # for ch in self.mm_meta['ChNames']:
+                # for ch in self._mm_meta['ChNames']:
                 #     self.channel_names.append(ch)
 
-        self.z_step_size = self.mm_meta["z-step_um"]
+        self.z_step_size = self._mm_meta["z-step_um"]
 
     def _get_channel_names(self):
         well = self.hcs_meta["plate"]["wells"][0]["path"]