zea.data.convert.echoxflow¶

Convert EchoXFlow 2d_brightness_mode recordings to the zea HDF5 format.

Finds all recordings with at least --min-frames B-mode frames and a frame rate above --min-fps, then writes each as a zea-format HDF5 file under dst, laid out as <dst>/<exam_id>/<recording_id>.hdf5.

Usage:

python -m zea.data.convert echoxflow <src> <dst>
python -m zea.data.convert echoxflow <src> <dst> --limit 2

src is the EchoXFlow data root (e.g. /data/EchoXFlow/data) containing a croissant.json catalog. Reading EchoXFlow recordings requires the optional echoxflow package (https://github.com/Ahus-AIM/EchoXFlow), which is not published on PyPI; install it directly from GitHub:

pip install "echoxflow @ git+https://github.com/Ahus-AIM/EchoXFlow.git"

EchoXFlow declares requires-python = ">=3.13", but the reader also runs on Python 3.11/3.12 (only pip’s metadata check blocks it); there, append --ignore-requires-python to the command above.

Functions

build_metadata(record, bmode_stream, store)

Collect EchoXFlow metadata that maps onto zea's MetadataSpec.

convert_echoxflow(args)

Convert EchoXFlow 2d_brightness_mode recordings into zea HDF5 files.

make_dataset_card(repo_id)

Build a HuggingFace dataset card (README.md) for the converted dataset.

sector_coordinates(geometry, height, width)

Build a zea per-pixel Cartesian coordinate grid from EchoXFlow SectorGeometry.

upload_echoxflow(output_folder, revision, ...)

Upload a converted EchoXFlow dataset to a HuggingFace Hub revision branch.
zea.data.convert.echoxflow.build_metadata(record, bmode_stream, store)[source]¶

Collect EchoXFlow metadata that maps onto zea’s MetadataSpec.

  • subject.id <- exam_id (enables subject-wise splits)

  • ecg <- the recording’s ECG signal, if present (Signal1D)

Return type:

dict

zea.data.convert.echoxflow.convert_echoxflow(args)[source]¶

Convert EchoXFlow 2d_brightness_mode recordings into zea HDF5 files.

Each qualifying recording is written to <dst>/<exam_id>/<recording_id>.hdf5.

Usage:

python -m zea.data.convert echoxflow <src> <dst>
python -m zea.data.convert echoxflow <src> <dst> --limit 2
Parameters:

args (argparse.Namespace) –

An object with attributes:

  • src (str | Path): EchoXFlow data root containing croissant.json.

  • dst (str | Path): Destination directory for zea HDF5 files.

  • croissant (str | None): Path to croissant.json (default: <src>/croissant.json).

  • min_frames (int): Minimum B-mode frame count.

  • min_fps (float): Minimum frame rate (Hz).

  • limit (int | None): Convert at most N recordings.

  • overwrite (bool): Overwrite existing output files.

  • upload (bool): Upload the converted dataset to HuggingFace Hub.

  • revision (str | None): Target branch on the Hub. Required when upload is set; upload to main is blocked.

  • hf_repo_id (str): HuggingFace repo id for ownership checks and optional upload. Defaults to zeahub/echoxflow when empty.

zea.data.convert.echoxflow.make_dataset_card(repo_id)[source]¶

Build a HuggingFace dataset card (README.md) for the converted dataset.

The zea_repo_id front-matter field is what the output-directory ownership checks key on, so it must match repo_id.

Return type:

str

zea.data.convert.echoxflow.sector_coordinates(geometry, height, width)[source]¶

Build a zea per-pixel Cartesian coordinate grid from EchoXFlow SectorGeometry.

EchoXFlow B-mode frames are sampled on a polar (sector) grid whose rows span the depth (radial) axis and whose columns span the steering angle (polar) axis. zea’s polar_pixel_grid maps that to Cartesian (x, y, z) positions in metres.

Returns an array of shape (height, width, 3) (broadcast across frames), or None if the recording has no geometry.

Return type:

ndarray | None

zea.data.convert.echoxflow.upload_echoxflow(output_folder, revision, repo_id)[source]¶

Upload a converted EchoXFlow dataset to a HuggingFace Hub revision branch.

Only for zea maintainers with push access to the repository. Upload to main is blocked; merge the revision branch into main manually after verifying the upload.

Parameters:

  • output_folder (str | Path) – Directory containing the converted HDF5 files.

  • revision (str) – Target branch name on the Hub (must not be "main").

  • repo_id (str) – Target HuggingFace repository ID.

Return type:

None