ARI¶

ARI is a public head-related transfer function database from the Acoustic Research Institute of the Austrian Academy of Sciences. In hrtfpykit, ARI maps the ARI SOFA files and aligned subject resources into the package’s shared dataset interface.

The ARI integration is designed for workflows that need acoustic HRTF data and optional subject resources under the same map-style dataset object. Acoustic specs load the subject SOFA file through load_hrtf(), and resource specs can request the ARI anthropometry and metadata CSV files when those resources are present or downloaded.

Dataset scope.

hrtfpykit configures ARI subject identifiers from the official HRTF files included in the checksum map. The exposed subject IDs use the nh form, such as nh2, nh720, or nh1059. The ARI configuration contains 263 subject HRTF files.

The ARI resources used by hrtfpykit are:

HRTF SOFA files for acoustic data.
anthro.csv for numeric anthropometry measurements.
metadata.csv for subject descriptors such as sex, age, weight, and recording dates.

The anthropometry and metadata CSV resources are derived from the public ARI anthro.mat MATLAB file and are stored as separate tables so they can be requested independently with AnthropometrySpec and MetadataSpec.

Layout and subject paths.

ARI HRTF filenames are not generated from one common subject path template. The configuration therefore stores a subject path map from each canonical subject ID to its SOFA filename. Examples include hrtf b_nh2.sofa, hrtf c_nh831.sofa, and hrtf d_nh1059.sofa.

The official ARI HRTF files are distributed in b, c, and d filename groups. hrtfpykit treats the included files as one compatible ARI HRTF collection because they share the same source grid, IR shape, and sample rate. The dataset class does not expose a public group selector. If a workflow needs only a subset of ARI subjects, pass exclude_subject_ids when constructing the dataset.

ARI anthropometry uses shared measurement columns such as x1 and ear measurement columns with L_ and R_ prefixes. When AnthropometrySpec requests ear="left" or ear="right", hrtfpykit returns the shared fields plus the fields that match the requested ear prefix.

Downloads.

The built-in downloader supports the hrtf, anthropometry, and metadata resource groups. Set download=True to download resources before dataset construction, and use download_resources to choose which resource groups to fetch.

ARI does not use download_hrtf_variant or dataset_hrtf_variant. The HRTF resource family is represented by the configured subject path map.

By default, downloads verify SHA-256 checksums. verify_checksum=False skips checksum verification when that behavior is explicitly required, but keeping checksum verification enabled is recommended.

References.

class hrtfpykit.datasets.ARI(root, dataset_hrtf_transform=None, download=False, download_resources='hrtf', verify_checksum=True, exclude_subject_ids=None, inputs=None, target=None, split='all', split_ratio=(0.8, 0.1, 0.1), split_seed=0, verbose=False)¶

Build an ARI dataset instance.

ARI resolves the local ARI resources declared by ARIConfig, including HRTF SOFA files, anthropometry CSV data, and metadata CSV data. It applies subject exclusions and split selection, and returns samples defined by the requested input and target specs.

Acoustic specs load one subject HRTF with load_hrtf(). When dataset_hrtf_transform is provided, the loaded HRTF is transformed before specs extract IR/TF values or calculate derived values such as ITD, ILD, or spherical harmonic coefficients.

Parameters:

