Skip to content

HDF5

rddac.open_h5 and rddac.inspect_h5 are the top level helpers for reading and inspecting a single experiment. Both are re-exported at the package root (rddac.open_h5, rddac.inspect_h5); the implementation lives in rddac.h5_tools.

rddac.open_h5

open_h5(experiment_id: int, source: str | Path | None = None, data_dir: str | Path | None = DEFAULT_DATA_DIR, dataset=None) -> h5py.File

Return an h5py.File for the requested RDDAC experiment.

Looks the manifest up, walks the locally mapped zips and reads the h5 member matching the zero-padded <experiment_id>.h5 (e.g. 0042.h5) into a BytesIO. The returned object is read-only, supports the with idiom and can be indexed like any other h5py.File.

Parameters:

Name Type Description Default
experiment_id int

The experiment index (matches the h5 filename inside the zip; 42 -> 0042.h5).

 required
source str | Path | None

Override the Croissant manifest URL / path.

 None
data_dir str | Path | None

Directory searched for already-downloaded zips. Pass None to skip the local lookup entirely.

 DEFAULT_DATA_DIR
dataset

A pre-loaded mlcroissant.Dataset (e.g. from rddac.load). When given, source and data_dir are ignored.

 None

Raises:

Type Description
FileNotFoundError

No locally mapped zip contained the requested h5.
Source code in rddac/h5_tools.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def open_h5(
    experiment_id: int,
    source: str | Path | None = None,
    data_dir: str | Path | None = DEFAULT_DATA_DIR,
    dataset=None,
) -> h5py.File:
    """Return an `h5py.File` for the requested RDDAC experiment.

    Looks the manifest up, walks the locally mapped zips and reads the h5
    member matching the zero-padded ``<experiment_id>.h5`` (e.g. ``0042.h5``)
    into a `BytesIO`. The returned object is read-only, supports the `with`
    idiom and can be indexed like any other `h5py.File`.

    Args:
        experiment_id: The experiment index (matches the h5 filename inside
            the zip; ``42`` -> ``0042.h5``).
        source: Override the Croissant manifest URL / path.
        data_dir: Directory searched for already-downloaded zips. Pass `None`
            to skip the local lookup entirely.
        dataset: A pre-loaded `mlcroissant.Dataset` (e.g. from `rddac.load`).
            When given, `source` and `data_dir` are ignored.

    Raises:
        FileNotFoundError: No locally mapped zip contained the requested h5.
    """
    return _ddacs_h5_tools.open_h5(
        experiment_id, source=source, data_dir=data_dir, dataset=dataset, spec=RDDAC_SPEC
    )

rddac.inspect_h5

inspect_h5(file_or_path: h5py.File | str | Path) -> None

Pretty-print the group/dataset hierarchy of an HDF5 file.

Accepts either an open h5py.File (e.g. from ddacs.open_h5) or a path on disk. Prints to stdout and returns nothing.

Source code in ddacs/h5_tools.py 
82
83
84
85
86
87
88
89
90
91
92
def inspect_h5(file_or_path: h5py.File | str | Path) -> None:
    """Pretty-print the group/dataset hierarchy of an HDF5 file.

    Accepts either an open `h5py.File` (e.g. from `ddacs.open_h5`) or a path
    on disk. Prints to stdout and returns nothing.
    """
    if isinstance(file_or_path, h5py.File):
        _print_tree(file_or_path)
    else:
        with h5py.File(file_or_path, "r") as f:
            _print_tree(f)