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
Section titled “coherence”coherence( x: Signal | NumericArrayLike, y: Signal | NumericArrayLike, fs: float | None = None, *, nperseg: int | np.integer[Any] | None = None, overlap: float = 0.5,) -> CoherenceResultOrdinary 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
Section titled “CoherenceResult”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()
Section titled “CoherenceResult.plot()”CoherenceResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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
Section titled “FrequencyResponseResult”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()
Section titled “FrequencyResponseResult.plot()”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,) -> AxesPlot the Bode magnitude/phase and the coherence.
Parameters
| Name | Description |
|---|---|
language |
Label language, "en" (default) or "es". |
transfer_function
Section titled “transfer_function”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,) -> FrequencyResponseResultEstimate 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. |