Merge pull request #222 from czbiohub-sf/unified-api

Unified API for Micro-manager readers

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: Build and deploy docs
+name: documentation
 
 on:
   push:
@@ -22,7 +22,7 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
-        with: 
+        with:
           fetch-depth: 0
       - name: Setup Pages
         id: pages
@@ -45,7 +45,7 @@ jobs:
       - name: Upload build artifacts
         uses: actions/upload-pages-artifact@v1
         with:
-          path: './docs/build/html'
+          path: "./docs/build/html"
 
   deploy:
     environment:

.github/workflows/pr.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     branches:
       - main
+      - unified-api
 
 jobs:
   style:
@@ -29,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

@@ -27,7 +27,7 @@ used at the Biohub and in the broader imaging community.
 
 ### Installation
 
-Install a pre-release of iohub with pip:
+Install a released version of iohub from PyPI with pip:
 
 ```sh
 pip install iohub
@@ -100,10 +100,10 @@ and the [example scripts](https://github.com/czbiohub-sf/iohub/tree/main/docs/ex
 Read a directory containing a TIFF dataset:
 
 ```py
-from iohub import read_micromanager
+from iohub import read_images
 
-reader = read_micromanager("/path/to/data/")
-print(reader.shape)
+reader = read_images("/path/to/data/")
+print(reader)
 ```
 
 ## Why iohub?

docs/source/_static/switcher.json

@@ -2,5 +2,9 @@
     {
         "version": "latest",
         "url": "/main/index.html"
+    },
+    {
+        "version": "v0.1.0",
+        "url": "/v0.1.0/index.html"
     }
-]
+]

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,7 +6,7 @@
 import tifffile as tiff
 import zarr
 
-from iohub.reader_base import ReaderBase
+from iohub._deprecated.reader_base import ReaderBase
 
 
 class UPTIReader(ReaderBase):