Add ND2 reader, pixel size extraction with ZYX ordering, and OME-NGFF compatible axes for all image formats

examples/notebooks/loading_data.ipynb

@@ -0,0 +1,300 @@
+{
+ "cells": [
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "### Examples for loading data using the ImageOpener class\n",
+    "\n",
+    "**Note:** If you've made code changes to clearex, run the next cell to reload the module:"
+   ],
+   "id": "75ca24c94a6de263"
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2026-01-04T13:08:43.391281834Z",
+     "start_time": "2026-01-04T13:08:41.874159158Z"
+    }
+   },
+   "cell_type": "code",
+   "source": [
+    "from pathlib import Path\n",
+    "\n",
+    "# OPTIONAL: Reload module to pick up code changes\n",
+    "# Only run this if you've edited the clearex source code\n",
+    "import importlib\n",
+    "import clearex.io.read\n",
+    "importlib.reload(clearex.io.read)"
+   ],
+   "id": "35a13da2a9189a62",
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<module 'clearex.io.read' from '/project/bioinformatics/Danuser_lab/Dean/dean/git/clearex/src/clearex/io/read.py'>"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "execution_count": 1
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2026-01-04T13:01:14.348628027Z",
+     "start_time": "2026-01-04T13:01:14.343427809Z"
+    }
+   },
+   "cell_type": "code",
+   "source": [
+    "from clearex.io.read import ImageOpener\n",
+    "reader = ImageOpener()"
+   ],
+   "id": "2d718ad83b4fbd2b",
+   "outputs": [],
+   "execution_count": 8
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": "### Troubleshooting cell - check if files exist and what type they are",
+   "id": "2e2fcb6884f2aa1f"
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2026-01-04T12:54:20.103374315Z",
+     "start_time": "2026-01-04T12:54:20.084388894Z"
+    }
+   },
+   "cell_type": "code",
+   "source": [
+    "# Check file/directory status\n",
+    "paths_to_check = [\n",
+    "    \"/archive/bioinformatics/Danuser_lab/Dean/dean/2024-11-26-yuanyuan/fused.n5\",\n",
+    "    \"/archive/bioinformatics/Danuser_lab/Dean/dean/2023-11-13-Nicole/488myosin_561nuclear_647rfp/2023-11-08/Cell_001/CH00_000000.h5\",\n",
+    "    \"/archive/bioinformatics/Danuser_lab/Dean/dean/2024-05-21-tiling/cell5_fused_tp_0_ch_0.zarr\",\n",
+    "]\n",
+    "\n",
+    "for path_str in paths_to_check:\n",
+    "    p = Path(path_str)\n",
+    "    print(f\"{p.name}:\")\n",
+    "    print(f\"  Exists: {p.exists()}\")\n",
+    "    print(f\"  Is file: {p.is_file()}\")\n",
+    "    print(f\"  Is dir: {p.is_dir()}\")\n",
+    "    print(f\"  Suffix: {p.suffix}\")\n",
+    "    print()"
+   ],
+   "id": "4a116e8acf32c0c0",
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "fused.n5:\n",
+      "  Exists: True\n",
+      "  Is file: False\n",
+      "  Is dir: True\n",
+      "  Suffix: .n5\n",
+      "\n",
+      "CH00_000000.h5:\n",
+      "  Exists: True\n",
+      "  Is file: True\n",
+      "  Is dir: False\n",
+      "  Suffix: .h5\n",
+      "\n",
+      "cell5_fused_tp_0_ch_0.zarr:\n",
+      "  Exists: True\n",
+      "  Is file: False\n",
+      "  Is dir: True\n",
+      "  Suffix: .zarr\n",
+      "\n"
+     ]
+    }
+   ],
+   "execution_count": 3
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2026-01-04T12:55:35.864905675Z",
+     "start_time": "2026-01-04T12:54:38.365907936Z"
+    }
+   },
+   "cell_type": "code",
+   "source": [
+    "# ND2 file example\n",
+    "nd2_path = \"/archive/bioinformatics/Danuser_lab/Dean/Seweryn/SoRa/s_green_EEA1/1_non_expanded/full_large_8_sytox_EEA1_002.nd2\"\n",
+    "data, info = reader.open(nd2_path)\n",
+    "print(f\"ND2 pixel size: {info.pixel_size}\")  # (0.9, 0.325, 0.325) µm"
+   ],
+   "id": "ee2276296eca1b46",
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "ND2 pixel size: (0.9, 0.325, 0.325)\n"
+     ]
+    }
+   ],
+   "execution_count": 4
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2026-01-04T12:56:18.440127781Z",
+     "start_time": "2026-01-04T12:56:17.514223975Z"
+    }
+   },
+   "cell_type": "code",
+   "source": [
+    "# TIFF file example - extracts Z spacing from ImageDescription JSON\n",
+    "tiff_path = \"/archive/bioinformatics/Danuser_lab/Dean/dean/2024-10-18-yuanyuan/38_100umrange_0.2umstep_Cell_004/CH00_000000.tiff\"\n",
+    "data_tiff, info_tiff = reader.open(tiff_path)\n",
+    "print(f\"TIFF pixel size: {info_tiff.pixel_size}\")  # (0.2, 0.167, 0.167) µm"
+   ],
+   "id": "5a95ea350ed12536",
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "TIFF pixel size: (0.2, 0.1670001075060573, 0.1670001075060573)\n"
+     ]
+    }
+   ],
+   "execution_count": 5
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2026-01-04T18:10:10.857155914Z",
+     "start_time": "2026-01-04T18:10:10.809669800Z"
+    }
+   },
+   "cell_type": "code",
+   "source": [
+    "importlib.reload(clearex.io.read)\n",
+    "from clearex.io.read import ImageOpener\n",
+    "reader = ImageOpener()\n",
+    "n5_path = \"/archive/bioinformatics/Danuser_lab/Dean/dean/2024-11-26-yuanyuan/fused.n5/\"\n",
+    "data_n5, info_n5 = reader.open(n5_path, prefer_dask=True)\n",
+    "print(info_n5.pixel_size)\n",
+    "print(data_n5.shape)"
+   ],
+   "id": "76cf6052bd3fca69",
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Reader N5Reader claims the file.\n",
+      "None\n",
+      "(1401, 13108, 13109)\n"
+     ]
+    }
+   ],
+   "execution_count": 37
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2026-01-04T18:19:14.387967971Z",
+     "start_time": "2026-01-04T18:15:19.468743033Z"
+    }
+   },
+   "cell_type": "code",
+   "source": [
+    "h5_path = \"/archive/bioinformatics/Danuser_lab/Dean/dean/2023-11-13-Nicole/NA/488myosin_561nuclear_647rfp/2023-11-08/Cell_001/CH00_000000.h5\"\n",
+    "data_h5, info_h5 = reader.open(h5_path)\n",
+    "info_h5.pixel_size"
+   ],
+   "id": "609d1ecb0dd284dc",
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Reader HDF5Reader claims the file.\n",
+      "Reader HDF5Reader failed to open the file: [Errno 13] Unable to synchronously open file (file read failed: time = Sun Jan  4 12:19:09 2026\n",
+      ", filename = '/archive/bioinformatics/Danuser_lab/Dean/dean/2023-11-13-Nicole/NA/488myosin_561nuclear_647rfp/2023-11-08/Cell_001/CH00_000000.h5', file descriptor = 56, errno = 13, error message = 'Permission denied', buf = 0x7ffc76276f48, total read size = 8, bytes this sub-read = 8, offset = 0)\n"
+     ]
+    },
+    {
+     "ename": "ValueError",
+     "evalue": "No suitable reader found for: /archive/bioinformatics/Danuser_lab/Dean/dean/2023-11-13-Nicole/NA/488myosin_561nuclear_647rfp/2023-11-08/Cell_001/CH00_000000.h5",
+     "output_type": "error",
+     "traceback": [
+      "\u001B[31m---------------------------------------------------------------------------\u001B[39m",
+      "\u001B[31mValueError\u001B[39m                                Traceback (most recent call last)",
+      "\u001B[36mCell\u001B[39m\u001B[36m \u001B[39m\u001B[32mIn[41]\u001B[39m\u001B[32m, line 2\u001B[39m\n\u001B[32m      1\u001B[39m h5_path = \u001B[33m\"\u001B[39m\u001B[33m/archive/bioinformatics/Danuser_lab/Dean/dean/2023-11-13-Nicole/NA/488myosin_561nuclear_647rfp/2023-11-08/Cell_001/CH00_000000.h5\u001B[39m\u001B[33m\"\u001B[39m\n\u001B[32m----> \u001B[39m\u001B[32m2\u001B[39m data_h5, info_h5 = \u001B[43mreader\u001B[49m\u001B[43m.\u001B[49m\u001B[43mopen\u001B[49m\u001B[43m(\u001B[49m\u001B[43mh5_path\u001B[49m\u001B[43m)\u001B[49m\n\u001B[32m      3\u001B[39m info_h5.pixel_size\n",
+      "\u001B[36mFile \u001B[39m\u001B[32m/project/bioinformatics/Danuser_lab/Dean/dean/git/clearex/src/clearex/io/read.py:1897\u001B[39m, in \u001B[36mImageOpener.open\u001B[39m\u001B[34m(self, path, prefer_dask, chunks, **kwargs)\u001B[39m\n\u001B[32m   1895\u001B[39m     error_msg += \u001B[33mf\u001B[39m\u001B[33m\"\u001B[39m\u001B[33m  - \u001B[39m\u001B[38;5;132;01m{\u001B[39;00mreader_name\u001B[38;5;132;01m}\u001B[39;00m\u001B[33m: \u001B[39m\u001B[38;5;132;01m{\u001B[39;00merror\u001B[38;5;132;01m}\u001B[39;00m\u001B[38;5;130;01m\\n\u001B[39;00m\u001B[33m\"\u001B[39m\n\u001B[32m   1896\u001B[39m logger.error(msg=error_msg)\n\u001B[32m-> \u001B[39m\u001B[32m1897\u001B[39m \u001B[38;5;28;01mraise\u001B[39;00m \u001B[38;5;167;01mValueError\u001B[39;00m(\u001B[33mf\u001B[39m\u001B[33m\"\u001B[39m\u001B[33mNo suitable reader found for: \u001B[39m\u001B[38;5;132;01m{\u001B[39;00mp\u001B[38;5;132;01m}\u001B[39;00m\u001B[33m\"\u001B[39m)\n",
+      "\u001B[31mValueError\u001B[39m: No suitable reader found for: /archive/bioinformatics/Danuser_lab/Dean/dean/2023-11-13-Nicole/NA/488myosin_561nuclear_647rfp/2023-11-08/Cell_001/CH00_000000.h5"
+     ]
+    }
+   ],
+   "execution_count": 41
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2026-01-04T18:11:09.752524718Z",
+     "start_time": "2026-01-04T18:11:02.637067432Z"
+    }
+   },
+   "cell_type": "code",
+   "source": [
+    "zarr_path = \"/archive/bioinformatics/Danuser_lab/Dean/dean/2024-05-21-tiling/cell5_fused_tp_0_ch_0.zarr\"\n",
+    "data_zarr, info_zarr = reader.open(zarr_path)\n",
+    "info_zarr.pixel_size\n",
+    "print(data_zarr.shape)"
+   ],
+   "id": "75008c08db1cd093",
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Reader ZarrReader claims the file.\n",
+      "(1, 1, 65, 5734, 9550)\n"
+     ]
+    }
+   ],
+   "execution_count": 39
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": null,
+   "source": "",
+   "id": "de201bd830e2a842"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pyproject.toml

@@ -14,6 +14,7 @@ requires-python = ">=3.12"
 
 dependencies = [
     "antspyx",
+    "black>=25.11.0",
     "cython>=3.1.4",
     "dask==2025.1.0",
     "dask-image",
@@ -24,9 +25,12 @@ dependencies = [
     "jupyterlab",
     "matplotlib",
     "napari[all]>0.6.1",
+    "nd2",
     "neuroglancer>=2.40.1,<3.0.0",
+    "ome-types",
     "opencv-python",
     "pandas>=2.3.3",
+    "pytest>=8.4.2",
     "pywavelets",
     "scikit-image",
     "scipy",