compare_amplitude

hrtfpykit.plots.compare_amplitude(hrtfs, positions=('front',), ear='left', x_axis='time', legends=None, line_colors=None, line_styles=None, legend_location=None, legend_bbox_to_anchor=None, show=True, titles=True)

Compare HRIR amplitude curves across multiple HRTF instances.

The function overlays one time-domain impulse-response waveform per HRTF for each requested source position. It is intended for comparing HRIR shape, delay, windowing, or preprocessing effects across subjects or pipeline outputs. Each position query is resolved independently for every HRTF, and a warning is emitted when the real resolved source coordinate differs across inputs.

The horizontal axis can show seconds or sample indices. Time mode requires every input HRTF to provide IR.sample_rate; sample mode only requires the impulse-response array.

Parameters:

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

  • positions (str | list | tuple | np.ndarray, default=(front,)) – Position query or collection of position queries. Up to 4 positions are accepted. Query resolution uses each HRTF’s nearest available source in spherical coordinates.

  • ear ({left, right, both}, default=``left``) – Ear channel selection. both requires exactly one position and creates separate left-ear and right-ear subplots.

  • x_axis ({time, samples}, default=``time``) – Horizontal axis mode for waveforms. time converts samples to seconds using each HRTF’s sample rate.

  • 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) – Controls subplot titles in single-ear mode.

Return type:

None

Raises:

ValueError – If the HRTF list length, option values, legend/style lengths, requested positions, IR availability, sample-rate requirements, IR shape, or ear channels are invalid.

Warns:

HRTFPyKitWarning – If the same position query resolves to different real source coordinates in different HRTFs.

Notes

The layout selection mirrors compare_magnitude(): one single-ear position uses Layout_1, two positions use Layout_2Vertical, three or four positions use Layout_3, and ear=``both`` uses Layout_2Horizontal for one position.

Examples

Compare left-ear front-direction impulse responses for two HRTFs, using sample indices on the x-axis:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import compare_amplitude
>>> hrtf_a = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("hrtfs/P0002_FreeFieldComp_44kHz.sofa")
>>> compare_amplitude(
...     [hrtf_a, hrtf_b],
...     positions="front",
...     ear="left",
...     x_axis="samples",
...     legends=["P0001", "P0002"],
...     line_styles=["-", "--"],
... )