zea.data.spec¶

Functions

`check_dtype`(value, expected_dtype)	Check if the dtype of a value matches the expected dtype, allowing for compatible types.
`find_matched_shape`(value, expected_shapes)	Find the first expected shape specification that matches the shape of the value.
`match_shape`(value, expected_shape)	Check if the shape of a value matches the expected shape specification.
`value_shape`(value)	Return the shape tuple for numpy arrays and scalar values.

Classes

`Annotations`([anatomy, view, label, ...])	Frame-level annotations, either per frame or broadcast labels.
`BeamformedData`(values[, extent, labels, ...])	Beamformed (beamsummed) data and spatial extent metadata.
`BooleanMap`(values[, extent, labels, ...])	Map data with bool pixel values and spatial extent metadata.
`ColorDopplerMap`(values[, extent, labels, ...])	Color Doppler (velocity) data and spatial extent metadata.
`DataSpec`([raw_data, aligned_data, ...])	Data group containing raw channels, derived pipeline products, and optional spatial maps.
`EnvelopeData`(values[, extent, labels, ...])	Envelope-detected data and spatial extent metadata.
`FileSpec`(data[, scan, metadata, metrics, ...])	A dataset containing all the data, scan parameters, metadata, and metrics for a single acquisition.
`FloatMap`(values[, extent, labels, ...])	Map data with float32 pixel values and spatial extent metadata.
`Image`(values[, extent, labels, description, ...])	Reconstructed (log-compressed) image data and spatial extent metadata.
`ImageSc`(values[, extent, labels, ...])	Scan-converted image data and spatial extent metadata.
`Map`(values[, extent, labels, description, ...])	Map data and spatial extent metadata.
`MetadataSpec`([subject, credit, probe_pose, ...])	Metadata group with subject, acquisition context, annotations, and extra signals.
`MetricsSpec`([common_midpoint_phase_error, ...])	Metrics group for acquisition-level quality/performance metrics.
`ProbePose`(start_time_offset, ...)	Sampled probe pose metadata at the tip of the transducer.
`ScanSpec`(probe_geometry, sampling_frequency, ...)	Scan group with acquisition and transmit metadata.
`Segmentation`(values[, extent, labels, ...])	Segmentation data and spatial extent metadata.
`ShearWaveElastographyMap`(values[, extent, ...])	Shear-wave elastography data and spatial extent metadata.
`Signal`(start_time_offset, sampling_frequency)	Base class for additional signals with timing and sampling-frequency metadata.
`Signal1D`(start_time_offset, ...)	One-dimensional sampled signal with timing metadata.
`SignalND`(start_time_offset, ...)	N-dimensional sampled signal with timing metadata.
`SosMap`(values[, extent, labels, ...])	Speed-of-sound map data and spatial extent metadata.
`Spec`()	Base class for data specifications with schema validation.
`StrainPercentageMap`(values[, extent, ...])	Strain map data and spatial extent metadata.
`Subject`([id, type, age, sex, fat_percentage])	Subject metadata associated with the study.
`TissueDopplerMap`(values[, extent, labels, ...])	Tissue Doppler data and spatial extent metadata.
`UnsignedIntMap`(values[, extent, labels, ...])	Map data with uint8 pixel values and spatial extent metadata.

class zea.data.spec.Annotations(anatomy=None, view=None, label=None, image_quality=None)[source]¶

Bases: Spec

Frame-level annotations, either per frame or broadcast labels.

Parameters:

anatomy (ndarray | str | None) – Anatomy label.
view (ndarray | None) – View label of shape (n_frames,).
label (ndarray | None) – Pathology or classification label of shape (n_frames,).
image_quality (ndarray | str | None) – Image quality label, e.g. low, mid, high.

anatomy: ndarray | str | None = None¶

image_quality: ndarray | str | None = None¶

label: ndarray | None = None¶

view: ndarray | None = None¶

