zea.data.convert.echoxflow¶

Convert the EchoXFlow dataset to the zea format.

EchoXFlow is a public echocardiography dataset from Akershus University Hospital: 666 routine-care examinations with 35,377 recordings, stored in the scanner’s native beamspace (polar) grid before scan conversion. It covers 1-D, 2-D and 3-D B-mode, colour, tissue and spectral Doppler, with a co-registered ECG and dense and sparse annotations.

This converter only takes the single-plane 2-D B-mode recordings and writes each one to its own zea HDF5 file. Each file holds:

  • the B-mode frames (uint8, still on the beamspace grid),

  • the Cartesian (x, y, z) position of every pixel, from the sector geometry,

  • the frame timestamps,

  • the ECG, if the recording has one,

  • the exam ID, stored as metadata/subject/id. It groups recordings by examination, not by patient: one patient can have several exams, so do not use it for patient-disjoint splits. Use splits.csv from the original dataset for that.

Limitations

The result is a filtered subset of EchoXFlow, not the full dataset:

  • Other modalities (M-mode, multi-plane and 3-D B-mode, all Doppler) are skipped.

  • Recordings with fewer than --min-frames frames (default 10) or a frame rate of --min-fps or lower (default 30 Hz) are skipped. This drops probe-positioning sweeps and single-frame captures.

  • Annotations, most recording metadata, the patient-level splits (splits.csv) and the view labels are not converted. You can join them back from the original dataset using the exam and recording IDs in the output paths.

License

CC BY-NC-SA 4.0 - https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode

Non-commercial use only. Converted data must be shared under the same license, with credit to the EchoXFlow authors.

Reference

E. Stenhede, J. Sulkowska, E. B. Orstad, H. Schirmer, and A. Ranjbar, “EchoXFlow: A Beamspace Echocardiography Dataset for Cardiac Motion, Flow, and Function,” in Advances in Neural Information Processing Systems (NeurIPS), Datasets and Benchmarks Track, 2026. arXiv:2605.05447

Links

Usage

Download and extract EchoXFlow as described on its dataset page. Then point the converter at the data root, which is the folder containing croissant.json. The output is laid out as <dst>/data/<exam_id>/<recording_id>.hdf5, next to a dataset card (README.md) and the EchoXFlow LICENSE.

zea convert echoxflow /data/EchoXFlow/data ./output
zea convert echoxflow /data/EchoXFlow/data ./output --limit 2

Note

Reading EchoXFlow needs the echoxflow package. It is not on PyPI, so install it from GitHub:

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

The package declares Python >= 3.13, but the reader also works on 3.11 and 3.12. On those versions, add --ignore-requires-python to the command.

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, min_frames, ...)

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 (groups by examination, not by patient; use the original splits.csv for patient-disjoint folds)

  • 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>/data/<exam_id>/<recording_id>.hdf5. A dataset card (README.md) and the EchoXFlow LICENSE are written to <dst>.

Usage:

zea convert echoxflow <src> <dst>
zea 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, min_frames, min_fps, num_recordings, num_exams, size_gb)[source]¶

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

The card credits the original EchoXFlow dataset, carries its CC BY-NC-SA 4.0 license and lists what this subset leaves out. The counts, size and filter settings come from the conversion run, so the card matches the uploaded files.

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