ITDSpec

class hrtfpykit.datasets.ITDSpec(positions='all', plane=None, index_by=('subject',), position_one_hot=False, position_index=False, method='threshold', output='time', thresh_level=-10.0, upper_cut_freq=3000.0, filter_order=10, absolute=False, 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. By default, signed ITD values are returned. Set absolute=True to return unsigned ITD values.

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. Supported canonical combinations are ("subject",) and ("subject", "position"). "source", "sources", and "positions" are accepted as aliases for "position" and normalize to "position".

  • 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=``time``) – Output unit requested from the ITD metric. time returns microseconds.

  • 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.

  • absolute (bool, default=False) – Whether to request unsigned ITD values from the ITD metric.

  • 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(...)