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

Compare HRTF magnitude responses from several HRTFs.

compare_magnitude reads TF.magnitude and TF.frequency_bins 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 magnitude traces. When unit="db", values are converted to decibels.

Frequency limits are resolved across all inputs. If the same query resolves to different real source coordinates across HRTFs, the function emits an HRTFPyKitWarning so the comparison is explicit about source mismatch.

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 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 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 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, 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 HRTF magnitude comparisons.

Return type:

matplotlib.figure.Figure

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

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 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("P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("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,
... )