itd_difference

hrtfpykit.hrtf.itd_difference(hrtf_reference, hrtfs, method='threshold', output='time', thresh_level=-10.0, upper_cut_freq=3000.0, filter_order=10, absolute=False, reduction_axis=None, reduction_method='mean')

Compute ITD differences from a reference HRTF.

itd_difference compares one reference HRTF against one or more HRTFs. It first estimates signed ITD values with itd(), then subtracts the reference values from each compared HRTF. If hrtfs is one HRTF, no leading comparison axis is added. If hrtfs contains several HRTFs, the first axis indexes the compared HRTF ITD arrays, so standard HRTF data returns shape (len(itds), positions).

The default result is signed. Positive values mean the compared HRTF has a greater ITD value than the reference at the same source position. Set absolute=True to return difference magnitudes.

With a selected reduction_axis, use absolute=True and reduction_method="mean" to compute ITD MAE over the selected axes. Use reduction_method="rms" to compute RMS ITD error. With absolute=False and reduction_method="mean", signs are kept and the result is mean signed ITD error.

Parameters:

  • hrtf_reference (HRTF) – Reference HRTF. It must provide IR data, an IR sample rate, and source positions.

  • hrtfs (HRTF or sequence of HRTF) – HRTF object or objects compared against hrtf_reference. Every HRTF must use the same source grid as the reference.

  • method ({"threshold", "maxiacce"}, default=``”threshold”``) – ITD estimator passed to itd().

  • output ({"time", "samples"}, default=``”time”``) – Unit used before subtraction. "time" returns microseconds. "samples" requires matching sample rates across the reference and all compared HRTFs.

  • thresh_level (float, default=-10.0) – Threshold offset passed to itd() when method="threshold".

  • upper_cut_freq (float, default=3000.0) – Low-pass cutoff frequency passed to itd().

  • filter_order (int, default=10) – Filter order passed to itd().

  • absolute (bool, default=False) – If False, return signed differences compared - reference. If True, return abs(compared - reference).

  • reduction_axis ({"itds", "positions", "global"} or None, default=None) – Axis reduced after differences are computed. None returns every compared ITD difference array. "itds" reduces the compared HRTF ITD axis and preserves source positions. "position" or "positions" reduces source positions and preserves the compared HRTF ITD axis when several HRTF ITD arrays are provided. "global" reduces all axes. "source" and "sources" are accepted as aliases.

  • reduction_method ({"mean", "rms"}, default=``”mean”``) – Reduction method. "mean" computes the arithmetic mean over the selected axes. Use it with absolute=True to compute MAE. Use "rms" to compute RMS error over the selected axes.

Returns:

ITD differences after the requested reduction. Without reduction, a single compared HRTF returns (positions,) for standard data. Several compared HRTF ITD arrays return (len(itds), positions).

Return type:

numpy.ndarray

Raises:

ValueError – If any input is not an HRTF object, if hrtfs is empty, if IR data or sample rates are missing, if source grids differ, if sample output is requested for different sample rates, if calculated ITD arrays have different shapes, or if an option value is unsupported.

Examples

Compare one processed HRTF against a reference and keep one value per position:

>>> from hrtfpykit.hrtf import itd_difference, load_hrtf
>>> reference = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> processed = reference.transform.add_itd(20, unit="samples")
>>> values = itd_difference(
...     reference,
...     processed,
...     output="samples",
...     absolute=True,
...     reduction_axis="itds",
... )
>>> values.shape
(793,)

Return one global RMS score in microseconds:

>>> score = itd_difference(
...     reference,
...     processed,
...     output="time",
...     absolute=True,
...     reduction_axis="global",
...     reduction_method="rms",
... )
>>> score.shape
()