compare_absolute_itd

hrtfpykit.plots.compare_absolute_itd(hrtfs, plane_angle=0.0, legends=None, line_colors=None, line_styles=None, legend_location=None, legend_bbox_to_anchor=None, show=True, show_titles=True, show_labels=True, show_legends=True)

Compare absolute ITD curves from several HRTFs.

compare_absolute_itd calls itd() for each HRTF as itd(hrtf, method="threshold", output="time", thresh_level=-10.0, upper_cut_freq=3000.0, filter_order=10, absolute=True). It selects the nearest measured horizontal plane for each HRTF, sorts each polar curve by azimuth, and overlays the curves in one figure.

Each HRTF resolves the requested horizontal plane independently. If compared HRTFs resolve to different real elevations, the function emits an HRTFPyKitWarning.

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.

  • plane_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 the default color 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, display the figure before returning.

  • show_titles (bool, default=True) – If False, suppress generated figure titles.

  • show_labels (bool, default=True) – If False, suppress generated axis labels and colorbar labels.

  • show_legends (bool, default=True) – If False, suppress generated legends.

Returns:

Figure containing the overlaid absolute ITD polar curves.

Return type:

matplotlib.figure.Figure

Raises:

ValueError – If the HRTF list length, plane_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 angular axis uses spherical azimuth in the SOFA convention. The radial axis uses ITD time units and integer microsecond tick labels.

Examples

Compare absolute ITD on the horizontal plane for two HRTFs:

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