root (str or Path) – Local ARI dataset root.
dataset_hrtf_transform (callable or None, default=None) – Optional transform applied to every loaded HRTF before any acoustic spec is evaluated. Spec transforms are applied after this dataset transform and before value extraction or derived cue calculation.
download (bool, default=False) – If True, downloads selected official ARI resources before dataset construction.
download_resources (str or sequence of str, default=``hrtf``) – Official resources requested for download. ARI provides HRTF SOFA files, anthropometry CSV data, and metadata CSV data.
verify_checksum (bool, default=True) – Whether official SHA-256 checksums are verified during resource download. Keeping this enabled is the recommended behavior. Set it to False only when checksum verification should be skipped; file existence and non empty checks still run.
exclude_subject_ids (str, int, sequence, or None, default=None) – ARI subjects excluded before scanning and splitting.
inputs (spec, sequence of specs, or None, default=None) – Specs exposed under sample inputs.
target (spec, sequence of specs, or None, default=None) – Specs exposed under sample targets.
split ({all, train, validation, test}, default=``all``) – Subject split used by this dataset instance.
split_ratio (tuple of float, default=(0.8, 0.1, 0.1)) – Train, validation, and test split ratios.
split_seed (int, default=0) – Random seed used for deterministic split assignment.
verbose (bool, default=False) – If True, prints resource and dataset summaries. Download summaries print whenever files are downloaded.

Returns:

Dataset object supporting indexed sample extraction and subject HRTF loading.

Return type:

ARI

Notes

The official ARI HRTF files are distributed in b, c, and d filename groups. This class treats the included files as one compatible ARI HRTF collection because they share the same source grid, IR shape, and sample rate, so they can be used inside the same ARI dataset instance.

The ARI dataset does not expose a public group selector. To use only a specific subset, exclude the subjects outside that subset with exclude_subject_ids before construction.

Examples

Build an ARI dataset that returns full HRIR arrays:

>>> from hrtfpykit.datasets import ARI, HRTFSpec
>>> dataset = ARI(
...     root="datasets/ari",
...     inputs=HRTFSpec(
...         domain="time",
...         signal="ir",
...         index_by=("subject",),
...         name="hrir",
...     ),
... )
>>> sample = dataset[0]
>>> sample["inputs"]["hrir"].shape
(1550, 2, 256)

__getitem__(index)¶

Return one sample by integer row index.

This method resolves the row context, dispatches each input and target spec through the value selector layer, and adds requested context encodings. It is the runtime path that turns dataset state into sample dictionaries for training, evaluation, or direct inspection.

Returned samples always contain inputs, target, and meta keys. inputs is None when no input specs and no context encodings were requested. target is None when no target specs were requested. meta contains dataset and row-provenance fields. When context encodings are requested by specs, keys such as position_one_hot, position_index, ear_one_hot, frequency_index, or sample_index are added to sample inputs for rows that carry the corresponding context.

Parameters:

index (int) – Dataset row index. Negative integers follow the underlying row-list behavior. Non-integer indices are rejected.

Returns:

Sample dictionary with inputs, target, and meta entries.

Return type:

dict[str, object]

Raises:

TypeError – If index is not an integer.
IndexError – If index is outside the constructed row table.

__len__()¶

Return the number of dataset rows.

Rows are created from selected subjects and any shared indexed axes such as position, ear, frequency, or samples. The result is the number of integer indices accepted by __getitem__() before normal Python list bounds checking is applied.

Returns:: Number of samples addressable by integer indexing.
Return type:: int

property available_subjects: list[str]¶

Return subjects available after resource intersection.

Available subjects are the non-excluded subjects that have every resource required by the selected input and target specs. This property describes resource availability, not necessarily the final train, validation, or test split subset.

Returns:: Canonical subject identifiers available for the selected specs.
Return type:: list of str

property azimuth_angles: ndarray | None¶

Return available dataset azimuth angles.

The angles are derived from the full dataset source grid. They report available spatial coverage independently from the subset selected by position-indexed specs.

Returns:: Unique azimuth angles from the dataset-level source positions.
Return type:: numpy.ndarray or None

property dataset_hrtf_variant: str | dict[str, object] | None¶

Return the selected HRTF resource variant.

This value records the HRTF variant used for local resource scanning and loading. Datasets with one selector axis return a string such as measured. Datasets with multiple selector axes return a dictionary containing fields such as type, sample_rate, and version. None means no HRTF variant was selected or no HRTF resource family is configured.

Returns:: Selected HRTF variant stored in the dataset state.
Return type:: str, dict, or None

