plot_elevation_spectrum

hrtfpykit.plots.plot_elevation_spectrum(hrtf, azimuth=0.0, x_axis='linear', unit='db', ear='both', reference='max', colormap='jet', freq_min=None, freq_max=None, show=True, show_titles=True, show_labels=True, show_legends=True)

Plot HRTF magnitude across elevation at one azimuth.

plot_elevation_spectrum resolves the requested azimuth from a numeric angle or a named direction, selects the nearest measured azimuth slice in hrtf.Sources, and plots hrtf.TF.magnitude against frequency and elevation. When unit="db", magnitude values are converted to decibels.

The selected real azimuth is used in the figure title when titles are enabled. With ear="both", the function creates separate left and right panels with shared color limits.

Parameters:

  • azimuth (float | str, default=0.0) – Azimuth used to select the elevation slice. Named aliases such as front, back, left, and right are accepted. The nearest available azimuth in the source grid is used.

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

  • unit ({db, linear}, default=``db``) – Magnitude representation used for the heatmap values.

  • ear ({left, right, both}, default=``both``) – Ear channel to display. When both is selected, a separate subplot is created for each ear.

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

  • colormap (str, default=``jet``) – Colormap name used for the heatmap.

  • 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 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.

  • hrtf (HRTF)

Returns:

Figure containing the selected elevation spectrum heatmap.

Return type:

matplotlib.figure.Figure

Raises:

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

  • ValueError – If TF data is missing, azimuth is not finite or is an unknown named position, the selected slice has no positions, frequency bins are invalid, the selected frequency range contains no bins, or the requested ear channel is not available.

Notes

When the requested azimuth is not present exactly in the source grid, the nearest available azimuth is selected by circular angular distance. When unit="db" and reference="max", normalization is computed from the selected slice and ear channels.

Examples

Plot a front facing elevation spectrum to inspect how magnitude changes from below to above the listener:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import plot_elevation_spectrum
>>> hrtf = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> plot_elevation_spectrum(
...     hrtf,
...     azimuth="front",
...     x_axis="log",
...     ear="left",
...     freq_max=16000.0,
... )