compare_ild_curve

hrtfpykit.plots.compare_ild_curve(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 signed ILD curves across multiple HRTFs.

This function computes broad-band signed ILD in decibels for each HRTF, extracts the nearest horizontal-plane slice to elevation_angle, sorts the slice by signed azimuth, and overlays one azimuth-versus-ILD line per HRTF. It is intended for inspecting level-cue directionality across subjects, datasets, or processing pipelines.

Unlike compare_absolute_ild(), this function preserves ILD sign. The x-axis uses the signed -180 .. 180 azimuth convention.

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) – Optional legend anchor tuple (x, y).

  • 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, sample-rate availability, selected plane, or computed ILD shape is invalid.

Warns:

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

Notes

The plot uses one Cartesian axis and overlays all subjects in the same coordinate frame. Curves may have different azimuth sample locations if the HRTFs use different source grids.

Examples

Compare the signed ILD curve around the horizontal plane:

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