ome-arrow 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

ome_arrow/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.2'
-__version_tuple__ = version_tuple = (0, 0, 2)
+__version__ = version = '0.0.4'
+__version_tuple__ = version_tuple = (0, 0, 4)
 
 __commit_id__ = commit_id = None

ome_arrow/core.py

@@ -5,12 +5,11 @@ Core of the ome_arrow package, used for classes and such.
 from __future__ import annotations
 
 import pathlib
-from typing import Any, Dict, Iterable, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Dict, Iterable, Optional, Tuple
 
 import matplotlib
 import numpy as np
 import pyarrow as pa
-import pyvista
 
 from ome_arrow.export import to_numpy, to_ome_parquet, to_ome_tiff, to_ome_zarr
 from ome_arrow.ingest import (
@@ -25,6 +24,10 @@ from ome_arrow.transform import slice_ome_arrow
 from ome_arrow.utils import describe_ome_arrow
 from ome_arrow.view import view_matplotlib, view_pyvista
 
+# if not in runtime, import pyvista for type hints
+if TYPE_CHECKING:
+    import pyvista
+
 
 class OMEArrow:
     """
@@ -47,6 +50,8 @@ class OMEArrow:
         self,
         data: str | dict | pa.StructScalar | "np.ndarray",
         tcz: Tuple[int, int, int] = (0, 0, 0),
+        column_name: str = "ome_arrow",
+        row_index: int = 0,
     ) -> None:
         """
         Construct an OMEArrow from:
@@ -91,7 +96,9 @@ class OMEArrow:
                 ".parquet",
                 ".pq",
             }:
-                self.data = from_ome_parquet(s)
+                self.data = from_ome_parquet(
+                    s, column_name=column_name, row_index=row_index
+                )
 
             # TIFF
             elif path.suffix.lower() in {".tif", ".tiff"} or s.lower().endswith(
@@ -293,7 +300,7 @@ class OMEArrow:
         clim: tuple[float, float] | None = None,
         show_axes: bool = True,
         scaling_values: tuple[float, float, float] | None = (1.0, 0.1, 0.1),
-    ) -> matplotlib.figure.Figure | pyvista.Plotter:
+    ) -> matplotlib.figure.Figure | "pyvista.Plotter":
         """
         Render an OME-Arrow record using Matplotlib or PyVista.
 

ome_arrow/ingest.py

@@ -4,6 +4,7 @@ Converting to and from OME-Arrow formats.
 
 import itertools
 import re
+import warnings
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
@@ -820,42 +821,6 @@ def from_ome_parquet(
 ) -> pa.StructScalar:
     """
     Read an OME-Arrow record from a Parquet file and return a typed StructScalar.
