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 use the regular template hrtf {version}_{subject_id}.sofa. Examples include hrtf b_nh2.sofa, hrtf c_nh831.sofa, and hrtf d_nh1059.sofa.

The official ARI NH HRTF files are distributed in b, c, and d filename groups. hrtfpykit treats the included files as one compatible ARI NH collection because they share the same source grid, IR shape, and sample rate. Use dataset_hrtf_variant="NH" for the full configured NH collection, or pass dataset_hrtf_variant={"type": "NH", "version": "b"}, "c", or "d" to scan one filename group.

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 uses the HRTF type NH. download_hrtf_variant="all" or download_hrtf_variant="NH" downloads the full configured NH collection. Passing download_hrtf_variant={"type": "NH", "version": "b"}, "c", or "d" downloads one ARI filename group.

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_variant='NH', dataset_hrtf_transform=None, download=False, download_resources='hrtf', download_hrtf_variant='NH', download_server='sofacoustics', verify_checksum=True, exclude_subject_ids=None, download_exclude_subject_ids=None, inputs=None, target=None, split='all', split_ratio=(0.8, 0.1, 0.1), split_seed=0, verbose=False)¶

ARI resolves the local ARI resources declared by ARIConfig. It exposes the official NH HRTF SOFA collection, ARI anthropometry CSV data, and subject metadata CSV data through the shared integer-indexed dataset interface. The NH HRTFs are distributed in b, c, and d filename groups; dataset_hrtf_variant="NH" scans the compatible configured collection, while a versioned NH variant selects one group.

Samples are driven by input and target specs. Acoustic specs load one subject HRTF with load_hrtf(). If dataset_hrtf_transform is provided, it is applied to that loaded HRTF first. Acoustic specs then operate on the dataset-level HRTF version, optionally apply their own HRTF transform, and finally extract time-domain values, frequency-domain values, ITD, ILD, or spherical-harmonic coefficients. Resource specs can add anthropometry and metadata values to the same sample. Subjects missing any required resource family are removed before row construction.

Download selection is independent from dataset construction selection. download_resources and download_hrtf_variant control which official files are downloaded. dataset_hrtf_variant controls which local HRTF files are scanned and loaded after the download step. The dataset does not infer download resources from inputs or target and does not copy dataset_hrtf_variant into download_hrtf_variant. ARI can download from sofacoustics or sonicom-ecosystem. sofacoustics provides configured HRTF, anthropometry, and metadata files. sonicom-ecosystem provides ARI HRTF files listed by ecosystem database catalogs.

Users can also download or prepare files manually and copy them under root. ARI HRTFs are accepted as official root-level filenames such as hrtf b_nh2.sofa and as local alternatives such as nh2/hrtf b_nh2.sofa, nh2/hrtf/hrtf b_nh2.sofa, nh2/hrtf/nh/hrtf b_nh2.sofa, or nh2/hrtf/nh/b/hrtf b_nh2.sofa. Anthropometry is accepted as anthro.csv, anthropometry/anthro.csv, anthropometry/*.csv, anthro/anthro.csv, or anthro/*.csv. Metadata is accepted as metadata.csv, metadata/metadata.csv, or metadata/*.csv.

Parameters:

root (str or Path) – Local ARI dataset root.
dataset_hrtf_variant ({NH} or dict, default=``NH``) – ARI HRTF variant used for dataset construction. NH selects the full configured NH collection across the b, c, and d filename groups. A dict may use {"type": "NH", "version": "b"}, {"type": "NH", "version": "c"}, or {"type": "NH", "version": "d"} to scan only one filename group.
dataset_hrtf_transform (callable or None, default=None) – Optional transform applied to every loaded HRTF before any acoustic spec is evaluated. Spec-level HRTF transforms run after this dataset-level 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 ({hrtf, anthropometry, metadata, all} or sequence of str, default=``hrtf``) – Official resources requested for download. sofacoustics supports hrtf, anthropometry, and metadata. sonicom-ecosystem supports only hrtf for ARI. Passing all requests every resource provided by the selected download server.
download_hrtf_variant ({all, NH}, dict, or None, default=``NH``) – ARI HRTF variant requested for download. all downloads every configured ARI HRTF family. NH downloads the full NH collection. A dict may use {"type": "NH", "version": "b"}, {"type": "NH", "version": "c"}, or {"type": "NH", "version": "d"} to download one ARI filename group. This value is independent from dataset_hrtf_variant.
download_server ({sofacoustics, sonicom-ecosystem}, default=``sofacoustics``) – Official server used when download=True. sofacoustics downloads configured ARI files directly from SOFAcoustics, with anthropometry and metadata fetched from their configured companion URLs. sonicom-ecosystem reads the SONICOM ecosystem database JSON entries and downloads ARI HRTF files listed there.
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.
download_exclude_subject_ids (str, int, sequence, or None, default=None) – ARI subjects excluded only from the download request. This does not change dataset construction; use exclude_subject_ids to exclude subjects from scanning, splitting, and samples.
inputs (spec, sequence of specs, or None, default=None) – Specs resolved under sample["inputs"]. None builds samples without an inputs group unless target specs are provided.
target (spec, sequence of specs, or None, default=None) – Specs resolved under sample["target"]. None builds samples without a target group unless input specs are provided.
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 configured ARI NH groups share the same source grid, IR shape, and sample rate, so they can be used as one compatible dataset collection or selected by filename group when a workflow needs a narrower subset.

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