zea.data.metadata

Selective metadata loading for Dataloader.

See the return_metadata argument of Dataloader for the path syntax and the shape of the result.

Functions

has_per_frame_paths(paths)	Whether any of paths can resolve to a field with a leading n_frames axis.
batch_leaf_shape(path, shape, n_frames[, ...])	Return shape as batching sees it: selected, with the frame axis a placeholder.
metadata_signature(file, paths)	Map every leaf reachable from paths to its shape in file.
missing_metadata_paths(file, paths)	Return the subset of paths that file cannot supply.
normalize_metadata_paths(return_metadata)	Normalize the return_metadata argument into a tuple of dotted paths.
read_metadata(file, paths)	Read paths off an open file into a nested, FileSpec-shaped dict.
select_metadata_axes(tree, dim_selections, ...)	Return a copy of tree narrowed by the sample's axis_selections.
selected_dimensions(key, num_dims, ...)	Resolve {axis: selection} on key into {dimension name: selection}.
selected_leaf_shape(path, shape, ...)	Return shape as it is after select_metadata_axes() narrows it.
slice_metadata(tree, frame_selection, n_frames)	Return a copy of tree with per-frame fields sliced to the sample's frames.

zea.data.metadata.batch_leaf_shape(path, shape, n_frames, dim_selections=None, dim_sizes=None)

Return shape as batching sees it: selected, with the frame axis a placeholder.

Batching stacks metadata leaf by leaf, so the leaves of every file must line up. Both cuts a sample’s metadata undergoes are applied here, since a leaf only has to match after them: the selection (selected_leaf_shape()), and the frame axis, sliced to the sample’s frame count and so normalized rather than compared. Everything else must match exactly.

Return type:

tuple

zea.data.metadata.has_per_frame_paths(paths)

Whether any of paths can resolve to a field with a leading n_frames axis.

Lets the caller skip the per-frame slicing pass entirely when only static metadata (scan parameters, probe geometry, subject) was requested.

Return type:

bool

zea.data.metadata.metadata_signature(file, paths)

Map every leaf reachable from paths to its shape in file.

The shapes are the raw stored ones: normalizing the frame axis needs the file’s own frame count, which the caller holds. Dtypes are deliberately left out – stacking promotes them (float32 with float64, <U4 with <U9), so a difference there is not a batching failure.

Parameters:

• file (File) – An open File.

• paths (Sequence[str]) – Dotted paths to describe. A path pointing at a group expands to one entry per leaf below it.

Returns:

Leaf dotted path -> shape tuple. A path absent from the file maps to the shape of None, i.e. (); use missing_metadata_paths() to tell absence apart from a genuine scalar.

Return type:

dict[str, tuple]

zea.data.metadata.missing_metadata_paths(file, paths)

Return the subset of paths that file cannot supply.

Lets a caller check a whole dataset up front instead of discovering a missing path when read_metadata() reaches the file mid-epoch.

Parameters:

• file (File) – An open File.

• paths (Sequence[str]) – Dotted paths to check.

Returns:

The paths absent from file, in the order given. Empty when the file can answer all of them.

Return type:

tuple[str, ...]

zea.data.metadata.normalize_metadata_paths(return_metadata)

Normalize the return_metadata argument into a tuple of dotted paths.

Parameters:

return_metadata – False/None to return arrays only, True for file identity only, or a string / iterable of dotted paths.

Return type:

tuple[str, ...] | None

Returns:

None when no metadata should be returned, otherwise a tuple of dotted paths (possibly empty, meaning file identity only).

zea.data.metadata.read_metadata(file, paths)

Read paths off an open file into a nested, FileSpec-shaped dict.

Parameters:

• file (File) – An open File.

• paths (Sequence[str]) – Dotted paths to read. A path pointing at a group reads the whole group recursively.

Returns:

Nested dict mirroring FileSpec.

Return type:

dict

Raises:

KeyError – If a requested path is absent from the file.

zea.data.metadata.select_metadata_axes(tree, dim_selections, dim_sizes, prefix='')

Return a copy of tree narrowed by the sample’s axis_selections.

A selection means something about the acquisition – “these 21 transmits” – so a field carrying that dimension stops describing the sample it comes with unless it is cut the same way. Unlike the frame axis of slice_metadata(), the cut is the same for every sample of a file, so this runs once per file rather than per sample.

Parameters:

• tree (dict) – Nested metadata dict as returned by read_metadata().

• dim_selections (dict) – Dimension name -> selection, from selected_dimensions().

• dim_sizes (dict) – Dimension name -> that dimension’s full extent in this file.

• prefix (str) – Dotted prefix of tree within the file spec (internal).

Returns:

A new nested dict; values with no selected axis are shared, not copied.

Return type:

dict

zea.data.metadata.selected_dimensions(key, num_dims, axis_selections)

Resolve {axis: selection} on key into {dimension name: selection}.

Naming the dimension is what lets the same take reach metadata laid out differently: axis 1 of data/raw_data is n_tx, which is axis 0 of scan.t0_delays. Empty for a key the spec cannot name, and for dimensions the take may not travel along (PROPAGATED_DIMENSIONS).

Return type:

dict[str, Any]

zea.data.metadata.selected_leaf_shape(path, shape, dim_selections, dim_sizes)

Return shape as it is after select_metadata_axes() narrows it.

Return type:

tuple

zea.data.metadata.slice_metadata(tree, frame_selection, n_frames, prefix='')

Return a copy of tree with per-frame fields sliced to the sample’s frames.

Parameters:

• tree (dict) – Nested metadata dict as returned by read_metadata().

• frame_selection – The frame selector used to read the sample’s images (a slice over the file’s frame axis).

• n_frames (int | None) – Total number of frames in the file, used to recognize which arrays actually carry a frame axis. None disables slicing.

• prefix (str) – Dotted prefix of tree within the file spec (internal).

Returns:

A new nested dict; unsliced values are shared, not copied.

Return type:

dict