compare_itd_curve

hrtfpykit.plots.compare_itd_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 ITD curves across multiple HRTFs.

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

Unlike compare_absolute_itd(), this function preserves ITD 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 ITD 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 ITD curve around the horizontal plane:

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