compare_absolute_ild

hrtfpykit.plots.compare_absolute_ild(hrtfs, elevation_angle=0.0, legends=None, line_colors=None, line_styles=None, legend_location=None, legend_bbox_to_anchor=None, show=True, titles=True)

Compare absolute ILD polar curves across multiple HRTF instances.

This function computes broad-band interaural level difference for each HRTF, converts it to an absolute magnitude in decibels, extracts the nearest horizontal-plane curve to elevation_angle, and overlays one polar trace per HRTF. It is intended for comparing level-cue magnitude across subjects, measured datasets, or processing pipelines without preserving ILD sign.

Each HRTF resolves the requested horizontal plane independently. The figure title uses the real resolved elevation from the first HRTF, and the function warns if other inputs resolve to a different elevation.

Parameters:

  • hrtfs (list[HRTF]) – HRTF objects to compare. The list must contain at least 2 and at most 5 entries. Every object must contain IR data and an IR sample rate.

  • elevation_angle (float, default=0.0) – Requested horizontal-plane elevation in degrees. The nearest available elevation is selected separately for each HRTF.

  • legends (list[str] | tuple[str, ...] | None, default=None) – Subject legend labels. Defaults to subject_1 through subject_n.

  • line_colors (list[str] | tuple[str, ...] | None, default=None) – One line color per subject. Uses Matplotlib default cycle when omitted.

  • line_styles (list[str] | tuple[str, ...] | None, default=None) – One line style per subject. Defaults to solid lines.

  • legend_location (str | None, default=None) – Legend location. Defaults to upper right.

  • legend_bbox_to_anchor (tuple[float, float] | None, default=None) – Legend anchor tuple (x, y). Defaults to (1.08, 1.08).

  • show (bool, default=True) – If True, calls matplotlib.pyplot.show().

  • titles (bool, default=True) – If True, renders a figure title using the resolved elevation from the first HRTF.

Return type:

None

Raises:

ValueError – If the HRTF list length, elevation_angle, legend/style lengths, IR availability, or sample-rate availability are invalid.

Warns:

HRTFPyKitWarning – If HRTFs resolve the requested horizontal plane to different real elevations.

Notes

The polar theta axis uses a north-up orientation with 30-degree ticks. The radial axis uses Labels.ild_db and integer tick labels because ILD is displayed in decibels.

Examples

Compare absolute ILD on the horizontal plane for two HRTFs:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import compare_absolute_ild
>>> hrtf_a = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("hrtfs/P0002_FreeFieldComp_44kHz.sofa")
>>> compare_absolute_ild(
...     [hrtf_a, hrtf_b],
...     elevation_angle=0.0,
...     legends=["P0001", "P0002"],
...     line_styles=["-", "--"],
... )