class zea.data.spec.BeamformedData(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: FloatMap

Beamformed (beamsummed) data and spatial extent metadata.

Parameters:

values (ndarray) – The beamformed data of shape (n_frames, z, x, n_ch) or (n_frames, z, x, y, n_ch) and type float32. n_ch is 1 for RF data or 2 for IQ data.
extent (ndarray | None) – Spatial extent in meters of shape (n_frames, 6) or (6,). A shape of (6,) is broadcast to all frames. Values are ordered as (xmin, xmax, ymin, ymax, zmin, zmax) and stored as float32.
labels (ndarray | None) – The labels for the channel dimension, e.g. [“RF”] or [“I”, “Q”]. Auto-generated from n_ch if not provided.

class zea.data.spec.BooleanMap(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: Map

Map data with bool pixel values and spatial extent metadata.

class zea.data.spec.ColorDopplerMap(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: FloatMap

Color Doppler (velocity) data and spatial extent metadata.

Parameters:

values (ndarray) – The color Doppler velocity values in m/s of shape (n_frames, z, x, y) and type float32. Positive values indicate flow towards the transducer, negative values indicate flow away from the transducer.
extent (ndarray | None) – The color Doppler extent in meters of shape (n_frames, 6) or (6,).

class zea.data.spec.DataSpec(raw_data=None, aligned_data=None, beamformed_data=None, envelope_data=None, image_sc=None, image=None, segmentation=None, sos_map=None, strain_percentage_map=None, shear_wave_elastography_map=None, tissue_doppler=None, color_doppler=None, **extra_maps)[source]¶

Bases: Spec

Data group containing raw channels, derived pipeline products, and optional spatial maps.

Pipeline data products (plain arrays):

raw_data: Raw channel data of shape (n_frames, n_tx, n_ax, n_el, n_ch): and type float32 or int16.
aligned_data: Time-of-flight corrected data of shape: (n_frames, n_tx, n_ax, n_el, n_ch) and type float32 or int16.

Spatial map data products (with extent metadata):

beamformed_data: Beamformed (beamsummed) data and extent metadata.
envelope_data: Envelope-detected data and extent metadata.
image_sc: Scan-converted image data and extent metadata.
image: Reconstructed image data and extent metadata.
segmentation: Segmentation data and extent metadata.
sos_map: Speed-of-sound map data and extent metadata.
strain_percentage_map: Strain map data and extent metadata.
shear_wave_elastography_map: Shear-wave elastography data and extent metadata.
tissue_doppler: Tissue Doppler data and extent metadata.
color_doppler: Color Doppler velocity data and extent metadata.
**kwargs: Any other spatially aligned map data and extent metadata.

At least one data field (pipeline or spatial map) must be provided.

FIELD_METADATA = {'aligned_data': {'description': 'Time-of-flight corrected data.', 'unit': '-'}, 'raw_data': {'description': 'Raw channel data.', 'unit': '-'}}¶

aligned_data: ndarray | None = None¶

beamformed_data: BeamformedData | dict | None = None¶

color_doppler: ColorDopplerMap | dict | None = None¶

envelope_data: EnvelopeData | dict | None = None¶

image: Image | dict | None = None¶

image_sc: ImageSc | dict | None = None¶

raw_data: ndarray | None = None¶

segmentation: Segmentation | dict | None = None¶

shear_wave_elastography_map: ShearWaveElastographyMap | dict | None = None¶

sos_map: SosMap | dict | None = None¶

strain_percentage_map: StrainPercentageMap | dict | None = None¶

tissue_doppler: TissueDopplerMap | dict | None = None¶

class zea.data.spec.EnvelopeData(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: FloatMap

Envelope-detected data and spatial extent metadata.

Parameters:

values (ndarray) – The envelope data of shape (n_frames, x, z) or (n_frames, z, x, y) and type float32.
extent (ndarray | None) – Spatial extent in meters of shape (n_frames, 6) or (6,). A shape of (6,) is broadcast to all frames. Values are ordered as (xmin, xmax, ymin, ymax, zmin, zmax) and stored as float32.

class zea.data.spec.FileSpec(data, scan=None, metadata=<factory>, metrics=<factory>, probe_name=None, us_machine=None, description=None)[source]¶

Bases: Spec

A dataset containing all the data, scan parameters, metadata, and metrics for a single acquisition.

This class can be used to create a new dataset, which is validated upon initialization. Afterwards, it can be saved to disk as hdf5 file.

Parameters:

data (DataSpec | dict) – The data for the acquisition.
scan (ScanSpec | dict | None) – The scan parameters.
metadata (MetadataSpec | dict) – Additional metadata about the acquisition.
metrics (MetricsSpec | dict) – Metrics computed from the acquisition.
probe_name (str | None) – The name of the probe used to acquire the data.
us_machine (str | None) – The ultrasound machine used to acquire the data.

Example

>>> from zea.data.spec import FileSpec
>>> import numpy as np

>>> dataset = FileSpec(
...     data={
...         "raw_data": np.zeros((2, 4, 64, 8, 1), dtype=np.float32),
...     },
...     scan={
...         "probe_geometry": np.zeros((8, 3), dtype=np.float32),
...         "sampling_frequency": np.float32(40e6),
...         "center_frequency": np.float32(5e6),
...         "demodulation_frequency": np.float32(5e6),
...         "initial_times": np.zeros(4, dtype=np.float32),
...         "t0_delays": np.zeros((4, 8), dtype=np.float32),
...         "tx_apodizations": np.ones((4, 8), dtype=np.float32),
...         "focus_distances": np.full(4, np.inf, dtype=np.float32),
...         "transmit_origins": np.zeros((4, 3), dtype=np.float32),
...         "polar_angles": np.zeros(4, dtype=np.float32),
...     },
... )
>>> dataset.data.raw_data.shape
(2, 4, 64, 8, 1)

data: DataSpec | dict¶

description: str | None = None¶

classmethod from_hdf5(file)[source]¶

Load and validate a FileSpec from an open HDF5 file.

This reads all groups into memory and runs the full spec validation (dtype, shape, dimension consistency). Legacy files are handled transparently: extra scalar fields in the scan group (n_frames, n_tx, etc.) are ignored, flat data/image datasets are loaded as image_sc when image_sc is absent, and the probe root attribute is mapped to probe_name.

Parameters:: file (File) – An open h5py.File (or zea.File).
Returns:: A fully validated spec object.
Return type:: FileSpec

metadata: MetadataSpec | dict¶

metrics: MetricsSpec | dict¶

probe_name: str | None = None¶

save(path, compression='gzip')[source]¶

Save the dataset to the specified path.

Return type:: None

scan: ScanSpec | dict | None = None¶

us_machine: str | None = None¶

class zea.data.spec.FloatMap(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: Map

Map data with float32 pixel values and spatial extent metadata.

class zea.data.spec.Image(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: Map

Reconstructed (log-compressed) image data and spatial extent metadata.

Parameters:

values (ndarray) – The image values of shape (n_frames, z, x, y) or (n_frames, z, x) and type uint8 or float32. For float32 values, the values should be in dB (between -inf and 0).
extent (ndarray | None) – The image extent in meters of shape (n_frames, 6) or (6,). A shape of (6,) is broadcast to all frames. Values are ordered as (radius_min, radius_max, theta_min, theta_max, phi_min, phi_max) and stored as float32.

class zea.data.spec.ImageSc(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: Image

Scan-converted image data and spatial extent metadata.

Parameters:

values (ndarray) – The scan-converted values of shape (n_frames, z, x, y) or (n_frames, z, x) and type uint8 or float32. For float32 values, the values should be in dB (between -inf and 0).
extent (ndarray | None) – Spatial extent in meters of shape (n_frames, 6) or (6,). A shape of (6,) is broadcast to all frames. Values are ordered as (xmin, xmax, ymin, ymax, zmin, zmax) and stored as float32.

class zea.data.spec.Map(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: Spec

Map data and spatial extent metadata.

The most flexible map spec, which can be used for any spatially aligned data product.

Parameters:

values (ndarray) – The map values of shape (n_frames, z, x, y, n_ch) or (n_frames, z, x, y) or (n_frames, z, x, n_ch) or (n_frames, z, x) and type uint8 or float32 or int16.
extent (ndarray | None) – The map extent in meters of shape (n_frames, 6) or (6,). A shape of (6,) is broadcast to all frames. Values are ordered as (xmin, xmax, ymin, ymax, zmin, zmax) and stored as float32.
labels (ndarray | None) – The labels corresponding to the n_ch channels in the values. This is required when values have an n_ch dimension, and should be None otherwise. For IQ data, this would typically be [“I”, “Q”].
description (str | None) – An optional free-text description of the map.
unit (str | None) – An optional string specifying the physical unit of the map values, e.g. “m/s”, “%”, etc.
min (float | None) – The minimum value of the map.
max (float | None) – The maximum value of the map.

description: str | None = None¶

extent: ndarray | None = None¶

labels: ndarray | None = None¶

max: float | None = None¶

min: float | None = None¶

unit: str | None = None¶

values: ndarray¶

class zea.data.spec.MetadataSpec(subject=None, credit=None, probe_pose=None, voice_narration=None, ecg=None, text_report=None, annotations=None, **extra_signals)[source]¶

Bases: Spec

Metadata group with subject, acquisition context, annotations, and extra signals.

FIELD_METADATA = {'annotations': {'description': 'Frame-level annotations.', 'unit': '-'}, 'credit': {'description': 'Credit or attribution for the dataset.', 'unit': '-'}, 'ecg': {'description': 'Electrocardiogram signal.', 'unit': '-'}, 'probe_pose': {'description': 'Sampled probe pose at the transducer tip.', 'unit': '-'}, 'text_report': {'description': 'Free-text report associated with the study.', 'unit': '-'}, 'voice_narration': {'description': 'Voice narration signal.', 'unit': '-'}}¶

annotations: Annotations | dict | None = None¶

credit: str | None = None¶

ecg: Signal1D | dict | None = None¶

probe_pose: ProbePose | dict | None = None¶

subject: Subject | dict¶

text_report: str | None = None¶

voice_narration: Signal1D | dict | None = None¶

class zea.data.spec.MetricsSpec(common_midpoint_phase_error=None, coherence_factor=None)[source]¶

Bases: Spec

Metrics group for acquisition-level quality/performance metrics.

Parameters:

common_midpoint_phase_error (ndarray | None) – Common midpoint phase error in radians of shape (n_frames,) and type float32.
coherence_factor (ndarray | None) – Coherence factor of shape (n_frames,) and type float32.

coherence_factor: ndarray | None = None¶

common_midpoint_phase_error: ndarray | None = None¶

class zea.data.spec.ProbePose(start_time_offset, sampling_frequency, translation, rotation, rotation_representation)[source]¶

Bases: Signal

Sampled probe pose metadata at the tip of the transducer.

The pose uses the coordinate convention x = lateral along the transducer, y = elevation (out of plane), and z = axial (depth).

Parameters:

translation (ndarray) – Position of the transducer tip in meters of shape (T, 3), ordered as (x, y, z).
rotation (ndarray) – Orientation of the transducer tip of shape (T, 3) or (T, 4), interpreted according to rotation_representation.
rotation_representation (str) – Rotation parameterization. Supported values are "euler_xyz", "quaternion_wxyz", and "quaternion_xyzw".
start_time_offset (ndarray | float) – Time offset in seconds between the first transmit event of the ultrasound acquisition and sample 0 of this data.
sampling_frequency (ndarray | float) – Sampling frequency in Hz for probe pose samples.

FIELD_METADATA = {'rotation': {'description': 'Orientation associated with the transducer-tip pose in the x-lateral, y-elevation, z-axial coordinate convention, interpreted according to rotation_representation.', 'unit': '-'}, 'rotation_representation': {'description': 'Rotation parameterization: one of euler_xyz, quaternion_wxyz, or quaternion_xyzw.', 'unit': '-'}, 'sampling_frequency': {'description': 'Sampling frequency.', 'unit': 'Hz'}, 'start_time_offset': {'description': 'Time offset between the first transmit event of the ultrasound acquisition and sample 0 of this data. Negative means this data starts before the first transmit event; positive means it starts after.', 'unit': 's'}, 'translation': {'description': 'Position of the transducer tip, ordered as (x, y, z), where x is lateral along the transducer, y is elevation (out of plane), and z is axial (depth).', 'unit': 'm'}}¶

rotation: ndarray¶

rotation_representation: str¶

translation: ndarray¶

class zea.data.spec.ScanSpec(probe_geometry, sampling_frequency, center_frequency, demodulation_frequency, initial_times, t0_delays, tx_apodizations, focus_distances, transmit_origins, polar_angles, time_to_next_transmit=None, azimuth_angles=None, sound_speed=None, tgc_gain_curve=None, element_width=None, waveforms_one_way=None, waveforms_two_way=None)[source]¶

Bases: Spec

Scan group with acquisition and transmit metadata.

All fields are aligned with the data format specification.

Parameters:

probe_geometry (ndarray) – The probe geometry in meters of shape (n_el, 3), represented as (x, y, z) coordinates.
sampling_frequency (ndarray | float) – The sampling frequency in Hz.
center_frequency (ndarray | float) – The center frequency in Hz of the transmit pulse. Single scalar if all transmits share the same center frequency; otherwise an array of shape (n_tx,) with one frequency per transmit.
demodulation_frequency (ndarray | float) – The frequency in Hz at which the data should be demodulated. Usually the same as center_frequency, but different when doing harmonic imaging. Single scalar if all transmits share the same center frequency; otherwise an array of shape (n_tx,) with one frequency per transmit.
initial_times (ndarray) – The times in seconds when the A/D converter starts sampling of shape (n_tx,). This is the time between the first element firing and the first recorded sample.
t0_delays (ndarray) – The transmit delays in seconds for each element of shape (n_tx, n_el). This is the time at which each element fires, shifted such that the first element fires at t=0.
tx_apodizations (ndarray) – The apodization values that were applied to each element during transmit of shape (n_tx, n_el). This is a value between -1 and 1 that indicates how much each element contributed to the transmit beam, with 0 meaning no contribution and 1 meaning full contribution. Negative values indicate that the element was fired with opposite polarity.
focus_distances (ndarray) – The transmit focus distances in meters of shape (n_tx,). This is the distance from the origin point on the transducer to where the beam comes to focus. For planewaves this is set to infinity or zero.
transmit_origins (ndarray) – The transmit origins of the transmit beams in meters of shape (n_tx, 3). This is the (x, y, z) position from which the beam is transmitted.
polar_angles (ndarray) – The polar angles in radians of the transmit beams of shape (n_tx,).
time_to_next_transmit (ndarray) – The time in s between subsequent transmit events of shape (n_frames, n_tx).
azimuth_angles (ndarray) – The azimuthal angles in radians of the transmit beams of shape (n_tx,).
sound_speed (ndarray | float | None) – The speed of sound in meters per second.
tgc_gain_curve (ndarray | None) – The time-gain-compensation that was applied to every sample in the raw_data of shape (n_ax,). Divide by this curve to undo the TGC.
element_width (ndarray | float | None) – The width of the elements in the probe in meters.
waveforms_one_way (ndarray | None) – One-way waveforms of shape (n_tx, .) as simulated by the Verasonics system. This is the waveform after being filtered by the transducer bandwidth once.
waveforms_two_way (ndarray | None) – Two-way waveforms of shape (n_tx, .) as simulated by the Verasonics system. This is the waveform after being filtered by the transducer bandwidth twice.

FIELD_METADATA = {'azimuth_angles': {'description': 'Azimuthal angles of transmit beams.', 'unit': 'rad'}, 'center_frequency': {'description': 'Center frequency of the transmit pulse.', 'unit': 'Hz'}, 'demodulation_frequency': {'description': 'Demodulation frequency.', 'unit': 'Hz'}, 'element_width': {'description': 'Element width of the probe.', 'unit': 'm'}, 'focus_distances': {'description': 'Transmit focus distances.', 'unit': 'm'}, 'initial_times': {'description': 'A/D converter start times per transmit.', 'unit': 's'}, 'polar_angles': {'description': 'Polar angles of transmit beams.', 'unit': 'rad'}, 'probe_geometry': {'description': 'Probe geometry (x, y, z) per element.', 'unit': 'm'}, 'sampling_frequency': {'description': 'Sampling frequency.', 'unit': 'Hz'}, 'sound_speed': {'description': 'Speed of sound.', 'unit': 'm/s'}, 't0_delays': {'description': 'Transmit delays per element.', 'unit': 's'}, 'tgc_gain_curve': {'description': 'Time-gain-compensation curve.', 'unit': '-'}, 'time_to_next_transmit': {'description': 'Time between transmit events.', 'unit': 's'}, 'transmit_origins': {'description': 'Transmit beam origins (x, y, z).', 'unit': 'm'}, 'tx_apodizations': {'description': 'Transmit apodization per element.', 'unit': '-'}, 'waveforms_one_way': {'description': 'One-way transmit waveforms.', 'unit': 'V'}, 'waveforms_two_way': {'description': 'Two-way transmit waveforms.', 'unit': 'V'}}¶

azimuth_angles: ndarray = None¶

center_frequency: ndarray | float¶

demodulation_frequency: ndarray | float¶

element_width: ndarray | float | None = None¶

focus_distances: ndarray¶

initial_times: ndarray¶

property n_el: int¶: Number of elements.

property n_tx: int¶: Number of transmits.

polar_angles: ndarray¶

probe_geometry: ndarray¶

sampling_frequency: ndarray | float¶

sound_speed: ndarray | float | None = None¶

t0_delays: ndarray¶

tgc_gain_curve: ndarray | None = None¶

time_to_next_transmit: ndarray = None¶

transmit_origins: ndarray¶

tx_apodizations: ndarray¶

waveforms_one_way: ndarray | None = None¶

waveforms_two_way: ndarray | None = None¶

class zea.data.spec.Segmentation(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: BooleanMap

Segmentation data and spatial extent metadata.

Parameters:

values (ndarray) – The segmentation values of shape (n_frames, z, x, y, n_labels) and type bool.
extent (ndarray | None) – The segmentation extent in meters of shape (n_frames, 6) or (6,). A shape of (6,) is broadcast to all frames. Values are ordered as (xmin, xmax, ymin, ymax, zmin, zmax) and stored as float32.
labels (ndarray | None) – The labels corresponding to the segmentation values, where each unique value in the values corresponds to a label in this list of shape (n_labels,) and type str.

class zea.data.spec.ShearWaveElastographyMap(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: FloatMap

Shear-wave elastography data and spatial extent metadata.

Parameters:

values (ndarray) – The shear-wave elastography values in m/s of shape (n_frames, z, x, y) and type float32.
extent (ndarray | None) – The SWE extent in meters of shape (n_frames, 6) or (6,).

class zea.data.spec.Signal(start_time_offset, sampling_frequency)[source]¶

Bases: Spec

Base class for additional signals with timing and sampling-frequency metadata.

Parameters:

start_time_offset (ndarray | float) – Time offset in seconds between the first transmit event of the ultrasound acquisition and sample 0 of this data. Negative means this data starts before the first transmit event; positive means it starts after.
sampling_frequency (ndarray | float) – Sampling frequency in Hz for the additional signal samples.

FIELD_METADATA = {'sampling_frequency': {'description': 'Sampling frequency.', 'unit': 'Hz'}, 'start_time_offset': {'description': 'Time offset between the first transmit event of the ultrasound acquisition and sample 0 of this data. Negative means this data starts before the first transmit event; positive means it starts after.', 'unit': 's'}}¶

sampling_frequency: ndarray | float¶

start_time_offset: ndarray | float¶

class zea.data.spec.Signal1D(start_time_offset, sampling_frequency, samples)[source]¶

Bases: Signal

One-dimensional sampled signal with timing metadata.

Parameters:

samples (ndarray) – Signal samples of shape (T) and type uint8 or float32 or int16 or complex64.
start_time_offset (ndarray | float) – Time offset in seconds between the first transmit event of the ultrasound acquisition and sample 0 of this data.
sampling_frequency (ndarray | float) – Sampling frequency in Hz for signal samples.

FIELD_METADATA = {'samples': {'description': 'Signal samples.', 'unit': '-'}, 'sampling_frequency': {'description': 'Sampling frequency.', 'unit': 'Hz'}, 'start_time_offset': {'description': 'Time offset between the first transmit event of the ultrasound acquisition and sample 0 of this data. Negative means this data starts before the first transmit event; positive means it starts after.', 'unit': 's'}}¶

samples: ndarray¶

class zea.data.spec.SignalND(start_time_offset, sampling_frequency, samples)[source]¶

Bases: Signal

N-dimensional sampled signal with timing metadata.

Parameters:

samples (ndarray) – Signal samples of shape (T, …) and type uint8 or float32 or int16 or complex64.
start_time_offset (ndarray | float) – Time offset in seconds between the first transmit event of the ultrasound acquisition and sample 0 of this data.
sampling_frequency (ndarray | float) – Sampling frequency in Hz for signal samples.

FIELD_METADATA = {'samples': {'description': 'Signal samples.', 'unit': '-'}, 'sampling_frequency': {'description': 'Sampling frequency.', 'unit': 'Hz'}, 'start_time_offset': {'description': 'Time offset between the first transmit event of the ultrasound acquisition and sample 0 of this data. Negative means this data starts before the first transmit event; positive means it starts after.', 'unit': 's'}}¶

samples: ndarray¶

class zea.data.spec.SosMap(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: FloatMap

Speed-of-sound map data and spatial extent metadata.

Parameters:

values (ndarray) – The speed-of-sound map values in m/s of shape (n_frames, z, x, y) and type float32.
extent (ndarray | None) – The speed-of-sound map extent in meters of shape (n_frames, 6) or (6,). A shape of (6,) is broadcast to all frames. Values are ordered as (xmin, xmax, ymin, ymax, zmin, zmax) and stored as float32.

class zea.data.spec.Spec[source]¶

Bases: object

Base class for data specifications with schema validation.

Subclasses should define a SCHEMA class variable that specifies the expected dtype and shape for each field. The __post_init__ method will validate that the actual fields match the schema, including checking that dimensions with the same name have consistent sizes across fields.

static create_dataset(group, field_name, value, compression='gzip')[source]¶

Create a dataset in the given group for the specified field and value, handling string and scalar values appropriately.

Return type:: None

classmethod fields()[source]¶

Return the names of all fields.

Return type:: tuple[str, ...]

classmethod get_dtype(field_name)[source]¶

Get the dtype of a field.

Return type:: Union[Tuple[type, ...], type]

classmethod optional_fields()[source]¶

Return the names of fields that have a default value.

Return type:: tuple[str, ...]

classmethod required_fields()[source]¶

Return the names of fields that have no default value.

Return type:: tuple[str, ...]

store_in_group(group, compression='gzip')[source]¶

Store the data in the given group (e.g. hdf5 group).

Return type:: None

to_dict()[source]¶

Return this spec as a nested dictionary based on SCHEMA fields.

Nested specs are converted recursively.

Return type:: dict[str, Any]

class zea.data.spec.StrainPercentageMap(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: FloatMap

Strain map data and spatial extent metadata.

Parameters:

values (ndarray) – The strain values in % of shape (n_frames, z, x, y) and type float32.
extent (ndarray | None) – The strain extent in meters of shape (n_frames, 6) or (6,). A shape of (6,) is broadcast to all frames. Values are ordered as (xmin, xmax, ymin, ymax, zmin, zmax) and stored as float32.

class zea.data.spec.Subject(id=None, type=None, age=None, sex=None, fat_percentage=None)[source]¶

Bases: Spec

Subject metadata associated with the study.

Parameters:

type (str | None) – Subject type, e.g. human, phantom, animal.
age (uint8 | None) – Subject age in years.
sex (str | None) – Subject sex.
fat – Subject fat percentage.

age: uint8 | None = None¶

fat_percentage: float32 | None = None¶

id: str | None = None¶

sex: str | None = None¶

type: str | None = None¶

class zea.data.spec.TissueDopplerMap(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: FloatMap

Tissue Doppler data and spatial extent metadata.

Parameters:

values (ndarray) – The tissue Doppler values in m/s of shape (n_frames, z, x, y) and type float32.
extent (ndarray | None) – The tissue Doppler extent in meters of shape (n_frames, 6) or (6,).

class zea.data.spec.UnsignedIntMap(values, extent=None, labels=None, description=None, unit=None, min=None, max=None)[source]¶

Bases: Map

Map data with uint8 pixel values and spatial extent metadata.

zea.data.spec.check_dtype(value, expected_dtype)[source]¶

Check if the dtype of a value matches the expected dtype, allowing for compatible types.

Works for numpy arrays, numpy scalars, and Python native types.

Return type:: None

zea.data.spec.find_matched_shape(value, expected_shapes)[source]¶

Find the first expected shape specification that matches the shape of the value.

Return type:: tuple | None

zea.data.spec.match_shape(value, expected_shape)[source]¶

Check if the shape of a value matches the expected shape specification.

Return type:: bool

zea.data.spec.value_shape(value)[source]¶

Return the shape tuple for numpy arrays and scalar values.

Return type:: tuple