plot_magnitude

hrtfpykit.plots.plot_magnitude(hrtf, positions=('front', 'back', 'left', 'right'), x_axis='linear', unit='db', ear='both', reference=1.0, freq_min=None, freq_max=None, show=True, show_titles=True, show_labels=True, show_legends=True)

Plot magnitude responses for selected source positions.

plot_magnitude reads hrtf.TF.magnitude and hrtf.TF.frequency_bins, resolves each requested source with hrtf.Sources.get_position_index(...), and draws one spectrum panel per source direction. When unit="db", the plotted values are produced to decibels; reference="max" uses the maximum selected magnitude as the dB reference.

Frequency limits are passed in hertz and displayed in kilohertz. Position queries use named directions such as "front" or spherical [azimuth, elevation] coordinates in degrees.

Parameters:

  • positions (str | list | tuple | np.ndarray, default=(front, back, left, right)) – One position or a collection of positions. Named aliases such as front, back, left, and right are accepted. Numeric queries must use spherical coordinates in degrees as [azimuth, elevation], for example [0.0, 0.0] for the front direction. Up to four positions can be shown in one figure.

  • x_axis ({linear, log}, default=``linear``) – Frequency scale used on the x axis.

  • unit ({db, linear}, default=``db``) – Magnitude representation used on the y axis.

  • ear ({left, right, both}, default=``both``) – Ear channel to display. When both is selected, left and right responses are drawn together in each subplot.

  • reference (float | {max}, default=1.0) – Reference used when unit=``db``. max normalizes the plotted magnitude to the maximum selected value.

  • freq_min (float | None, default=None) – Minimum frequency in Hz included in the plot.

  • freq_max (float | None, default=None) – Maximum frequency in Hz included in the plot.

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

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

  • hrtf (HRTF)

Returns:

Figure containing the selected HRTF magnitude response panels.

Return type:

matplotlib.figure.Figure

Raises:

  • AttributeError – If unit, x_axis, or ear is not one of the supported values.

  • ValueError – If TF values or frequency bins are missing, no positions are requested, more than four positions are requested, the selected frequency range contains no bins, or the requested ear channel is not available.

Notes

The figure uses one panel for one requested source, two stacked panels for two requested sources, and a compact grid for three or four requested sources. With ear="both", both ear channels are drawn in each panel with the shared ear legend.

Examples

Plot one normalized magnitude response for the front direction on a logarithmic frequency axis:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import plot_magnitude
>>> hrtf = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> plot_magnitude(
...     hrtf,
...     positions="front",
...     x_axis="log",
...     ear="both",
...     reference="max",
...     freq_max=16000.0,
... )