sht_error

hrtfpykit.hrtf.sht_error(original_magnitude, reconstructed_magnitude, magnitude='linear', reference=1.0)

Compute reconstruction error metrics between two magnitude tensors.

The function compares two magnitude arrays element by element. It is intended for evaluating the output of sht_inverse() against the original magnitudes used for the decomposition, but it accepts any two finite arrays with matching shape. By default, errors are computed on linear magnitudes. With magnitude="db", absolute magnitudes are converted to decibels with a small positive floor before calculating the same error metrics, so rms_error is a global LSD-style RMS dB error for the provided arrays.

Parameters:

  • original_magnitude (np.ndarray) – Reference linear-magnitude values. Must have the same shape as reconstructed_magnitude.

  • reconstructed_magnitude (np.ndarray) – Reconstructed linear-magnitude values to evaluate against the reference.

  • magnitude ({linear, db}, default=``linear``) – Domain used for the error calculation. linear compares the input arrays directly. db compares the decibel values of the absolute input magnitudes.

  • reference (float | {max}, default=1.0) – Reference magnitude used only when magnitude=``db``. Passing max uses the maximum absolute magnitude across both input arrays so the original and reconstructed values share the same dB reference.

Returns:

Error metrics returned as:

  • absolute_error: L2 norm of original - reconstructed in the selected magnitude domain. With magnitude=``db``, this is the L2 norm of the dB-domain reconstruction error.

  • relative_error: absolute error divided by the reference L2 norm. .With magnitude=``db``, the reference norm is computed from the original dB values.

  • rms_error: root-mean-square point-wise error. With magnitude=``db``, this is the global LSD-style RMS error in dB.

  • max_absolute_error: maximum absolute point-wise error. With magnitude=``db``, this is the largest point-wise absolute dB error.

Return type:

tuple[float, float, float, float]

Raises:

ValueError – If the input arrays have different shapes, are empty, or contain non-finite values, if magnitude is unsupported, if reference is invalid for dB conversion, or if dB conversion produces non-finite values.

Examples

Measure reconstruction error after decomposing and reconstructing the left ear HRTF magnitudes:

>>> import numpy as np
>>> from hrtfpykit.hrtf import load_hrtf, sht, sht_error, sht_inverse
>>> hrtf = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> sh = sht(hrtf, sh_order=3, ear="left")
>>> reconstructed = sht_inverse(sh)
>>> abs_err, rel_err, rms_err, max_err = sht_error(
...     original_magnitude=np.abs(hrtf.TF.values[:, 0, :]),
...     reconstructed_magnitude=reconstructed,
... )
>>> tuple(round(value, 6) for value in (abs_err, rel_err, rms_err, max_err))
(22.470729, 0.211882, 0.070256, 0.686853)
>>> _, _, lsd_error, _ = sht_error(
...     original_magnitude=np.abs(hrtf.TF.values[:, 0, :]),
...     reconstructed_magnitude=reconstructed,
...     magnitude="db",
... )
>>> round(lsd_error, 6)
6.458158