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, show_titles=True, show_labels=True, show_legends=True)

Plot spherical harmonic reconstruction error for one source and ear.

sht_reconstruction_error reads the original magnitude from hrtf.TF.values and compares it with reconstructed_magnitude, typically produced by sht_inverse(). It resolves one source query with hrtf.Sources.get_position_index(...), selects the requested ear, applies the requested frequency range, and plots original - reconstructed across frequency.

When magnitude="db", original and reconstructed magnitudes are converted with magnitude_to_db() before subtraction. The generated title reports the RMS reconstruction error computed with the same RMS error definition exposed by sht_error().

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, display the figure before returning.

  • show_titles (bool, default=True) – If False, suppress generated subplot titles.

  • show_labels (bool, default=True) – If False, suppress generated axis labels.

  • show_legends (bool, default=True) – If False, suppress generated legends.

Returns:

Figure containing the reconstruction error trace.

Return type:

matplotlib.figure.Figure

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("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,
... )