compare_magnitude

hrtfpykit.plots.compare_magnitude(hrtfs, positions=('front',), ear='left', x_axis='linear', unit='db', reference=1.0, legends=None, line_colors=None, line_styles=None, legend_location=None, legend_bbox_to_anchor=None, freq_min=None, freq_max=None, show=True, titles=True)

Compare HRTF magnitude responses across multiple HRTF objects.

The function overlays one magnitude curve per HRTF for each requested source position. It is designed for comparing subjects, measurements, model outputs, or processing pipelines that share a broadly comparable source grid and frequency range. Each position query is resolved against every HRTF independently, then the real resolved positions are checked so the caller is warned when a named or numeric query resolves to different source coordinates across subjects.

Frequency limits are resolved across all provided HRTFs. If freq_min or freq_max is omitted, the plotted range is restricted to the overlapping frequency span available in every input. Frequency values are shown in kHz on the x-axis, while freq_min and freq_max are specified in Hz to match the stored frequency bins.

Parameters:

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

  • 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 ({linear, log}, default=``linear``) – Frequency-axis scale used for all subplots.

  • unit ({db, linear}, default=``db``) – Magnitude representation. db converts magnitudes with magnitude-to-decibel conversion; linear plots raw magnitudes.

  • reference (float | str, default=1.0) – Reference used when unit is db. max normalizes all plotted curves to the maximum selected magnitude over the requested positions, frequency range, and ear selection.

  • 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 when x_axis is linear and upper left when x_axis is log.

  • legend_bbox_to_anchor (tuple[float, float] | None, default=None) – Optional legend anchor tuple (x, y).

  • freq_min (float | None, default=None) – Minimum frequency in Hz. If omitted, resolved from all HRTFs.

  • freq_max (float | None, default=None) – Maximum frequency in Hz. If omitted, resolved from all HRTFs.

  • 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, frequency range, TF availability, frequency bins, or ear channels are invalid.

Warns:

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

Notes

One single-ear position uses Layout_1, two positions use Layout_2Vertical, and three or four positions use Layout_3. When ear is both, the function uses Layout_2Horizontal and one position, placing left-ear and right-ear comparisons side by side.

Examples

Compare left-ear magnitude responses from two SOFA files at the front direction, using a logarithmic frequency axis and a shared dB reference:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import compare_magnitude
>>> hrtf_a = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("hrtfs/P0002_FreeFieldComp_44kHz.sofa")
>>> compare_magnitude(
...     [hrtf_a, hrtf_b],
...     positions="front",
...     ear="left",
...     x_axis="log",
...     unit="db",
...     reference="max",
...     legends=["P0001", "P0002"],
...     line_styles=["-", "--"],
...     freq_max=16000.0,
... )