Skip to content

electroacoustics.frequency_response

Frequency-response and coherence estimators (Bendat & Piersol).

Two-channel (input/output) system identification from measured signals, using the Welch-averaged cross- and auto-spectral densities. Following Bendat & Piersol, Random Data: Analysis and Measurement Procedures (4th ed., 2010):

  • the H1 estimator (unbiased when the noise is on the output),
  • the H2 estimator (unbiased when the noise is on the input),
  • the ordinary coherence , the fraction of the output power linearly explained by the input.

For a noiseless linear time-invariant path both estimators recover the true transfer function and the coherence is unity; additive output noise biases H2 but not H1 and pulls the coherence down to , which is the analytic oracle used to verify the implementation.

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

coherence(
x: Signal | NumericArrayLike,
y: Signal | NumericArrayLike,
fs: float | None = None,
*,
nperseg: int | np.integer[Any] | None = None,
overlap: float = 0.5,
) -> CoherenceResult

Ordinary coherence between x and y (Bendat & Piersol).

: unity for a noiseless linear path and with additive output noise. Averaging over several segments is required for a meaningful estimate (a single segment gives ).

Parameters

Name Description
x First signal, 1-D. Accepts a phonometry.io.Signal, whose calibration is applied to the samples. The coherence is a normalised ratio, so it is unchanged whichever of the two is calibrated and by how much.
y Second signal, 1-D, same length as x. Same treatment as x.
fs Sample rate, in Hz. Required when both records are bare arrays; either may be a Signal and supply it, and two Signals recorded at different rates are refused rather than arbitrated.
nperseg Welch segment length; None picks a default.
overlap Segment overlap fraction (default 0.5).

Returns: The bins and the coherence at each, as a CoherenceResult.

Raises

Exception When
ValueError If the inputs or parameters are invalid.
TypeError if nperseg is a flag, a text or an array where a count goes, or x or y holds a text or a value that is not a real number.
CoherenceResult(
frequencies: NDArray[np.float64],
coherence: NDArray[np.float64],
)

The ordinary coherence of two records, frequency by frequency.

What coherence returns: the frequency axis and the coherence, named, where a (frequencies, gamma_squared) tuple used to be unpacked by position.

Attributes

Name Description
frequencies The Welch frequency bins, in Hz.
coherence at each bin.
CoherenceResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the coherence against frequency, on 0 to 1.

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the coherence curve.

Returns: The axes.

FrequencyResponseResult(
frequencies: NDArray[np.float64],
response: NDArray[np.complex128],
magnitude_db: NDArray[np.float64],
phase_rad: NDArray[np.float64],
coherence: NDArray[np.float64],
estimator: Literal['H1', 'H2'],
)

Estimated frequency response of an input/output path (Bendat & Piersol).

Attributes

Name Description
frequencies Frequency axis, in Hz.
response Complex frequency-response estimate H(f).
magnitude_db Magnitude , in dB.
phase_rad Phase of H, in radians (unwrapped).
coherence Ordinary coherence .
estimator Estimator used ('H1' or 'H2').
FrequencyResponseResult.plot(
ax: None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> tuple[Axes, Axes, Axes]
FrequencyResponseResult.plot(
ax: Axes,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the Bode magnitude/phase and the coherence.

Parameters

Name Description
language Label language, "en" (default) or "es".
transfer_function(
x: Signal | NumericArrayLike,
y: Signal | NumericArrayLike,
fs: float | None = None,
*,
estimator: Literal['H1', 'H2'] = 'H1',
nperseg: int | np.integer[Any] | None = None,
overlap: float = 0.5,
) -> FrequencyResponseResult

Estimate the frequency response from input x to output y.

(the default; unbiased for output noise) or (unbiased for input noise), from Welch-averaged Hann segments. The ordinary coherence is returned alongside as a data-quality indicator.

Parameters

Name Description
x Input (reference) signal, 1-D. Accepts a phonometry.io.Signal, whose calibration is applied to the samples. The response is a ratio of the two records, so with factors c_x on x and c_y on y it comes out as (c_y / c_x) H: a factor the two share cancels, calibrating only y multiplies the response by c_y and calibrating only x divides it by c_x. That is the right answer for a pair that is genuinely in two different units.
y Output (response) signal, 1-D, same length as x. Same treatment as x.
fs Sample rate, in Hz. Required when both records are bare arrays; either may be a Signal and supply it, and two Signals recorded at different rates are refused rather than arbitrated.
estimator 'H1' (default) or 'H2'.
nperseg Welch segment length; None picks a length targeting about 4 Hz resolution (as in intensity).
overlap Segment overlap fraction (default 0.5).

Returns: A FrequencyResponseResult.

Raises

Exception When
ValueError If the inputs or parameters are invalid.
TypeError if nperseg is a flag, a text or an array where a count goes, or estimator is not a text, or x or y holds a text or a value that is not a real number.