property dataset_mesh_variant: str | dict[str, object] | None¶

Return the selected mesh resource variant.

This value records the mesh variant used for local resource scanning and loading. Datasets with one selector axis return a string. Datasets with multiple selector axes return a dictionary containing fields such as type and version. None means no mesh variant was selected or no mesh resource family is configured.

Returns:: Selected mesh variant stored in the dataset state.
Return type:: str, dict, or None

dataset_summary()¶

Return the dataset summary created during construction.

The summary captures the final dataset state after resource intersection and split planning: root path, selected split, subject counts, normalized input and target specs, selected resource variants, row count, and acoustic context when HRTF resources are available.

Returns:: Human-readable summary of subjects, split, specs, selected variants, row count, and acoustic metadata.
Return type:: str

property elevation_angles: ndarray | None¶

Return available dataset elevation angles.

The angles are derived from the full dataset source grid. They describe the available elevation coverage before any position subset selected by specs is applied.

Returns:: Unique elevation angles from the dataset-level source positions.
Return type:: numpy.ndarray or None

property excluded_subjects: list[str]¶

Return subjects excluded from this dataset instance.

This list combines configuration-level exclusions and user-provided exclusions after subject-reference normalization. Excluded subjects are removed before resource intersection and split planning, so they never contribute rows.

Returns:: Canonical subject identifiers excluded from this dataset instance.
Return type:: list of str

property frequency_bins: ndarray | None¶

Return dataset-level frequency bins.

The bins come from the selected HRTF resources when frequency-domain data are available or can be derived. They define the dataset-level frequency axis used by frequency-indexed specs and remain separate from selected_frequency_indices.

Returns:: Frequency bins from selected HRTF resources, or None when no frequency-domain acoustic context was built.
Return type:: numpy.ndarray or None

get_subject_hrtf(subject_id)¶

Load one subject HRTF through the dataset resource map.

This method is the subject-level access point shared by concrete datasets. It applies the same subject normalization, HRTF path lookup, cache, and dataset-level HRTF transform used by indexed sample extraction, so direct inspection and indexed sample extraction use the same loading path.

Parameters:

subject_id (str or int) – Dataset subject reference. Integer values are mapped to the configured subject order.

Returns:

Loaded HRTF object after applying any dataset-level HRTF transform.

Return type:

HRTF

Raises:

ValueError – If dataset state is incomplete, subject mapping fails, HRTF loading fails, or the dataset-level HRTF transform does not return an HRTF object.
KeyError – If the mapped subject does not have an available HRTF resource in the dataset scan.
FileNotFoundError – If the resolved HRTF file is missing.

Return input specs used by this dataset.

The tuple contains the normalized specs that feed sample inputs. It reflects spec workflow decisions such as default names, shared index_by axes, context encodings, and dataset-specific validation.

Returns:: Normalized input specs in extraction order.
Return type:: tuple of specs

property name: str¶

Return the dataset configuration name.

The value is copied from the active dataset configuration during construction and can be used to identify the dataset source without reading private state.

Returns:: Dataset name stored in the dataset state.
Return type:: str

property positions: ndarray | None¶

Return dataset-level source positions.

These positions describe the full source grid resolved from the selected HRTF resources before spec-level row selection. Position-aware specs may use only a subset of this grid; that subset is exposed separately through selected_position_indices, selected_azimuth_angles, and selected_elevation_angles.

Returns:: Source-position array from selected HRTF resources, or None when no acoustic context was built.
Return type:: numpy.ndarray or None

resources_summary()¶

Return the resource scan summary created during construction.

The summary describes resources relevant to the selected specs and variants, not every resource a dataset family can support. It reports the local resource paths considered during construction, resource counts, missing files, partial media resources, and subject removals caused by resource intersection.

Returns:: Human-readable summary of scanned resources used by the selected specs.
Return type:: str

property root: Path¶

Return the local dataset root.

