sht_reconstruction_error

hrtfpykit.plots.sht_reconstruction_error(hrtf, reconstructed_magnitude, position='front', ear='left', x_axis='linear', magnitude='linear', reference=1.0, freq_min=None, freq_max=None, show=True)

Plot SH reconstruction magnitude error for one direction and ear.

This diagnostic plot shows the point-wise magnitude error between the original HRTF magnitude and a spherical-harmonic reconstruction at one source position and ear. The plotted error is original_magnitude - reconstructed_magnitude for the selected trace in the requested magnitude domain, and the subplot title includes the root-mean-square error across frequency.

Use this function after sht_inverse() to inspect where a selected spherical-harmonic order loses spectral detail for a specific direction. Unlike sht_reconstruction_comparison(), this function plots the error directly instead of overlaying original and reconstructed spectra.

Notes

reconstructed_magnitude must contain linear magnitude values with the same source-position and frequency axes as the HRTF object’s current TF data. The frequency axis is taken from TF.frequency_bins and displayed in kHz.

The function creates a new Figure with a single axis and returns None.

Parameters:

  • hrtf (HRTF) – HRTF object providing the reference complex TF data, frequency bins, and source-grid metadata. TF.values must have shape (positions, ears, frequency_bins) and include at least two ear channels.

  • reconstructed_magnitude (np.ndarray) – Reconstructed linear magnitude values. Use shape (N, F) for a single-ear spherical-harmonic reconstruction or (N, 2, F) for a two-ear reconstruction produced with ear=``both``. The first axis must match the HRTF source-position axis and the final axis must match TF.frequency_bins.

  • position (np.ndarray | list | tuple | str, default=``front``) – Single spatial query resolved on the HRTF source grid. Named positions such as front, back, left, and right are accepted. Numeric queries use spherical coordinates in degrees as [azimuth, elevation].

  • ear ({left, right}, default=``left``) – Ear channel used for the original HRTF trace and, when reconstructed_magnitude has an ear axis, for the reconstructed trace. For a single-ear reconstruction with shape (N, F), choose the ear that was used when computing the SH coefficients.

  • x_axis ({linear, log}, default=``linear``) – Frequency-axis scale used for the plot.

  • magnitude ({linear, db}, default=``linear``) – Magnitude domain used for the error trace. linear plots the raw linear-magnitude reconstruction error. db converts absolute magnitudes to decibels before subtracting, so the plotted trace is a point-wise LSD-style dB error.

  • reference (float | str, default=1.0) – Reference used when magnitude=``db``. Passing max normalizes both original and reconstructed values by the maximum absolute magnitude in the selected trace before dB conversion.

  • freq_min (float | None, default=None) – Lower frequency bound in hertz. When omitted, the minimum available frequency bin is used.

  • freq_max (float | None, default=None) – Upper frequency bound in hertz. When omitted, the maximum available frequency bin is used.

  • show (bool, default=True) – If True, call matplotlib.pyplot.show() before returning.

Returns:

The function creates and configures a Matplotlib figure as a side effect.

Return type:

None

Raises:

ValueError – If TF values or frequency bins are unavailable, if ear, x_axis, or magnitude is unsupported, if position does not resolve to exactly one source position, if original or reconstructed arrays have incompatible shapes, if the selected position is out of bounds, if the frequency-bin axis does not match the selected magnitude trace, if frequency bounds are invalid, if no frequency bins fall inside the selected range, or if dB conversion cannot produce finite values.

Examples

Plot the reconstruction error for the right ear at the left direction:

>>> from hrtfpykit.hrtf import load_hrtf, sht, sht_inverse
>>> from hrtfpykit.plots import sht_reconstruction_error
>>> hrtf = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> sh_representation = sht(hrtf, sh_order=8, ear="both")
>>> sh_representation.C.shape
(81, 2, 129)
>>> reconstructed = sht_inverse(sh_representation)
>>> reconstructed.shape
(793, 2, 129)
>>> sht_reconstruction_error(
...     hrtf=hrtf,
...     reconstructed_magnitude=reconstructed,
...     position="left",
...     ear="right",
...     x_axis="log",
...     magnitude="db",
...     reference="max",
...     freq_min=200.0,
...     freq_max=16000.0,
... )