spacr.qt.multi_format

Multi-format dataset detection — handles single-file dataset drops.

Not every microscopy dataset comes as one image per file. spaCR must also handle:

• .npz — one archive holding several named arrays (each usually a field / channel / stack).

• .npy — a single big ndarray whose axes carry the field / channel meaning.

• .lif / .nd2 — vendor formats that pack a whole plate + its metadata into one file. spaCR uses readlif and nd2reader to crack them open.

• Multi-page .tif / .tiff — one file, many pages; typical meaning is a stack along Z, T, or C.

describe_file() returns a DatasetDescription for any supported file (or None). Callers can then either:

• Extract images out into the canonical filename format via explode_to_folder() (writes real .tif files + a filename_map.csv), or

• Consume the arrays directly in a downstream analysis.

This module deliberately avoids importing heavy dependencies at top-level — vendor libraries are imported lazily inside the describers so users without them don’t pay a cost.

Classes

DatasetDescription

Structured summary of a single-file dataset drop.

Functions

describe_file(→ Optional[DatasetDescription])

Return a DatasetDescription for path or None.

Module Contents

class spacr.qt.multi_format.DatasetDescription

Structured summary of a single-file dataset drop.

Variables:

• path – the source file.

• kind – one of "npz" | "npy" | "lif" | "nd2" | "tif_multi".

• n_fields – number of distinct fields (a.k.a. positions / series).

• n_channels – number of channels per field.

• n_timepoints – number of timepoints (1 if none).

• n_slices – number of z-slices (1 if none).

• shape – (H, W) of one plane if known, else None.

• dtype – dtype of the arrays if known.

• notes – anything else worth telling the user.

summary() → str

Human-readable one-line summary for the Console.

spacr.qt.multi_format.describe_file(path: Any) → DatasetDescription | None

Return a DatasetDescription for path or None.

Parameters:

path – file to inspect.