xarray-ome

Seamless integration between OME-Zarr and xarray

xarray-ome provides an xarray backend for reading OME-Zarr (OME-NGFF) files, enabling efficient access to multiscale bioimaging data with lazy loading and physical coordinates.

Note

Powered by ngff-zarr

xarray-ome is built on top of ngff-zarr, which handles all OME-NGFF specification parsing and Zarr I/O. We focus on providing seamless xarray integration and coordinate transformations.

Features

🚀 Easy to Use

Open OME-Zarr files with a single function call

from xarray_ome import open_ome_datatree
dt = open_ome_datatree("image.ome.zarr")

📊 Multiscale Support

Access entire multiscale pyramids as DataTree structures

high_res = dt["scale0"]
low_res = dt["scale2"]

🌍 Remote Access

Work with remote data without downloading

# Try with real IDR sample data!
url = "https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.4/idr0062A/6001240.zarr"
ds = open_ome_dataset(url)

⚡ Lazy Loading

Efficient processing with Dask integration

# Only loads what you need
subset = ds.isel(z=0).compute()

Quick Start

Installation

pip install xarray-ome

Basic Usage

Try it with real data from the Image Data Resource:

import xarray as xr

# Load remote OME-Zarr data (no download needed!)
url = "https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.4/idr0062A/6001240.zarr"
ds = xr.open_dataset(url, engine="ome-zarr")

# View the dataset
ds

<xarray.Dataset> Size: 70MB
Dimensions:  (c: 2, z: 236, y: 275, x: 271)
Coordinates:
  * c        (c) <U7 56B 'LaminB1' 'Dapi'
  * z        (z) float64 2kB 0.0 0.5002 1.0 1.501 ... 116.0 116.5 117.0 117.5
  * y        (y) float64 2kB 0.0 0.3604 0.7208 1.081 ... 97.67 98.03 98.39 98.75
  * x        (x) float64 2kB 0.0 0.3604 0.7208 1.081 ... 96.23 96.59 96.95 97.31
Data variables:
    image    (c, z, y, x) uint16 70MB ...
