compare_lsd

hrtfpykit.plots.compare_lsd(hrtf_a, hrtf_b, ear='left', epsilon=1e-12, azimuth_range_mode='-180-180', colormap='jet', show=True, titles=True)

Plot full-grid LSD across source positions as a spatial scatter map.

The function computes one LSD value per source position by averaging across frequencies using lsd() with frequencies=None and reduction is frequencies. The result is shown as an azimuth-elevation scatter map with color representing log-spectral distance in decibels.

Frequency selection is delegated to the metric. With frequencies=None, the metric uses its default LSD band from 20 Hz to 20 kHz and validates that both HRTFs can be compared over the requested source grid and ear channel.

Parameters:

  • hrtf_a (HRTF) – First HRTF used in the comparison. Must contain TF data and a source grid compatible with hrtf_b.

  • hrtf_b (HRTF) – Second HRTF used in the comparison. Must contain TF data and a source grid compatible with hrtf_a.

  • ear ({left, right}, default=``left``) – Ear channel used for LSD computation.

  • epsilon (float, default=1e-12) – Positive floor passed to lsd() before dB conversion.

  • azimuth_range_mode ({0-360, -180-180}, default=``-180-180``) – Azimuth convention applied to the x-axis values.

  • colormap (str, default=``jet``) – Matplotlib colormap used to encode LSD values.

  • show (bool, default=True) – If True, calls matplotlib.pyplot.show().

  • titles (bool, default=True) – If True, applies the figure title.

Return type:

None

Raises:

ValueError – If delegated LSD calculation fails, source positions are invalid, or the returned LSD values cannot be aligned with the number of source positions.

Notes

This is a spatial summary plot: each source position receives one frequency-averaged LSD value. Use compare_lsd_plane() when you need to inspect how LSD varies with both direction and frequency on a canonical plane.

Examples

Plot a full-grid log-spectral-distance summary for the right ear:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import compare_lsd
>>> hrtf_a = load_hrtf("hrtfs/P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_b = load_hrtf("hrtfs/P0002_FreeFieldComp_44kHz.sofa")
>>> compare_lsd(
...     hrtf_a,
...     hrtf_b,
...     ear="right",
...     azimuth_range_mode="-180-180",
...     colormap="viridis",
... )