Skip to content

Unbounded Experiments

In some microscopy experiments, the total number of frames to be acquired is not known in advance. For example, a time-lapse imaging session may continue until a specific biological event occurs, or some duration has elapsed.

ome-writers supports this case by allowing you to define an unbounded first dimension in your AcquisitionSettings. A dimension is considered unbounded if its count is set to None. Only the first dimension can be unbounded.

When using an unbounded first dimension, you can keep appending frames to the stream until you decide to stop the acquisition. The stream writer will handle dynamically resizing the underlying storage as needed.

"""Example of using ome_writers with unbounded first dimension.

This simulates visiting two positions for an "unknown" number of timepoints.
(e.g. run for an hour, regardless of how long the inter-frame interval ends up being).
"""

import sys

import numpy as np

from ome_writers import AcquisitionSettings, Dimension, create_stream

# Derive format/backend from command line argument (default: auto)
FORMAT = "auto" if len(sys.argv) < 2 else sys.argv[1]

# create acquisition settings
settings = AcquisitionSettings(
    root_path="example_unbounded",
    # declare dimensions in order of acquisition (slowest to fastest)
    dimensions=[
        # count=None makes this an unbounded dimension
        # only the first dimension can be unbounded
        Dimension(name="t", count=None, chunk_size=1, type="time"),
        Dimension(name="p", type="position", coords=["Pos0", "Pos1"]),
        Dimension(name="y", count=256, chunk_size=64, type="space"),
        Dimension(name="x", count=256, chunk_size=64, type="space"),
    ],
    dtype="uint16",
    overwrite=True,
    format=FORMAT,
)

# actual count of first dimension for the sake of this example
# (in reality, it would likely be conditional, e.g. in a generator loop)
actual_count = 3
numframes = np.prod(settings.shape[1:-2]) * actual_count
frame_shape = settings.shape[-2:]

with create_stream(settings) as stream:
    for i in range(numframes):
        stream.append(np.full(frame_shape, fill_value=i, dtype=settings.dtype))

if settings.format.name == "ome-zarr":
    import yaozarrs

    yaozarrs.validate_zarr_store(settings.output_path)
    print("✓ Zarr store is valid")