-
-    Expected layout (as produced by `to_ome_parquet`):
-      - single Parquet file
-      - a single column (default name "ome_arrow") of `OME_ARROW_STRUCT` type
-      - one row (row_index=0)
-
-    This function is forgiving:
-      - If `column_name` is None or not found, it will auto-detect a struct column
-        that matches the OME-Arrow field names.
-      - If the table has multiple rows, you can choose which record to read
-        via `row_index`.
-
-    Parameters
-    ----------
-    parquet_path : str | Path
-        Path to the .parquet file.
-    column_name : Optional[str], default "ome_arrow"
-        Name of the column that stores the OME-Arrow struct. If None, auto-detect.
-    row_index : int, default 0
-        Which row to read if the table contains multiple rows.
-    strict_schema : bool, default False
-        If True, require the column's type to equal `OME_ARROW_STRUCT` exactly.
-        If False, we only require the column to be a Struct with the same field
-        names (order can vary).
-
-    Returns
-    -------
-    pa.StructScalar
-        A validated OME-Arrow struct scalar.
-
-    Raises
-    ------
-    FileNotFoundError
-        If the file does not exist.
-    ValueError
-        If a suitable column/row cannot be found or schema checks fail.
     """
     p = Path(parquet_path)
     if not p.exists():
@@ -874,7 +839,9 @@ def from_ome_parquet(
         col_fields = {f.name for f in t}
         return ome_fields == col_fields
 
+    requested_name = column_name
     candidate_col = None
+    autodetected_name = None
 
     if column_name is not None and column_name in table.column_names:
         arr = table[column_name]
@@ -898,10 +865,12 @@ def from_ome_parquet(
             if pa.types.is_struct(arr.type):
                 if strict_schema and arr.type == OME_ARROW_STRUCT:
                     candidate_col = arr
+                    autodetected_name = name
                     column_name = name
                     break
                 if not strict_schema and _struct_matches_ome_fields(arr.type):
                     candidate_col = arr
+                    autodetected_name = name
                     column_name = name
                     break
         if candidate_col is None:
@@ -911,21 +880,26 @@ def from_ome_parquet(
                 hint = f"column '{column_name}' not found and auto-detection failed."
             raise ValueError(f"Could not locate an OME-Arrow struct column: {hint}")
 
+    # Emit warning if auto-detection was used
+    if autodetected_name is not None and autodetected_name != requested_name:
+        warnings.warn(
+            f"Requested column '{requested_name}' was not usable or not found. "
+            f"Auto-detected OME-Arrow column '{autodetected_name}'.",
+            UserWarning,
+            stacklevel=2,
+        )
+
     # 2) Extract the row as a Python dict
-    #    (Using to_pylist() for the single element slice is simple & reliable.)
     record_dict: Dict[str, Any] = candidate_col.slice(row_index, 1).to_pylist()[0]
 
     # 3) Reconstruct a typed StructScalar using the canonical schema
-    #    (this validates field names/types and normalizes order)
     scalar = pa.scalar(record_dict, type=OME_ARROW_STRUCT)
 
     # Optional: soft validation via file-level metadata (if present)
     try:
         meta = table.schema.metadata or {}
-        meta.get(b"ome.arrow.type", b"").decode() == str(
-            OME_ARROW_TAG_TYPE
-        ) and meta.get(b"ome.arrow.version", b"").decode() == str(OME_ARROW_TAG_VERSION)
-        # You could log/print a warning if tag_ok is False, but don't fail.
+        meta.get(b"ome.arrow.type", b"").decode() == str(OME_ARROW_TAG_TYPE)
+        meta.get(b"ome.arrow.version", b"").decode() == str(OME_ARROW_TAG_VERSION)
     except Exception:
         pass
 

ome_arrow/view.py

@@ -2,16 +2,27 @@
 Viewing utilities for OME-Arrow data.
 """
 
+from __future__ import annotations
+
 import contextlib
+import warnings
+from typing import TYPE_CHECKING
 
 import matplotlib.pyplot as plt
 import numpy as np
 import pyarrow as pa
-import pyvista as pv
 from matplotlib.axes import Axes
 from matplotlib.figure import Figure
 from matplotlib.image import AxesImage
 
