# electroacoustics.frequency_response

> One page of the phonometry documentation, as Markdown. Index: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/reference/api/electroacoustics/frequency-response/
Language: en
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-07-15
Updated: 2026-11-11T17:49:24Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Frequency-response and coherence estimators (Bendat & Piersol).

---

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 $H_1 = G_{xy} / G_{xx}$ (unbiased when the
  noise is on the output),
* the **H2** estimator $H_2 = G_{yy} / G_{yx}$ (unbiased when the
  noise is on the input),
* the **ordinary coherence**
  $\gamma^2 = \lvert G_{xy} \rvert^2 / (G_{xx} \cdot G_{yy}) \in [0, 1]$, 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
$\mathrm{SNR} / (1 + \mathrm{SNR})$, 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

```python
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 $\gamma^2(f)$ between `x` and `y`
(Bendat & Piersol).

$\gamma^2 = \lvert G_{xy} \rvert^2 / (G_{xx} G_{yy}) \in [0, 1]$: unity for a noiseless linear path and
$\mathrm{SNR}/(1+\mathrm{SNR})$ with additive output noise.
Averaging over several segments is required for a meaningful estimate
(a single segment gives $\gamma^2 \equiv 1$).

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | First signal, 1-D. Accepts a [`phonometry.io.Signal`](https://docs.jmrp.io/phonometry/reference/api/io/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`](https://docs.jmrp.io/phonometry/reference/api/io/io/#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`](https://docs.jmrp.io/phonometry/reference/api/electroacoustics/frequency-response/#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

```python
CoherenceResult(
    frequencies: NDArray[np.float64],
    coherence: NDArray[np.float64],
)
```

The ordinary coherence of two records, frequency by frequency.

What [`coherence`](https://docs.jmrp.io/phonometry/reference/api/electroacoustics/frequency-response/#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` | $\gamma^2(f) \in [0, 1]$ at each bin. |

### CoherenceResult.plot()

```python
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

```python
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 $20 \log_{10} \lvert H \rvert$, in dB. |
| `phase_rad` | Phase of `H`, in radians (unwrapped). |
| `coherence` | Ordinary coherence $\gamma^2(f) \in [0, 1]$. |
| `estimator` | Estimator used (`'H1'` or `'H2'`). |

### FrequencyResponseResult.plot()

```python
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

```python
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`.

$H_1 = G_{xy} / G_{xx}$ (the default; unbiased for output
noise) or $H_2 = G_{yy} / G_{yx}$ (unbiased for input noise),
from Welch-averaged Hann segments. The ordinary coherence
$\gamma^2 = \lvert G_{xy} \rvert^2 / (G_{xx} G_{yy})$ is
returned alongside as a data-quality indicator.

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | Input (reference) signal, 1-D. Accepts a [`phonometry.io.Signal`](https://docs.jmrp.io/phonometry/reference/api/io/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`](https://docs.jmrp.io/phonometry/reference/api/io/io/#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`](https://docs.jmrp.io/phonometry/reference/api/power/intensity/)). |
| `overlap` | Segment overlap fraction (default 0.5). |

**Returns:** A [`FrequencyResponseResult`](https://docs.jmrp.io/phonometry/reference/api/electroacoustics/frequency-response/#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. |