Attributes:
    ome_scale:             {'c': 1.0, 'z': 0.5002025531914894, 'y': 0.3603981...
    ome_translation:       {'c': 0.0, 'z': 0.0, 'y': 0.0, 'x': 0.0}
    ome_ngff_resolution:   0
    ome_name:              image
    ome_version:           0.4
    ome_axes_types:        ['channel', 'space', 'space', 'space']
    ome_axes_units:        {'z': 'micrometer', 'y': 'micrometer', 'x': 'micro...
    ome_multiscale_paths:  ['0', '1', '2']
    ome_num_resolutions:   3
    ome_channel_colors:    ['0000FF', 'FFFF00']
    ome_channel_windows:   [{'min': 0.0, 'max': 65535.0, 'start': 0.0, 'end':...
    ome_ngff_metadata:     {'axes': [{'name': 'c', 'type': 'channel', 'unit':...

xarray.Dataset

• Dimensions:
  • c: 2
  • z: 236
  • y: 275
  • x: 271
• Coordinates: (4)
  • c
    (c)
    <U7
    'LaminB1' 'Dapi'

    array(['LaminB1', 'Dapi'], dtype='<U7')

  • z
    (z)
    float64
    0.0 0.5002 1.0 ... 117.0 117.5

    array([  0.      ,   0.500203,   1.000405, ..., 116.547195, 117.047397,
           117.5476  ], shape=(236,))

  • y
    (y)
    float64
    0.0 0.3604 0.7208 ... 98.39 98.75

    array([ 0.      ,  0.360398,  0.720796, ..., 98.028298, 98.388696, 98.749094],
          shape=(275,))

  • x
    (x)
    float64
    0.0 0.3604 0.7208 ... 96.95 97.31

    array([ 0.      ,  0.360398,  0.720796, ..., 96.586705, 96.947103, 97.307501],
          shape=(271,))

• Data variables: (1)
  • image
    (c, z, y, x)
    uint16
    ...

    [35175800 values with dtype=uint16]

• Indexes: (4)
  • c
    PandasIndex

    PandasIndex(Index(['LaminB1', 'Dapi'], dtype='object', name='c'))

  • z
    PandasIndex

    PandasIndex(Index([               0.0, 0.5002025531914894, 1.0004051063829789,
           1.5006076595744684, 2.0008102127659577,  2.501012765957447,
            3.001215319148937,  3.501417872340426,  4.001620425531915,
            4.501822978723405,
           ...
            113.0457770212766,  113.5459795744681, 114.04618212765959,
           114.54638468085108, 115.04658723404256, 115.54678978723406,
           116.04699234042555, 116.54719489361703, 117.04739744680853,
           117.54760000000002],
          dtype='float64', name='z', length=236))

  • y
    PandasIndex

    PandasIndex(Index([               0.0, 0.3603981534640209, 0.7207963069280418,
           1.0811944603920627, 1.4415926138560835, 1.8019907673201043,
           2.1623889207841254,  2.522787074248146,  2.883185227712167,
            3.243583381176188,
           ...
            95.50551066796554,  95.86590882142956,  96.22630697489357,
             96.5867051283576,  96.94710328182161,  97.30750143528563,
            97.66789958874966,  98.02829774221368,   98.3886958956777,
            98.74909404914172],
          dtype='float64', name='y', length=275))

  • x
    PandasIndex

    PandasIndex(Index([               0.0, 0.3603981534640209, 0.7207963069280418,
           1.0811944603920627, 1.4415926138560835, 1.8019907673201043,
           2.1623889207841254,  2.522787074248146,  2.883185227712167,
            3.243583381176188,
           ...
            94.06391805410945,  94.42431620757347,  94.78471436103749,
             95.1451125145015,  95.50551066796554,  95.86590882142956,
            96.22630697489357,   96.5867051283576,  96.94710328182161,
            97.30750143528563],
          dtype='float64', name='x', length=271))

• Attributes: (12)

  ome_scale :

  {'c': 1.0, 'z': 0.5002025531914894, 'y': 0.3603981534640209, 'x': 0.3603981534640209}

  ome_translation :

  {'c': 0.0, 'z': 0.0, 'y': 0.0, 'x': 0.0}

  ome_ngff_resolution :

  0

  ome_name :

  image

  ome_version :

  0.4

  ome_axes_types :

  ['channel', 'space', 'space', 'space']

  ome_axes_units :

  {'z': 'micrometer', 'y': 'micrometer', 'x': 'micrometer'}

  ome_multiscale_paths :

  ['0', '1', '2']

  ome_num_resolutions :

  3

  ome_channel_colors :

  ['0000FF', 'FFFF00']

  ome_channel_windows :

  [{'min': 0.0, 'max': 65535.0, 'start': 0.0, 'end': 1500.0}, {'min': 0.0, 'max': 65535.0, 'start': 0.0, 'end': 1500.0}]

  ome_ngff_metadata :

  {'axes': [{'name': 'c', 'type': 'channel', 'unit': None, 'orientation': None}, {'name': 'z', 'type': 'space', 'unit': 'micrometer', 'orientation': None}, {'name': 'y', 'type': 'space', 'unit': 'micrometer', 'orientation': None}, {'name': 'x', 'type': 'space', 'unit': 'micrometer', 'orientation': None}], 'datasets': [{'path': '0', 'coordinateTransformations': [{'scale': [1.0, 0.5002025531914894, 0.3603981534640209, 0.3603981534640209], 'type': 'scale'}]}, {'path': '1', 'coordinateTransformations': [{'scale': [1.0, 0.5002025531914894, 0.7207963069280418, 0.7207963069280418], 'type': 'scale'}]}, {'path': '2', 'coordinateTransformations': [{'scale': [1.0, 0.5002025531914894, 1.4415926138560835, 1.4415926138560835], 'type': 'scale'}]}], 'coordinateTransformations': None, 'omero': {'channels': [{'color': '0000FF', 'window': {'min': 0.0, 'max': 65535.0, 'start': 0.0, 'end': 1500.0}, 'label': 'LaminB1'}, {'color': 'FFFF00', 'window': {'min': 0.0, 'max': 65535.0, 'start': 0.0, 'end': 1500.0}, 'label': 'Dapi'}]}, 'name': 'image', 'version': '0.4', 'type': None, 'metadata': None}

Notice the xarray Dataset with physical coordinates and channel labels:

• Channel coordinates use labels from metadata ('LaminB1', 'Dapi') instead of indices

• Physical coordinates in micrometers for spatial dimensions (z, y, x)

• Lazy loading with Dask - data is only loaded when needed

• OME metadata preserved in attributes for round-tripping

Now work with the data using familiar xarray operations:

# Select by channel name
lamin = ds.sel(c='LaminB1')
print(f"LaminB1 channel shape: {lamin['image'].shape}")

# Create maximum intensity projection
mip = ds['image'].sel(c='Dapi').max(dim='z')
print(f"MIP shape: {mip.shape}")

# Process a subset (only downloads what you need!)
subset = ds.sel(c='Dapi').isel(z=slice(0, 10))
print(f"Subset shape: {subset['image'].shape}")
print(f"Subset size: {subset['image'].nbytes / 1e6:.1f} MB")

LaminB1 channel shape: (236, 275, 271)
MIP shape: (275, 271)
Subset shape: (10, 275, 271)
Subset size: 1.5 MB

Architecture

xarray-ome uses ngff-zarr for OME-Zarr I/O and focuses on the xarray integration:

        graph LR
    A[User Code] --> B[xarray-ome API]
    B --> C[Coordinate Translation]
    C --> D[ngff-zarr]
    D --> E[zarr]
    E --> F[Storage]
    

• ngff-zarr: Handles OME-Zarr specification compliance and I/O

• xarray-ome: Converts coordinate transformations and builds xarray structures

• zarr: Provides chunked array storage with lazy loading

Contents

• Usage Guide
  • Installation
  • Sample Data
  • Basic Usage
  • Features
  • Metadata Handling
  • Working with DataTree
  • Advanced Usage
  • Limitations
  • Examples
  • API Reference
  • See Also
• OME-NGFF to xarray Mapping
  • Design Philosophy
  • Metadata Mapping Reference
  • Complete Attribute Reference
  • Round-Trip Fidelity
  • Implementation Details
  • Version Support
• Examples
  • Featured Sample Dataset
  • Example Notebooks
  • Running Examples Locally
  • Additional Resources
• API Reference
  • Reading Functions
  • Writing Functions
  • Metadata Attributes
  • Coordinate Transformations
  • Utilities
  • Type Definitions
  • See Also
• Contributing Guide
  • Development Setup
  • Project Structure
  • Development Workflow
  • Code Style Guidelines
  • Git Workflow
  • Testing
  • Documentation
  • Pull Request Process
  • Architecture Guidelines
  • Release Process
  • Getting Help
  • Code of Conduct
  • License

Specification Support

OME-NGFF Versions:

• Reading: v0.1 through v0.5 (via ngff-zarr)

• Writing: v0.4 and v0.5 (via ngff-zarr)

Data Structures:

• ✅ Simple multiscale images

• ❌ HCS plate structures (not yet supported)

Contributing

Contributions are welcome! See our contributing guide for details.

License

MIT License. See LICENSE file for details.

Acknowledgments

• Built on ngff-zarr for OME-Zarr handling

• Inspired by xarray-ome-ngff for coordinate transformation patterns

• Part of the OME-NGFF ecosystem

Links

• Documentation: xarray-ome.readthedocs.io

• Source Code: github.com/your-org/xarray-ome

• Issue Tracker: github.com/your-org/xarray-ome/issues

• OME-NGFF Spec: ngff.openmicroscopy.org