Source code for acoustic_spaces.compare

"""Comparing a simulated response with a measured one, by the parameters of ISO 3382-1.

A model is checked against the room it stands for by comparing its parameters with
those measured there, octave band by octave band, in just noticeable differences (JNDs,
ISO 3382-1:2009, annex A, table A.1, and annex B for IACC; by analogy for T20, T30 and
C50, see :data:`JND`): a difference of less than one JND is too small to be heard.

- :func:`compare_impulse_responses` analyses two impulse responses, each at its own
  sample rate, as :func:`~acoustic_spaces.parameters.from_impulse_response` does.
- :func:`compare_parameters` compares two sets of parameters already computed.

Both give a :class:`Comparison`: per parameter and band the simulated and the measured
value, their difference and that difference in JNDs; and per parameter, how many bands
are within one JND and the mean absolute difference in JNDs from 125 Hz to 4 kHz. A
band where either side has no value is missing, with the reason, never zero: a
response that decays by less than 20 dB, a decay time whose range does not clear the
background noise, G without a reference on both sides, or a band above half a
response's sample rate.
"""

from __future__ import annotations

import math
from collections.abc import Sequence
from dataclasses import dataclass

import numpy as np

from acoustic_spaces.materials.bands import OCTAVE_BANDS_HZ
from acoustic_spaces.parameters import (
    _MIN_DECAY_DB,
    _NOISE_CLEARANCE_DB,
    ALL_PARAMETERS,
    DECAY_RANGES,
    PARAMETERS,
    RoomParameters,
    _band_label,
    _beyond_nyquist,
    _label,
    _symbol,
    band_decay,
    from_impulse_response,
)

#: Just noticeable differences per parameter: the JND, and whether it is a fraction of the
#: measured value (the decay times) rather than a step in the parameter's own unit (dB, s,
#: or none for D50, LF, LFC and IACC). ISO 3382-1:2009 gives those of EDT, C80, D50, Ts, G
#: and LF (annex A, table A.1) and of IACC (annex B); T20 and T30 take EDT's and C50
#: takes C80's by analogy, and the directional decay times take that of T30. The standard
#: gives none for LJ and stage support, which are not compared.
JND: dict[str, tuple[float, bool]] = {
    "edt": (0.05, True),
    "t20": (0.05, True),
    "t30": (0.05, True),
    "c50": (1.0, False),
    "c80": (1.0, False),
    "d50": (0.05, False),
    "ts": (0.010, False),
    "g": (1.0, False),
    "lf": (0.05, False),
    "lfc": (0.05, False),
    "iacc_e": (0.075, False),
    "iacc_l": (0.075, False),
    "t30_x": (0.05, True),
    "t30_y": (0.05, True),
    "t30_z": (0.05, True),
}
#: The octave bands the mean difference of each parameter is taken over (Hz).
SUMMARY_BANDS_HZ: tuple[int, ...] = (125, 250, 500, 1000, 2000, 4000)
#: The standard error, in JNDs, past which more rays would be worth tracing: the
#: parameter would change by about a JND or more between runs with other seeds.
CONVERGED_JND = 0.5


