MiracleDataset

class irdl.MiracleDataset

Bases: IstaBaseDataset

Download the MIRACLE database from DepositOnce.

Attributes:

namestr

Dataset name (“miracle”).

doistr

Digital Object Identifier (“10.14279/depositonce-20837”).

room_volumefloat

Room volume in cubic meters (830).

measurement_datefloat

Release date in POSIX seconds, used as the SOFA MeasurementDate (no per-measurement date is available).

_category = 'room_impulse_responses'

_download(provider_dir: Path, **dataset_kwargs) → Path

Download MIRACLE dataset file.

Downloads the full scenario HDF5 file. If a split is requested, the split will be extracted in _process().

Parameters:

provider_dirpathlib.Path

Provider directory (e.g., cache/MIRACLE/provider/).

**dataset_kwargsdict

Must contain ‘scenario’. May contain ‘dataset_split’.

Returns:

pathlib.Path

Path to the downloaded full scenario HDF5 file inside the provider directory.

_extract_split(ingest_path: Path, dataset_split: str, output_path: Path) → Path

Extract a dataset split from a full MIRACLE HDF5 file.

Reads the full file, indexes the requested quadrant of the source grid, and writes the result to a new HDF5 file.

Parameters:

ingest_pathpathlib.Path

Path to the full HDF5 file in the provider directory.

dataset_splitstr

Split to extract. One of ‘C1’, ‘C2’, ‘C3’, ‘C4’.

output_pathpathlib.Path

Target path in the ingest directory.

Returns:

pathlib.Path

Path to the extracted split HDF5 file.

_process(provider_artifact: Path, ingest_path: Path, **dataset_kwargs) → Path

Post-process MIRACLE file if needed.

If a dataset_split is requested and the file is the full scenario file, extracts the corresponding quadrant split into the ingest directory. Otherwise promotes the provider file to the ingest stage.

Parameters:

provider_artifactpathlib.Path

Path to the provider file (full scenario HDF5).

ingest_pathpathlib.Path

Path to the HDF5 file in the ingest directory.

**dataset_kwargsdict

Must contain ‘scenario’. May contain ‘dataset_split’.

Returns:

pathlib.Path

Path to the processed file in the ingest directory.

_validate_params(**dataset_kwargs) → None

Validate MIRACLE-specific parameters.

Parameters:

**dataset_kwargsdict

Must contain ‘scenario’ (one of ‘A1’, ‘A2’, ‘D1’, ‘R2’). May contain ‘dataset_split’ (one of ‘C1’, ‘C2’, ‘C3’, ‘C4’, or None). Scenario ‘D1’ cannot be split. output_format is also passed but unused here.

Raises:

ValueError

If scenario or split is out of range, or ‘D1’ is combined with a split.

doi: str = '10.14279/depositonce-20837'

classmethod get(scenario: str = 'A1', dataset_split: str | None = None, cache_dir: str | Path | None = None, export_dir: str | Path | None = None, output_format: str = 'pyfar') → dict | Path | None

Download the MIRACLE database from DepositOnce.

DOI: https://doi.org/10.14279/depositonce-20837

Parameters:

cache_dirstr

Cache directory for downloads. Defaults is the OS user cache directory. This default can be overridden by setting IRDL_CACHE_DIR environment variable.

export_dirstr, optional

Directory for final output. If specified, the data will be exported to <export_dir/MIRACLE/>. Else, it remains in <cache_dir/output/>.

output_formatstr

Output format: ‘pyfar’, ‘numpy’, ‘hdf5’, ‘sofa’, or ‘raw’.

scenariostr

Scenario to download. One of ‘A1’, ‘A2’, ‘D1’, ‘R2’.

dataset_splitstr or None, optional

Artificial dataset split. One of ‘C1’, ‘C2’, ‘C3’, ‘C4’ or None. Dense scenarios (D1) cannot be split.

Returns:

dict or Path

For ‘pyfar’ / ‘numpy’: dict of in-memory objects. For ‘sofa’ / ‘hdf5’ / ‘raw’: Path to file on disk.

measurement_date = 1697068800.0

name: str = 'miracle'

room_volume = 830