rms

hrtfpykit.hrtf.rms(hrtf, output='db', reference=1.0, reduction_axis=None, reduction_method='mean')

Compute RMS values for an HRTF.

rms is an HRTF metric. It reads HRIR data from hrtf.IR.values and always computes the first RMS over the final sample axis. For standard HRTF data with shape (positions, ears, samples), this returns one RMS value for each source and ear.

reduction_axis applies only after the sample axis RMS is computed. It selects remaining HRTF axes such as source positions and ears. reduction_method then chooses how those RMS values are reduced: "mean" averages them, while "rms" applies a second RMS over the selected axes.

Reduction is applied in the selected output representation. With output="db", RMS values are converted to dB before reduction, so reduction_method="mean" averages dB values. With output="linear", reduction is applied to linear RMS amplitudes.

Parameters:

  • hrtf (HRTF) – HRTF object that provides IR.values with the final axis interpreted as time samples. Standard data use layout (..., ear, samples).

  • output ({"db", "linear"}) – Output representation. The default is "db". "linear" returns RMS amplitudes. "db" converts RMS amplitudes to dB values.

  • reference (float or "max") – Reference used when output="db". The default is 1.0. "max" uses the maximum RMS value before output conversion and domain reduction.

  • reduction_axis ({"position", "ear", "global"}, tuple of str, or None) – HRTF axis or axes reduced after the first RMS calculation. The default is None, which returns the natural position by ear RMS array. "position" or "positions" reduces all source-position axes and preserves ears. "ear" or "ears" reduces the ear axis and preserves positions. "global" reduces position and ear axes. "source" and "sources" are accepted as aliases for "position" and "positions".

  • reduction_method ({"mean", "rms"}) – Method used for reduction_axis. The default is "mean". "mean" computes the arithmetic average of the RMS values in the selected output representation. "rms" computes a second RMS over the selected axes. This parameter never changes the first RMS over the sample axis.

Returns:

RMS values in the selected output representation after the requested reduction.

Return type:

numpy.ndarray

Raises:

ValueError – If the HRTF object or IR data are invalid; if output, reduction_axis, or reduction_method is unsupported; or if a requested domain axis is unavailable for the RMS array shape.

Examples

Compute one RMS value per source and ear:

>>> from hrtfpykit.hrtf import load_hrtf, rms
>>> hrtf = load_hrtf("P0001_FreeFieldComp_44kHz.sofa")
>>> rms_values = rms(hrtf, output="db")
>>> rms_values.shape
(793, 2)

Average dB RMS values across source positions and ears:

>>> average_level = rms(hrtf, output="db", reduction_axis="global")
>>> average_level.shape
()

Apply a second RMS reduction across ears after the sample axis RMS:

>>> ear_reduced = rms(hrtf, output="linear", reduction_axis="ear", reduction_method="rms")
>>> ear_reduced.shape
(793,)