[docs] @dataclass class ParameterComparison: """One parameter of a simulated and a measured response, one value per octave band. ``difference`` is the simulated value minus the measured one, and ``difference_jnd`` the same in JNDs, so both are positive where the simulation reads higher. They are NaN in the bands that cannot be compared; ``missing`` holds the reason for each of those, and None for the bands that are compared. """ name: str simulated: np.ndarray measured: np.ndarray #: The JND in each band, in the parameter's unit (NaN for a relative JND where #: there is no measured value to take it of). jnd: np.ndarray difference: np.ndarray difference_jnd: np.ndarray missing: list[str | None] @property def compared(self) -> int: """How many bands have a value on both sides.""" return sum(reason is None for reason in self.missing) @property def within_jnd(self) -> int: """How many of the compared bands are at most one JND apart.""" compared = np.isfinite(self.difference_jnd) return int(np.count_nonzero(np.abs(self.difference_jnd[compared]) <= 1.0)) @property def mean_abs_jnd(self) -> float: """Mean absolute difference in JNDs over the compared bands from 125 Hz to 4 kHz (``SUMMARY_BANDS_HZ``); NaN when none of them is compared.""" middle = np.isin(OCTAVE_BANDS_HZ, SUMMARY_BANDS_HZ) & np.isfinite(self.difference_jnd) if not middle.any(): return math.nan return float(np.abs(self.difference_jnd[middle]).mean())
def _plain(values: np.ndarray) -> list[float | None]: return [float(v) if np.isfinite(v) else None for v in values] def _cell(text: str, mark: str = " ") -> str: """One band of a table: 7 characters, right-aligned, and room for a mark.""" return f"{text:>7}{mark}"
[docs] @dataclass class Comparison: """A simulated and a measured response compared parameter by parameter. ``simulated`` and ``measured`` are the parameters of each side, and ``parameters`` a :class:`ParameterComparison` for each name of :data:`~acoustic_spaces.parameters.PARAMETERS`, and of those further ones with a JND that both sides give, which indexing gives as well: ``comparison["t30"].difference_jnd``. """ simulated: RoomParameters measured: RoomParameters parameters: dict[str, ParameterComparison] def __getitem__(self, name: str) -> ParameterComparison: return self.parameters[name]
[docs] def as_dict(self) -> dict: """Plain lists and numbers, with None for missing values (JSON friendly).""" out = {} for name, p in self.parameters.items(): jnd, relative = JND[name] mean = p.mean_abs_jnd out[name] = { "jnd": jnd, "jnd_relative": relative, "simulated": _plain(p.simulated), "measured": _plain(p.measured), "difference": _plain(p.difference), "difference_jnd": _plain(p.difference_jnd), "missing": list(p.missing), "compared": p.compared, "within_jnd": p.within_jnd, "mean_abs_jnd": mean if math.isfinite(mean) else None, } return { "bands_hz": list(OCTAVE_BANDS_HZ), "summary_bands_hz": list(SUMMARY_BANDS_HZ), "parameters": out, }
[docs] def table(self) -> str: """A text table: per parameter, the simulated and the measured value in each band and their difference in JNDs, marked * where it is more than one; then why the bands shown as - cannot be compared.""" lines = [f"{'':<16}" + "".join(_cell(_band_label(f)) for f in OCTAVE_BANDS_HZ)] # Missing bands, grouped: (reason, bands) -> the parameters it applies to. groups: dict[tuple[str, tuple[int, ...]], list[str]] = {} for name, p in self.parameters.items(): fmt = ".1f" if ALL_PARAMETERS[name][0] == "dB" else ".3f" for row, (what, values) in enumerate((("sim", p.simulated), ("meas", p.measured))): cells = "".join(_cell(f"{v:{fmt}}" if np.isfinite(v) else "-") for v in values) lines.append(f"{_label(name) if row == 0 else '':<10}{what:<6}{cells}") cells = "".join( _cell(f"{j:+.1f}", "*" if abs(j) > 1.0 else " ") if np.isfinite(j) else _cell("-") for j in p.difference_jnd ) lines.append(f"{'':<10}{'JNDs':<6}{cells}") bands: dict[str, list[int]] = {} for f, reason in zip(OCTAVE_BANDS_HZ, p.missing, strict=True): if reason is not None: bands.setdefault(reason, []).append(f) for reason, where in bands.items(): groups.setdefault((reason, tuple(where)), []).append(_symbol(name)) lines.append("JNDs: simulated minus measured, in just noticeable differences; * beyond one") if groups: lines.append("missing:") for (reason, where), names in groups.items(): at = ( "in every band" if len(where) == len(OCTAVE_BANDS_HZ) else "at " + ", ".join(_band_label(f) for f in where) ) lines.append(f" {', '.join(names)} {at}: {reason}") return "\n".join(line.rstrip() for line in lines)
[docs] def summary(self) -> str: """A text table: per parameter, how many of the compared bands are within one JND, and the mean absolute difference in JNDs from 125 Hz to 4 kHz.""" lines = [f"{'':<10}{'within 1 JND':>14}{'mean |JNDs|':>14}"] for name, p in self.parameters.items(): mean = p.mean_abs_jnd within = f"{p.within_jnd} of {p.compared}" lines.append( f"{_label(name):<10}{within:>14}{f'{mean:.1f}' if math.isfinite(mean) else '-':>14}" ) span = f"{_band_label(SUMMARY_BANDS_HZ[0])} to {_band_label(SUMMARY_BANDS_HZ[-1])}" lines.append(f"mean |JNDs|: the mean absolute difference in JNDs from {span}") return "\n".join(lines)
def _missing( name: str, side: str, params: RoomParameters, band: int, decay_range_db: np.ndarray | None, sample_rate: float | None, ) -> str | None: """Why the value of ``name`` in ``band`` of one side cannot be compared, or None.""" value = float(getattr(params, name)[band]) if math.isfinite(value): return None symbol = _symbol(name) if not math.isnan(value): return f"the {side} {symbol} is infinite" # clarity with no energy on one side if sample_rate is not None and _beyond_nyquist(sample_rate)[band]: half = sample_rate / 2.0 return f"the {side} response, at {sample_rate:g} Hz, holds nothing above {half:g} Hz" if all(math.isnan(float(getattr(params, n)[band])) for n in PARAMETERS): # The parameters rule: a band whose decay stops short has none at all. return f"the {side} response decays by less than {-_MIN_DECAY_DB:.0f} dB" if name == "g": return f"no reference for the {side} G" if name in DECAY_RANGES: bottom = DECAY_RANGES[name][1] needed = _NOISE_CLEARANCE_DB - bottom if decay_range_db is not None and decay_range_db[band] < needed: return ( f"the {side} decay clears the noise by {decay_range_db[band]:.0f} dB, " f"{symbol} needs {needed:.0f} dB" ) return f"the {side} decay does not reach {bottom:.0f} dB for {symbol}" return f"no {side} {symbol}" def _compare( simulated: RoomParameters, measured: RoomParameters, simulated_range_db: np.ndarray | None = None, measured_range_db: np.ndarray | None = None, simulated_rate: float | None = None, measured_rate: float | None = None, ) -> Comparison: bands = len(OCTAVE_BANDS_HZ) for side, params in (("simulated", simulated), ("measured", measured)): if any(np.shape(getattr(params, name)) != (bands,) for name in PARAMETERS): raise ValueError( f"the {side} parameters need one value per octave band, " f"{_band_label(OCTAVE_BANDS_HZ[0])} to {_band_label(OCTAVE_BANDS_HZ[-1])}" ) names = list(PARAMETERS) + [ name for name in ALL_PARAMETERS if name not in PARAMETERS and name in JND and all(np.isfinite(getattr(p, name)).any() for p in (simulated, measured)) ] compared = {} for name in names: s = np.asarray(getattr(simulated, name), dtype=float) m = np.asarray(getattr(measured, name), dtype=float) step, relative = JND[name] # A relative JND is taken of the measured value, the one the model is checked # against. jnd = step * np.abs(m) if relative else np.full(bands, step) missing = [] for b in range(bands): reasons = [ _missing(name, "simulated", simulated, b, simulated_range_db, simulated_rate), _missing(name, "measured", measured, b, measured_range_db, measured_rate), ] missing.append("; ".join(r for r in reasons if r) or None) ok = np.array([reason is None for reason in missing]) # Only the compared bands are subtracted, as infinities would warn; the others # stay NaN. difference = np.full(bands, math.nan) difference[ok] = s[ok] - m[ok] difference_jnd = np.full(bands, math.nan) difference_jnd[ok] = difference[ok] / jnd[ok] compared[name] = ParameterComparison( name=name, simulated=s, measured=m, jnd=jnd, difference=difference, difference_jnd=difference_jnd, missing=missing, ) return Comparison(simulated=simulated, measured=measured, parameters=compared)
[docs] def compare_parameters( simulated: RoomParameters, measured: RoomParameters, *, simulated_rate: float | None = None, measured_rate: float | None = None, ) -> Comparison: """Compare two sets of parameters, one value per octave band of ``OCTAVE_BANDS_HZ``. NaN values are missing bands, whose reason is read from the parameters themselves: a band with no parameter at all lies above half the sample rate of its response (when ``simulated_rate`` or ``measured_rate``, in Hz, gives it) or else decays by less than 20 dB, G alone is NaN without a reference, and a decay time alone when the decay does not reach the bottom of its fit range (:func:`compare_impulse_responses` also tells when the noise is in the way). LF, LFC, IACC and the directional decay times are compared where both sides give them. """ return _compare(simulated, measured, simulated_rate=simulated_rate, measured_rate=measured_rate)
[docs] def in_jnds(values: RoomParameters, errors: RoomParameters) -> dict[str, np.ndarray]: """``errors`` of ``values`` (such as their standard errors, :meth:`~acoustic_spaces.engine.response.Response.standard_errors`) in JNDs, for each parameter with a JND, per octave band; a relative JND is taken of the value itself. NaN where either is undefined.""" out = {} for name, (step, relative) in JND.items(): value = np.asarray(getattr(values, name), dtype=float) error = np.asarray(getattr(errors, name), dtype=float) jnd = step * np.abs(value) if relative else np.full(value.shape, step) ok = np.isfinite(value) & np.isfinite(error) & (jnd > 0) out[name] = np.full(value.shape, math.nan) out[name][ok] = error[ok] / jnd[ok] return out
[docs] def compare_impulse_responses( simulated: np.ndarray, simulated_rate: float, measured: np.ndarray, measured_rate: float, *, simulated_reference: float | Sequence[float] | None = None, measured_reference: float | Sequence[float] | None = None, filters: str = "iec", noise: bool = True, ) -> Comparison: """Compare a simulated and a measured impulse response, each at its own sample rate. Each is mono, (samples,) or (samples, 1), and analysed as by :func:`~acoustic_spaces.parameters.from_impulse_response` with the same ``filters`` and ``noise`` settings. The references are those of its ``reference_energy``: the energy of the same source at 10 m in free field, per band or of a broadband impulse (0.01 for responses made by this package, 0.01 * ir_gain**2 for those written with ``normalize``). G is compared only where both sides have one; without, it is missing in every band. A band at or above half a response's sample rate is missing (see :func:`~acoustic_spaces.parameters.from_impulse_response`). """ sides = {} for side, ir, rate, reference in ( ("simulated", simulated, simulated_rate, simulated_reference), ("measured", measured, measured_rate, measured_reference), ): params = from_impulse_response(ir, rate, reference, filters=filters, noise=noise) # The decay ranges tell which decay times the background noise leaves out. decay = band_decay(ir, rate, filters=filters, noise=noise) sides[side] = (params, decay.decay_range_db) (sim, sim_range), (meas, meas_range) = sides["simulated"], sides["measured"] return _compare(sim, meas, sim_range, meas_range, simulated_rate, measured_rate)
__all__ = [ "CONVERGED_JND", "JND", "SUMMARY_BANDS_HZ", "Comparison", "ParameterComparison", "compare_impulse_responses", "compare_parameters", "in_jnds", ]