ild_difference

hrtfpykit.hrtf.ild_difference(hrtf_reference, hrtfs, mode='broad-band', epsilon=1e-12, absolute=False, reduction_axis=None, reduction_method='mean')

Compute ILD differences from a reference HRTF.

ild_difference compares one reference HRTF against one or more HRTFs. It first computes signed ILD values with ild(), 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 ILD arrays. Broad-band mode then returns shape (len(ilds), positions) for standard data, and frequency-dependent mode returns shape (len(ilds), sources, frequency_bins).

The default result is signed. Positive values mean the compared HRTF has a greater ILD 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 ILD MAE over the selected axes. Use reduction_method="rms" to compute RMS ILD error. With absolute=False and reduction_method="mean", signs are kept and the result is mean signed ILD error.

Parameters:

  • hrtf_reference (HRTF) – Reference HRTF. It must provide source positions and the domains needed by the selected ILD mode.

  • 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. Frequency-dependent mode also requires matching TF frequency bins.

  • mode ({"broad-band", "frequency-dependent"}, default=``”broad-band”``) – ILD mode passed to ild().

  • epsilon (float, default=1e-12) – Positive floor passed to ild().

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

  • reduction_axis ({"ilds", "positions", "global"} or None, default=None) – Axis reduced after differences are computed. None returns every compared ILD difference array. "ilds" reduces the compared HRTF ILD axis and preserves source positions. "position" or "positions" reduces source positions and preserves the compared HRTF ILD axis when several HRTF ILD 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:

ILD differences after the requested reduction. Without reduction, a single compared HRTF returns (positions,) in broad-band mode and (positions, frequency_bins) in frequency-dependent mode. Several compared HRTF ILD arrays keep a leading ILD comparison axis.

Return type:

numpy.ndarray

Raises:

ValueError – If any input is not an HRTF object, if hrtfs is empty, if the source grids differ, if frequency-dependent mode is requested with missing or different frequency bins, if ILD 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 ild_difference, load_hrtf
>>> reference = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> processed = reference.transform.apply_gain(-1.0, scale="db")
>>> values = ild_difference(reference, processed, absolute=True, reduction_axis="ilds")
>>> values.shape
(793,)

Average absolute ILD differences from several HRTFs into one position curve:

>>> values = ild_difference(
...     reference,
...     [processed, processed],
...     absolute=True,
...     reduction_axis="ilds",
... )
>>> values.shape
(793,)

Return one global RMS score:

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