compare_hrtf_difference

hrtfpykit.plots.compare_hrtf_difference(hrtf_reference, hrtfs, metric='lsd', ear='left', frequencies=None, frequency_bands=None, epsilon=1e-12, reduction_method='mean', azimuth_range_mode='0-360', plot_type='heatmap', colormap='jet', show=True, show_titles=True, show_labels=True, show_legends=True)

Plot HRTF difference values over the reference source grid.

compare_hrtf_difference calls hrtf_difference() as hrtf_difference(hrtf_reference=hrtf_reference, hrtfs=hrtfs, metric=metric, ear=ear, plane="all", frequencies=frequencies, frequency_bands=frequency_bands, reduction_axis=..., reduction_method=reduction_method, epsilon=epsilon). metric="lsd" computes log spectral distortion from TF data, metric="rmse" and metric="mae" compute linear HRIR amplitude error from IR data, and metric="nrmse" computes reference normalized HRIR error in dB.

Source coordinates are read from hrtf_reference.Sources in spherical degrees. plot_type="scatter" colors the measured source positions directly, while plot_type="heatmap" interpolates the same source values onto an azimuth and elevation image grid.

Parameters:

  • hrtf_reference (HRTF) – Reference HRTF. It must provide the source grid used for plot coordinates and the domain data required by metric.

  • hrtfs (HRTF or sequence of HRTF) – Compared HRTF object or objects. Every compared HRTF must use the same source positions and metric data shape as hrtf_reference. Several compared HRTFs are reduced into one source map with reduction_method.

  • metric ({lsd, rmse, nrmse, mae}, default=``lsd``) – HRTF difference metric plotted on the source map.

  • ear ({left, right, both}, default=``left``) – Ear channel selection passed to hrtf_difference(). both computes both ears and reduces the ear axis before plotting.

  • frequencies (float, sequence of float, numpy.ndarray, or None, default=None) – Frequency selector in hertz passed to hrtf_difference() for metric="lsd". Each requested value is mapped to the nearest available TF bin.

  • frequency_bands (pair, sequence of pairs, numpy.ndarray, or None, default=None) – Inclusive frequency band or bands in hertz passed to hrtf_difference() for metric="lsd".

  • epsilon (float, default=1e-12) – Positive floor passed to hrtf_difference().

  • reduction_method ({mean, rms}, default=``mean``) – Method used to reduce compared HRTFs and, for ear="both", ears.

  • azimuth_range_mode ({0-360, -180-180}, default=``0-360``) – Azimuth convention applied to the x axis. 0-360 follows the SOFA anticlockwise convention: front is 0 degrees, listener left is 90 degrees, back is 180 degrees, and listener right is 270 degrees. -180-180 wraps listener right to -90 degrees and reverses the displayed x axis so listener left appears visually left.

  • plot_type ({scatter, heatmap}, default=``heatmap``) – Source map renderer. scatter plots measured sources as colored markers. heatmap plots an interpolated azimuth/elevation color image.

  • colormap (str, default=``jet``) – Colormap name used for source map coloring.

  • show (bool, default=True) – If True, display the figure before returning.

  • show_titles (bool, default=True) – If True, adds the default figure title.

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

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

Returns:

Figure containing the selected HRTF difference source map.

Return type:

matplotlib.figure.Figure

Raises:

ValueError – If metric calculation fails, source positions are invalid, or the number of metric values differs from the number of source positions.

Examples

Plot a left ear LSD heatmap:

>>> from hrtfpykit.hrtf import load_hrtf
>>> from hrtfpykit.plots import compare_hrtf_difference
>>> hrtf_reference = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> hrtf_compared = load_hrtf("P0002_FreeFieldComp_44kHz.sofa")
>>> compare_hrtf_difference(
...     hrtf_reference,
...     hrtf_compared,
...     metric="lsd",
...     ear="left",
...     plot_type="heatmap",
...     colormap="viridis",
... )