+try:  # optional dependency
+    import pyvista as pv
+except ImportError:  # pragma: no cover - exercised when viz extra missing
+    pv = None  # type: ignore[assignment]
+
+if TYPE_CHECKING:
+    import pyvista
+
 
 def view_matplotlib(
     data: dict[str, object] | pa.StructScalar,
@@ -63,6 +74,21 @@ def view_matplotlib(
     return fig, ax, im
 
 
+def _require_pyvista() -> "pyvista":
+    """
+    Ensure PyVista is available, raising a helpful error otherwise.
+    """
+    if pv is None:
+        msg = (
+            "PyVista-based visualization requires the optional 'viz' extras. "
+            "Install with `pip install ome-arrow[viz]` to enable 3D viewing."
+        )
+        warnings.warn(msg, RuntimeWarning)
+        raise RuntimeError(msg)
+
+    return pv
+
+
 def view_pyvista(
     data: dict | pa.StructScalar,
     c: int = 0,
@@ -77,16 +103,14 @@ def view_pyvista(
     percentile_clim: tuple[float, float] = (1.0, 99.9),  # robust contrast
     sampling_scale: float = 0.5,  # smaller = denser rays (sharper, slower)
     show: bool = True,
-) -> pv.Plotter:
+) -> "pyvista.Plotter":
     """
     Jupyter-inline interactive volume view using PyVista backends.
     Tries 'trame' → 'html' → 'static' when backend='auto'.
 
     sampling_scale controls ray step via the mapper after add_volume.
     """
-    import warnings
-
-    import numpy as np
+    pv = _require_pyvista()
 
     # ---- unwrap OME-Arrow row
     row = data.as_py() if isinstance(data, pa.StructScalar) else data

ome_arrow-0.0.4.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: ome-arrow
+Version: 0.0.4
+Summary: Using OME specifications with Apache Arrow for fast, queryable, and language agnostic bioimage data.
+Author: Dave Bunten
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bioio>=3
+Requires-Dist: bioio-ome-tiff>=1.4
+Requires-Dist: bioio-ome-zarr>=3.0.3
+Requires-Dist: bioio-tifffile>=1.3
+Requires-Dist: fire>=0.7
+Requires-Dist: matplotlib>=3.10.7
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pillow>=12
+Requires-Dist: pyarrow>=22
+Provides-Extra: viz
+Requires-Dist: ipywidgets>=8.1.8; extra == "viz"
+Requires-Dist: jupyterlab-widgets>=3.0.16; extra == "viz"
+Requires-Dist: pyvista>=0.46.4; extra == "viz"
+Requires-Dist: trame>=3.12; extra == "viz"
+Requires-Dist: trame-vtk>=2.10; extra == "viz"
+Requires-Dist: trame-vuetify>=3.1; extra == "viz"
+Dynamic: license-file
+
+<img height="200" src="https://raw.githubusercontent.com/wayscience/ome-arrow/main/docs/src/_static/logo.png?raw=true">
+
+![PyPI - Version](https://img.shields.io/pypi/v/ome-arrow)
+[![Build Status](https://github.com/wayscience/ome-arrow/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/wayscience/ome-arrow/actions/workflows/run-tests.yml?query=branch%3Amain)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Software DOI badge](https://zenodo.org/badge/DOI/10.5281/zenodo.17664969.svg)](https://doi.org/10.5281/zenodo.17664969)
+
+# Open, interoperable, and queryable microscopy images with OME Arrow
+
+OME-Arrow uses [Open Microscopy Environment (OME)](https://github.com/ome) specifications through [Apache Arrow](https://arrow.apache.org/) for fast, queryable, and language agnostic bioimage data.
+
+<img height="200" src="https://raw.githubusercontent.com/wayscience/ome-arrow/main/docs/src/_static/references_to_files.png">
+
+__Images are often left behind from the data model, referenced but excluded from databases.__
+
+<img height="200" src="https://raw.githubusercontent.com/wayscience/ome-arrow/main/docs/src/_static/various_ome_arrow_schema.png">
+
+__OME-Arrow brings images back into the story.__
+
+OME Arrow enables image data to be stored alongside metadata or derived data such as single-cell morphology features.
+Images in OME Arrow are composed of mutlilayer [structs](https://arrow.apache.org/docs/python/generated/pyarrow.struct.html) so they may be stored as values within tables.
+This means you can store, query, and build relationships on data from the same location using any system which is compatible with Apache Arrow (including Parquet) through common data interfaces (such as SQL and DuckDB).
+
+## Project focus
+
+This package is intentionally dedicated to work at a per-image level and not large batch handling (though it may be used for those purposes by users or in other projects).
+
+- For visualizing OME Arrow and OME Parquet data in Napari, please see the [`napari-ome-arrow`](https://github.com/WayScience/napari-ome-arrow) Napari plugin.
+- For more comprehensive handling of many images and features in the context of the OME Parquet format please see the [`CytoDataFrame`](https://github.com/cytomining/CytoDataFrame) project (and relevant [example notebook](https://github.com/cytomining/CytoDataFrame/blob/main/docs/src/examples/cytodataframe_at_a_glance.ipynb)).
+
+## Installation
+
+Install OME Arrow from PyPI or from source:
+
+```sh
+# install from pypi
+pip install ome-arrow
+
+# install directly from source
+pip install git+https://github.com/wayscience/ome-arrow.git
+```
+
+## Quick start
+
+See below for a quick start guide.
+Please also reference an example notebook: [Learning to fly with OME-Arrow](https://github.com/wayscience/ome-arrow/tree/main/docs/src/examples/learning_to_fly_with_ome-arrow.ipynb).
+
+```python
+from ome_arrow import OMEArrow
+
+# Ingest a tif image through a convenient OME Arrow class
+# We can also ingest OME-Zarr or NumPy arrays.
+oa_image = OMEArrow(
+    data="your_image.tif"
+)
+
+# Access the OME Arrow struct itself
+# (compatible with Arrow-compliant data storage).
+oa_image.data
+
+# Show information about the image.
+oa_image.info()
+
+# Display the image with matplotlib.
+oa_image.view(how="matplotlib")
+
+# Display the image with pyvista
+# (great for ZYX 3D images; install extras: `pip install 'ome-arrow[viz]'`).
+oa_image.view(how="pyvista")
+
+# Export to OME-Parquet.
+# We can also export OME-TIFF, OME-Zarr or NumPy arrays.
+oa_image.export(how="ome-parquet", out="your_image.ome.parquet")
+```
+
+## Contributing, Development, and Testing
+
+Please see our [contributing documentation](https://github.com/wayscience/ome-arrow/tree/main/CONTRIBUTING.md) for more details on contributions, development, and testing.
+
+## Related projects
+
+OME Arrow is used or inspired by the following projects, check them out!
+
+- [`napari-ome-arrow`](https://github.com/WayScience/napari-ome-arrow): enables you to view OME Arrow and related images.
+- [`nViz`](https://github.com/WayScience/nViz): focuses on ingesting and visualizing various 3D image data.
+- [`CytoDataFrame`](https://github.com/cytomining/CytoDataFrame): provides a DataFrame-like experience for viewing feature and microscopy image data within Jupyter notebook interfaces and creating OME Parquet files.
+- [`coSMicQC`](https://github.com/cytomining/coSMicQC): performs quality control on microscopy feature datasets, visualized using CytoDataFrames.

ome_arrow-0.0.4.dist-info/RECORD

@@ -0,0 +1,14 @@
+ome_arrow/__init__.py,sha256=DfQsw8l0mx1Qt3YiiMv2SUljKETP3wS5hrD5eBbjMDM,583
+ome_arrow/_version.py,sha256=QlXZ5JTjE_pgpDaeHk0GTExkc75xUZFmd0hA7kGYCJ0,704
+ome_arrow/core.py,sha256=pTKmzKFXF5d4nSJpXQxlS71UA23P7TLHrX2eA0IxgUg,18594
+ome_arrow/export.py,sha256=CCTnEdHko4Z0i5LEHuNGFLznWSsPyAFcS42H5nHU22Q,14875
+ome_arrow/ingest.py,sha256=7N-M_NYOskHjs59Yhd4j8QXnKC5ykBXM7cT9Ap2chz8,32032
+ome_arrow/meta.py,sha256=qeD0e_ItAQyZDT7ypkBU0rBh9oHIu2ziz9MCfPpPp9g,4199
+ome_arrow/transform.py,sha256=0275_Mn1mlGXSWJ86llch8JoJyvqEOfvG-ub1dUWFNI,5997
+ome_arrow/utils.py,sha256=XHovcqmjqoiBpKvXY47-_yUwf07f8zVE_F9BR_VKaPU,2383
+ome_arrow/view.py,sha256=O4sIF8CZ4if-tV-rr2-yyG8WB5jHN9jq8HKvS-Ielnw,10034
+ome_arrow-0.0.4.dist-info/licenses/LICENSE,sha256=9-2Pyhu3vTt2RJU8DorHQtHeNO_e5RLeFJTyOU4hOi4,1508
+ome_arrow-0.0.4.dist-info/METADATA,sha256=2al9lOlUBjuximxy-1L9TsbVkFC46o0_zR3T1EnFRtU,5908
+ome_arrow-0.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ome_arrow-0.0.4.dist-info/top_level.txt,sha256=aWOtkGXo_pfU-yy82guzGhz8Zh2h2nFl8Kc5qdzMGuE,10
+ome_arrow-0.0.4.dist-info/RECORD,,

ome_arrow-0.0.2.dist-info/METADATA

@@ -1,34 +0,0 @@
-Metadata-Version: 2.4
-Name: ome-arrow
-Version: 0.0.2
-Summary: Using OME specifications with Apache Arrow for fast, queryable, and language agnostic bioimage data.
-Author: Dave Bunten
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: bioio>=3
-Requires-Dist: bioio-ome-tiff>=1.4
-Requires-Dist: bioio-ome-zarr>=3.0.3
-Requires-Dist: bioio-tifffile>=1.3
-Requires-Dist: fire>=0.7
-Requires-Dist: ipywidgets>=8.1.8
-Requires-Dist: jupyterlab-widgets>=3.0.16
-Requires-Dist: matplotlib>=3.10.7
-Requires-Dist: numpy>=2.2.6
-Requires-Dist: pandas>=2.2.3
-Requires-Dist: pillow>=12
-Requires-Dist: pyarrow>=22
-Requires-Dist: pyvista>=0.46.4
-Requires-Dist: trame>=3.12
-Requires-Dist: trame-vtk>=2.10
-Requires-Dist: trame-vuetify>=3.1
-Dynamic: license-file
-
-# ome-arrow
-
-Using OME specifications with Apache Arrow for fast, queryable, and language agnostic bioimage data.

ome_arrow-0.0.2.dist-info/RECORD

@@ -1,14 +0,0 @@
-ome_arrow/__init__.py,sha256=DfQsw8l0mx1Qt3YiiMv2SUljKETP3wS5hrD5eBbjMDM,583
-ome_arrow/_version.py,sha256=huLsL1iGeXWQKZ8bjwDdIWC7JOkj3wnzBh-HFMZl1PY,704
-ome_arrow/core.py,sha256=NUCV9KUH3yCOlpetRS5NNVG_phodutE1F2ujDBPhHgY,18351
-ome_arrow/export.py,sha256=CCTnEdHko4Z0i5LEHuNGFLznWSsPyAFcS42H5nHU22Q,14875
-ome_arrow/ingest.py,sha256=zZz94LaLOpmoxnryLeoPsaWV0EzkYkGFizYSVcbd5w8,33016
-ome_arrow/meta.py,sha256=qeD0e_ItAQyZDT7ypkBU0rBh9oHIu2ziz9MCfPpPp9g,4199
-ome_arrow/transform.py,sha256=0275_Mn1mlGXSWJ86llch8JoJyvqEOfvG-ub1dUWFNI,5997
-ome_arrow/utils.py,sha256=XHovcqmjqoiBpKvXY47-_yUwf07f8zVE_F9BR_VKaPU,2383
-ome_arrow/view.py,sha256=DT8i56uV8Rw22KkqwjPPPKWJWNtfgR9OkI8Qj1WD8Ds,9355
-ome_arrow-0.0.2.dist-info/licenses/LICENSE,sha256=9-2Pyhu3vTt2RJU8DorHQtHeNO_e5RLeFJTyOU4hOi4,1508
-ome_arrow-0.0.2.dist-info/METADATA,sha256=XrGmDrHe-QMpEeDzUP4hVEmfh1P4Z8qyGMmGuMPWsfo,1164
-ome_arrow-0.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ome_arrow-0.0.2.dist-info/top_level.txt,sha256=aWOtkGXo_pfU-yy82guzGhz8Zh2h2nFl8Kc5qdzMGuE,10
-ome_arrow-0.0.2.dist-info/RECORD,,