ITDSpec

class hrtfpykit.datasets.ITDSpec(positions='all', plane=None, index_by=('subject',), position_one_hot=False, position_index=False, method='threshold', output='samples', thresh_level=-10.0, upper_cut_freq=3000.0, filter_order=10, transform=None, name=None)

Define interaural time difference values returned by a sample.

ITDSpec defines an ITD feature derived from each selected subject HRTF. It does not store ITD arrays itself. During indexing, the dataset loads the subject HRTF, applies the optional dataset level HRTF transform, applies this spec transform when provided, computes ITD from the resulting HRIR data, and returns the selected value.

The transform callable is used when ITD should be calculated from a modified HRTF version. It receives the loaded HRTF object before ITD calculation and must return the HRTF object that should be used for the metric. It does not receive the calculated ITD array.

If the spec is passed to inputs, its value appears under dataset[0]["inputs"][name]. If it is passed to target, its value appears under dataset[0]["target"][name]. When name is None, the default key is "itd". The returned value is a numpy.ndarray.

With index_by=("subject",), the output is a vector with one ITD value per selected source position. With index_by=("subject", "position"), each dataset row selects one source position and the output is a 0D array. position_index and position_one_hot add the same row context to sample inputs when requested.

Parameters:

  • positions ({all} or sequence of int, default=``all``) – Source position indices used before ITD calculation.

  • plane (str, tuple, dict, or None, default=None) – Optional plane selector used instead of explicit position indices.

  • index_by (str or tuple of str, default=(subject,)) – Dataset row axes. ITD supports subject only and position indexed rows.

  • position_one_hot (bool, default=False) – Whether position context encodings are exposed in sample inputs.

  • position_index (bool, default=False) – Whether position context encodings are exposed in sample inputs.

  • method (str, default=``threshold``) – ITD estimation method forwarded to the DSP metric.

  • output (str, default=``samples``) – Output unit or representation requested from the ITD metric.

  • thresh_level (float, default=-10.0) – Threshold level used by threshold based ITD methods.

  • upper_cut_freq (float, default=3000.0) – Upper cutoff frequency used by filtered ITD methods.

  • filter_order (int, default=10) – Filter order used by filtered ITD methods.

  • transform (callable or None, default=None) – Optional HRTF transform applied before ITD calculation. This transform receives the loaded HRTF object, not the calculated ITD value.

  • name (str or None, default=None) – Optional public key used in sample dictionaries.

Returns:

Specification object consumed by dataset construction.

Return type:

ITDSpec

Examples

>>> import numpy as np
>>> from hrtfpykit.datasets import HUTUBS, ITDSpec
>>> dataset = HUTUBS(
...     root="datasets/hutubs",
...     inputs=ITDSpec(
...         index_by=("subject", "position"),
...         position_index=True,
...         output="samples",
...         name="itd",
...     ),
... )
>>> sample = dataset[0]
>>> itd_value = sample["inputs"]["itd"]
>>> print(type(itd_value).__name__)
ndarray
>>> print(itd_value.shape)
()
>>> print(sample["inputs"]["position_index"])
0
>>> np.asarray(np.round(itd_value, 3))
array(...)