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, show_titles=True, show_labels=True, show_legends=True)

Compare HRIR amplitude responses from several HRTFs.

compare_amplitude reads IR.values from every HRTF in hrtfs. For each requested source query, it resolves the nearest measured source in every HRTF with hrtf.Sources.get_position_index(...) and overlays the selected impulse responses.

The x axis can show sample indices or time in milliseconds. Time mode uses each HRTF’s IR.sample_rate. If the same query resolves to different real source coordinates across HRTFs, 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 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 milliseconds 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 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) – Optional legend anchor tuple (x, y).

  • show (bool, default=True) – If True, display the figure before returning.

  • show_titles (bool, default=True) – If False, suppress generated subplot and 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 HRIR amplitude comparisons.

Return type:

matplotlib.figure.Figure

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

With one selected source and ear="both", the figure places the left and right ear comparisons in separate panels. Otherwise, each requested source gets its own panel and every HRTF is drawn in that panel.

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("P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("P0002_FreeFieldComp_44kHz.sofa")
>>> compare_amplitude(
...     [hrtf_a, hrtf_b],
...     positions="front",
...     ear="left",
...     x_axis="samples",
...     legends=["P0001", "P0002"],
...     line_styles=["-", "--"],
... )