The returned path is the expanded root stored during construction and used by every resource scanner. It may point to a directory that contains only the resource families required by the selected specs.

Returns:: Expanded local dataset root.
Return type:: Path

property sample_indices: ndarray | None¶

Return dataset-level time sample indices.

The indices describe the full HRIR sample axis from the selected HRTF resources. They support sample-indexed specs while keeping the complete time-domain acoustic context inspectable.

Returns:: Time-sample indices from selected HRTF resources, or None when no time-domain acoustic context was built.
Return type:: numpy.ndarray or None

property sample_rate: float | None¶

Return dataset-level acoustic sample rate.

The value is derived from the selected HRTF resources after resource validation. It represents the dataset-level acoustic context and is not changed by per-spec extraction choices such as position, frequency, or sample selection. None means the constructed dataset did not require or discover HRTF resources.

Returns:: Sample rate read from selected HRTF resources.
Return type:: float or None

property selected_azimuth_angles: ndarray | None¶

Return azimuth angles selected by position-aware specs.

The values summarize the selected position subset used for row generation. They are None when no selected spec produced a position-indexed acoustic subset.

Returns:: Unique azimuth angles for selected positions.
Return type:: numpy.ndarray or None

property selected_elevation_angles: ndarray | None¶

Return elevation angles selected by position-aware specs.

The values summarize the selected position subset used for row generation. They help inspect plane selectors and position-indexed datasets without losing the full elevation coverage available through elevation_angles.

Returns:: Unique elevation angles for selected positions.
Return type:: numpy.ndarray or None

property selected_frequency_indices: tuple[int, ...]¶

Return selected frequency-bin indices.

These indices are used when frequency appears in the shared dataset index_by axes. They identify the frequency bins that expand rows and determine how many frequency-indexed samples each selected subject contributes.

Returns:: Frequency-bin indices into frequency_bins.
Return type:: tuple of int

property selected_position_indices: tuple[int, ...]¶

Return source position indices selected by specs.

This property exposes the position subset used to build indexed rows after explicit position or plane selection. It is separate from positions so selected row context does not hide the full source grid.

Returns:: Source-position indices into positions.
Return type:: tuple of int

property selected_sample_indices: tuple[int, ...]¶

Return selected time-sample indices.

These indices are used when samples appears in the shared dataset index_by axes. They identify the HRIR samples that expand rows and determine how many sample-indexed samples each selected subject contributes.

Returns:: Time-sample indices into sample_indices.
Return type:: tuple of int

property selected_subjects: list[str]¶

Return subjects selected for the requested split.

Selected subjects are the available subjects used to build rows for this dataset instance. For split=``all``, this usually matches available_subjects; for train, validation, or test splits it is a deterministic subset derived from split_ratio and split_seed.

Returns:: Canonical subject identifiers used to build dataset rows.
Return type:: list of str

property split: str¶

Return the requested dataset split name.

The split controls which available subjects become rows in this dataset instance. It is stored separately from resource availability so callers can distinguish subjects that have all required resources from the subset chosen for train, validation, or test use.

Returns:: Split name used by this dataset instance.
Return type:: str

property split_ratio: tuple[float, float, float]¶

Return train, validation, and test split ratios.

These ratios are used by the split planner when split is train, validation, or test. They remain visible on the dataset object so split behavior can be inspected and reproduced.

Returns:: Three split ratios in train, validation, and test order.
Return type:: tuple of float

property split_seed: int¶

Return the split random seed.

The seed controls deterministic subject shuffling before train, validation, and test partitioning. It is part of the dataset state so selected subjects can be reproduced from the same resource set.

Returns:: Seed used for deterministic split planning.
Return type:: int

Return target specs used by this dataset.

The tuple contains the normalized specs that feed sample targets. A dataset with no target specs returns None under the target key during indexed access.

Returns:: Normalized target specs in extraction order.
Return type:: tuple of specs