plot_etc

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

Plot energy time curves for selected source positions.

plot_etc reads hrtf.IR.values, resolves each requested source with hrtf.Sources.get_position_index(...), and converts abs(IR) to decibels. The result is an energy time view of the selected HRIR samples.

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 ETC traces are drawn together in each subplot.

  • x_axis ({time, samples}, default=``time``) – Horizontal axis used for the ETC plot.

  • reference (float | {max}, default=``max``) – Reference used for decibel conversion. max normalizes the selected ETC traces to their maximum absolute IR value.

  • 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 energy time curve 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, the reference is invalid, or the requested ear channel is unavailable.

Notes

The figure uses the same source selection and panel arrangement as plot_amplitude(). The y values differ because the selected HRIR samples are converted to dB before plotting.

Examples

Plot the front direction ETC for both ears using sample indices:

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