plot_amplitude

hrtfpykit.plots.plot_amplitude(hrtf, positions=('front', 'back', 'left', 'right'), ear='both', x_axis='time', show=True, show_titles=True, show_labels=True, show_legends=True)

Plot HRIR amplitude responses for selected source positions.

plot_amplitude reads the current time domain data from hrtf.IR.values, resolves each requested source with hrtf.Sources.get_position_index(...), and draws the selected impulse responses. With ear="both", left and right channels are overlaid in each source panel.

The x axis can show sample indices or time in milliseconds. Time mode uses hrtf.IR.sample_rate to convert sample positions to milliseconds.

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.

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

  • x_axis ({time, samples}, default=``time``) – Horizontal axis used for the waveform 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 HRIR amplitude response panels.

Return type:

matplotlib.figure.Figure

Raises:

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

  • ValueError – If IR data is missing, time axis plotting lacks a sample rate, no positions are requested, more than four positions are requested, the IR array has no samples, or the requested ear channel is unavailable.

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 front HRIR waveform:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import plot_amplitude
>>> hrtf = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> plot_amplitude(
...     hrtf,
...     positions="front",
...     ear="both",
...     x_axis="samples",
... )