# environment.assessment.measurement

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

Canonical: https://docs.jmrp.io/phonometry/reference/api/environment/measurement/
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: Determination of environmental-noise sound pressure levels (ISO 1996-2:2017).

---

Determination of environmental-noise sound pressure levels (ISO 1996-2:2017).

The measurement companion of the ISO 1996-1 descriptors in
`phonometry.environment`. ISO 1996-2 covers *how* the levels that feed
those descriptors are obtained: the tonal adjustment for prominent tones, the
residual-noise correction, and the measurement-uncertainty budget.

**Tonal audibility (engineering method, ISO 1996-2:2007 Annex C).** From the
energy-summed tone level `Lpt` (Formula (C.1)) and the masking-noise level
`Lpn` in the critical band around the tone, the tonal audibility above the
masking threshold is
$\Delta L_\mathrm{ta} = L_{p\mathrm{t}} - L_{p\mathrm{n}} + 2 + \log_{10}[1 + (f_\mathrm{c}/502)^{2.5}]$ dB
(Formula (C.3)), and the
tonal adjustment is the piecewise function $K_\mathrm{t} = 0$ for
$\Delta L_\mathrm{ta} < 4$,
$K_\mathrm{t} = \Delta L_\mathrm{ta} - 4$ for $4 \le \Delta L_\mathrm{ta} \le 10$ and
$K_\mathrm{t} = 6$ for $\Delta L_\mathrm{ta} > 10$
(Formulae (C.4)–(C.6)). The critical bandwidth is 100 Hz for centre
frequencies up to 500 Hz and 20 % of the centre frequency above (Table C.1).
[`assess_tonal_audibility`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#assess_tonal_audibility) returns both in a plottable result. (The 2017
edition defers the full engineering method to ISO/PAS 20065; the detailed,
self-contained algorithm implemented here is the 2007/2009 Annex C one.)

**Survey method (ISO 1996-2:2017 Annex K).**
[`assess_tonal_survey`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#assess_tonal_survey) flags a one-third-octave band that exceeds *both*
neighbours by 15 dB (25–125 Hz), 8 dB (160–400 Hz) or 5 dB (500–10 000 Hz).

**Mean-audibility route (ISO 1996-2:2017 Table J.1).**
[`tonal_adjustment_from_mean_audibility`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#tonal_adjustment_from_mean_audibility) maps the ISO/PAS 20065 mean
audibility `ΔL` to `Kt` (0–6 dB).

**Residual-noise correction (Clause 10.4).**
$L = 10 \log_{10}(10^{L'/10} - 10^{L_\mathrm{res}/10})$ (Formula (16)); with a
residual
within 3 dB of the measured level no correction is allowed; the
*uncorrected* measured level `L'` is then the reportable value, as an upper
bound of the specific sound. [`gaussian_residual_level`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#gaussian_residual_level) estimates the
residual from percentile levels (Annex I, Formulae (I.1)/(I.2)).

**Measurement uncertainty (Clause 4, Annex F).**
$u = \sqrt{\sum (c_j \cdot u_j)^2}$
(Formula (2)) expanded by $k = 2$ (95 %) or $k = 1.3$ (80 %). The
residual-correction sensitivity coefficients (Formulae (F.7)/(F.8)) and the
repeated-measurement standard uncertainty (Formulae (17)–(20)) are provided.

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

## assess_tonal_audibility

```python
assess_tonal_audibility(
    tone_level: float,
    masking_noise_level: float,
    center_frequency: float,
) -> TonalAssessmentResult
```

Assess a tone's audibility and adjustment (ISO 1996-2 Annex C).

Combines [`tonal_audibility`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#tonal_audibility) and [`tonal_adjustment`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#tonal_adjustment) with the
[`critical_bandwidth`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#critical_bandwidth) into a plottable result.

**Parameters**

| Name | Description |
| :--- | :--- |
| `tone_level` | Energy-summed tone level `Lpt`, in dB. |
| `masking_noise_level` | Masking-noise level `Lpn`, in dB. |
| `center_frequency` | Critical-band centre frequency `fc`, in Hz. |

**Returns:** A [`TonalAssessmentResult`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#tonalassessmentresult).

## assess_tonal_survey

```python
assess_tonal_survey(
    levels: NumericArrayLike,
    *,
    frequencies: NumericArrayLike,
) -> TonalSurveyAssessment
```

Which one-third-octave bands hold a prominent tone? (Annex K, survey method).

ISO 1996-2:2017 Annex K, the objective survey method for the audibility
of tones in noise: a band is a prominent tone when it exceeds both
neighbours by 15 dB (25–125 Hz), 8 dB (160–400 Hz) or 5 dB
(500–10 000 Hz).

**Parameters**

| Name | Description |
| :--- | :--- |
| `levels` | One-third-octave-band time-average levels, in dB. |
| `frequencies` | The band centre frequencies, in Hz (same length). |

**Returns:** The answer, as a [`TonalSurveyAssessment`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#tonalsurveyassessment); the bands with a prominent tone are its `prominent` and `tone_frequencies`.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the inputs are empty, non-finite, or differ in length. |
| TypeError | if `frequencies` or `levels` holds a text or a value that is not a real number. |

## critical_bandwidth

```python
critical_bandwidth(center_frequency: float) -> float
```

Critical bandwidth around a tone (ISO 1996-2 Annex C, Table C.1).

100 Hz for a centre frequency up to 500 Hz, 20 % of the centre frequency
above 500 Hz.

**Parameters**

| Name | Description |
| :--- | :--- |
| `center_frequency` | Critical-band centre frequency `fc`, in Hz. |

**Returns:** Critical bandwidth, in Hz.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `center_frequency` is not positive/finite. |
| TypeError | if `center_frequency` is not a single number. |

## environmental_expanded_uncertainty

```python
environmental_expanded_uncertainty(
    standard_uncertainty: float,
    *,
    coverage: float = 0.95,
) -> float
```

Expanded uncertainty $U = k \cdot u$ (Clause 4).

Coverage factor $k = 2$ for 95 % or $k = 1.3$ for 80 %.

**Note**

Several domains define an expanded uncertainty over their own coverage
factors, and each says in its name what it is the uncertainty *of*:
this one is
[`environmental_expanded_uncertainty`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#environmental_expanded_uncertainty),
the building one is
[`insulation_expanded_uncertainty`](https://docs.jmrp.io/phonometry/reference/api/building/uncertainty/#insulation_expanded_uncertainty), and the
work-station one is
[`emission_expanded_uncertainty`](https://docs.jmrp.io/phonometry/reference/api/power/workstation/#emission_expanded_uncertainty), whose
coverage factor is the 1.6 that the ISO 11200 group prints. This one carried the bare name
until the work-station one needed it too, and one package holding the
unqualified spelling of a quantity three of them define was the reason
the other two had to be qualified.

**Parameters**

| Name | Description |
| :--- | :--- |
| `standard_uncertainty` | Combined standard uncertainty `u`, in dB. |
| `coverage` | Coverage probability (0.95 or 0.80). |

**Returns:** The expanded uncertainty `U`, in dB.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `u` is negative/non-finite or `coverage` is not one of the tabulated values. |
| TypeError | if `coverage` or `standard_uncertainty` is not a single number. |

## EnvironmentalMeasurementWarning

Warning for unreliable environmental-noise determinations.

## gaussian_residual_level

```python
gaussian_residual_level(l50: float, *, l90: float) -> float

gaussian_residual_level(l50: float, *, l95: float) -> float
```

Estimate the residual equivalent level from percentiles (Annex I).

$L_\mathrm{eq} = L_{50} + 0.115 \cdot ((L_{50} - L_{90})/1.28)^2$
(Formula (I.1)) or, with `L95`,
$L_\mathrm{eq} = L_{50} + 0.115 \cdot ((L_{50} - L_{95})/1.65)^2$
(Formula (I.2)). Supply exactly
one of `l90` / `l95`.

**Parameters**

| Name | Description |
| :--- | :--- |
| `l50` | Median level `L50`, in dB. |
| `l90` | Level exceeded 90 % of the time `L90`, in dB. |
| `l95` | Level exceeded 95 % of the time `L95`, in dB. |

**Returns:** The estimated Gaussian residual equivalent level, in dB.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If not exactly one of `l90` / `l95` is given, the inputs are not finite, or the percentile ordering is inverted (`L90`/`L95` cannot exceed `L50`, almost certainly swapped arguments, which the squared spread would otherwise hide). |
| TypeError | if `l50`, `l90` or `l95` is not a single number. |

## RepeatedMeasurementResult

```python
RepeatedMeasurementResult(
    mean_level: float,
    standard_uncertainty: float,
    approximate_uncertainty: float,
    n: int,
)
```

Energy-mean level and its uncertainty from repeats (Formulae (17)–(20)).

**Attributes**

| Name | Description |
| :--- | :--- |
| `mean_level` | Energy-mean level $L_k = 10 \log_{10}((1/N) \cdot \sum 10^{0.1 \cdot L_i})$, dB (Formula (18)). |
| `standard_uncertainty` | Standard uncertainty `uk` by the primary route, Formulae (17)+(19): the sample standard deviation `sk` of the energy values $10^{0.1 \cdot L_i}$ mapped back to level, $u_k = 10 \log_{10}(10^{0.1 \cdot L_k} + s_k) - L_k$, in dB. |
| `approximate_uncertainty` | The Note 2 substitute (Formula (20)), $\sqrt{\sum (L_i - L_k)^2/(N - 1)}$, in dB; valid only when the spread of the `Li` is small; it grossly inflates for spread levels. |
| `n` | Number of measurements. |

## residual_correction_uncertainty

```python
residual_correction_uncertainty(
    measured_level: float,
    residual_level: float,
    measured_uncertainty: float,
    residual_uncertainty: float,
) -> float
```

Uncertainty of the residual-corrected level (Formulae (F.7)–(F.9)).

With $m = 10^{-0.1(L' - L_\mathrm{res})}$, the sensitivity coefficients
are
$c_{L'} = 1/(1 - m)$ and $c_\mathrm{res} = -m/(1 - m)$, and
$u_L = \sqrt{c_{L'}^2 \cdot u_{L'}^2 + c_\mathrm{res}^2 \cdot u_\mathrm{res}^2}$.

**Parameters**

| Name | Description |
| :--- | :--- |
| `measured_level` | Measured level `L'`, in dB. |
| `residual_level` | Residual level `Lres`, in dB. |
| `measured_uncertainty` | Standard uncertainty of `L'`, in dB. |
| `residual_uncertainty` | Standard uncertainty of `Lres`, in dB. |

**Returns:** The combined standard uncertainty of the corrected level, in dB.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the residual is not below the measured level or an uncertainty is negative/non-finite. |
| TypeError | if `measured_level`, `measured_uncertainty`, `residual_level` or `residual_uncertainty` is not a single number. |

## residual_sound_correction

```python
residual_sound_correction(
    measured_level: float,
    residual_level: float,
) -> ResidualCorrectionResult
```

Correct a measured level for residual sound (Formula (16)).

$L = 10 \log_{10}(10^{L'/10} - 10^{L_\mathrm{res}/10})$. When the residual is
within 3 dB
of the measured level, §10.4 allows **no** correction: the *uncorrected*
measured level `L'` is the reportable value, as an upper bound of the
specific sound (the corrected value would understate reliability, being
the lower-side estimate). The result is then flagged `reliable = False`
and an [`EnvironmentalMeasurementWarning`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#environmentalmeasurementwarning) is issued; report
`reportable_upper_bound` (= `L'`), not `corrected_level`.

**Parameters**

| Name | Description |
| :--- | :--- |
| `measured_level` | Measured level `L'` including residual, in dB. |
| `residual_level` | Residual (background) level `Lres`, in dB. |

**Returns:** A [`ResidualCorrectionResult`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#residualcorrectionresult).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the levels are not finite or the residual is not below the measured level. |
| TypeError | if `measured_level` or `residual_level` is not a single number. |

## ResidualCorrectionResult

```python
ResidualCorrectionResult(
    corrected_level: float,
    reportable_upper_bound: float,
    margin: float,
)
```

Residual-noise-corrected level (ISO 1996-2:2017 Clause 10.4).

**Attributes**

| Name | Description |
| :--- | :--- |
| `corrected_level` | The corrected level `L` (Formula (16)), in dB. When `reliable` is `False` the standard allows *no* correction; this value is then informative only (it estimates the source from below) and must not be reported as the result. |
| `reportable_upper_bound` | The *measured* level `L'`, in dB. When the margin is 3 dB or less, §10.4 permits reporting the measured level as an upper bound of the specific sound level; this field carries that reportable value. |
| `margin` | `L' − Lres`, in dB (measured minus residual). |

### ResidualCorrectionResult.reliable

*property*

Whether the residual is more than 3 dB below the measured level.

Read from `margin`, settled, against the 3 dB of §10.4;
`False` when no correction is allowed and only the uncorrected
`L'` may be reported, as an upper bound.

## tonal_adjustment

```python
tonal_adjustment(audibility: float) -> float
```

Tonal adjustment `Kt` from the audibility (Formulae (C.4)–(C.6)).

$K_\mathrm{t} = 0$ for $\Delta L_\mathrm{ta} < 4$,
$K_\mathrm{t} = \Delta L_\mathrm{ta} - 4$ for $4 \le \Delta L_\mathrm{ta} \le 10$
and
$K_\mathrm{t} = 6$ for $\Delta L_\mathrm{ta} > 10$. `Kt` is not restricted
to integers.

**Parameters**

| Name | Description |
| :--- | :--- |
| `audibility` | Tonal audibility `ΔLta`, in dB. |

**Returns:** Tonal adjustment `Kt`, in dB (0 to 6).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `audibility` is not finite. |
| TypeError | if `audibility` is not a single number. |

## tonal_adjustment_from_mean_audibility

```python
tonal_adjustment_from_mean_audibility(
    mean_audibility: float,
    *,
    coarse: bool = False,
) -> int
```

Tonal adjustment `Kt` from the mean audibility `ΔL` (Table J.1).

The ISO 1996-2:2017 route that maps the ISO/PAS 20065 mean audibility
`ΔL` to an integer adjustment. With `coarse=True` the 3-dB-step
alternative applies ($\Delta L \le 2$ → 0,
$2 < \Delta L \le 9$ → 3, $\Delta L > 9$ → 6).

**Parameters**

| Name | Description |
| :--- | :--- |
| `mean_audibility` | Mean audibility `ΔL`, in dB. |
| `coarse` | Use the coarse 3-dB-step mapping instead of Table J.1. |

**Returns:** Tonal adjustment `Kt`, in dB (integer, 0 to 6).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `mean_audibility` is not finite. |
| TypeError | if `mean_audibility` is not a single number. |

## tonal_audibility

```python
tonal_audibility(
    tone_level: float,
    masking_noise_level: float,
    center_frequency: float,
) -> float
```

Tonal audibility above the masking threshold (Formula (C.3)).

$\Delta L_\mathrm{ta} = L_{p\mathrm{t}} - L_{p\mathrm{n}} + 2 + \log_{10}[1 + (f_\mathrm{c}/502)^{2.5}]$
dB.

**Parameters**

| Name | Description |
| :--- | :--- |
| `tone_level` | Energy-summed tone level `Lpt` in the critical band, in dB (see Formula (C.1)). |
| `masking_noise_level` | Masking-noise level `Lpn` in the critical band, in dB (see Formula (C.2)/(C.11)). |
| `center_frequency` | Critical-band centre frequency `fc`, in Hz. |

**Returns:** Tonal audibility `ΔLta`, in dB (dB above the masking threshold).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `center_frequency` is not positive/finite or the levels are not finite. |
| TypeError | if `center_frequency`, `masking_noise_level` or `tone_level` is not a single number. |

## TonalAssessmentResult

```python
TonalAssessmentResult(
    tone_level: float,
    masking_noise_level: float,
    center_frequency: float,
    critical_bandwidth: float,
    audibility: float,
    adjustment: float,
)
```

Tonal-audibility assessment of a tone in noise (ISO 1996-2 Annex C).

**Attributes**

| Name | Description |
| :--- | :--- |
| `tone_level` | Energy-summed tone level `Lpt`, in dB. |
| `masking_noise_level` | Masking-noise level `Lpn`, in dB. |
| `center_frequency` | Critical-band centre frequency `fc`, in Hz. |
| `critical_bandwidth` | Critical bandwidth, in Hz (Table C.1). |
| `audibility` | Tonal audibility `ΔLta`, in dB (Formula (C.3)). |
| `adjustment` | Tonal adjustment `Kt`, in dB (Formulae (C.4)–(C.6)). |

### TonalAssessmentResult.plot()

```python
TonalAssessmentResult.plot(
    ax: Axes | None = None,
    *,
    language: Literal['en', 'es'] = 'en',
    **kwargs: Any,
) -> Axes
```

Plot the `Kt(ΔLta)` adjustment curve with this tone marked.

**Parameters**

| Name | Description |
| :--- | :--- |
| `language` | The language of the labels: `"en"` or `"es"`. |

## TonalSurveyAssessment

```python
TonalSurveyAssessment(
    levels: NDArray[np.float64],
    frequencies: NDArray[np.float64],
)
```

Prominent tones in a one-third-octave spectrum, by the survey method (Annex K).

A band holds a prominent tone when it exceeds *both* adjacent
one-third-octave bands by the level difference for its range: 15 dB
(25–125 Hz), 8 dB (160–400 Hz), 5 dB (500–10 000 Hz). The two end bands,
with no pair of neighbours, never do. The thresholds, the level
differences and the answer are read from the levels and the band centres,
so they are not fields.

**Note**

Annex K defines the thresholds for 25 Hz to 10 kHz only. Bands
supplied outside that span are judged with the nearest rule
(15 dB below 25 Hz, 5 dB above 10 kHz), outside the standard.

**Attributes**

| Name | Description |
| :--- | :--- |
| `levels` | One-third-octave-band time-average levels, in dB. |
| `frequencies` | The band centre frequencies, in Hz (same length). |

### TonalSurveyAssessment.level_differences

*property*

Each band less the louder of its two neighbours, in dB; NaN at the ends.

### TonalSurveyAssessment.min_level_differences

*property*

The level difference Annex K asks of each band, in dB.

### TonalSurveyAssessment.plot()

```python
TonalSurveyAssessment.plot(
    ax: Axes | None = None,
    *,
    language: Literal['en', 'es'] = 'en',
    **kwargs: Any,
) -> Axes
```

Draw the spectrum with the prominent bands marked and each band's bar.

**Parameters**

| Name | Description |
| :--- | :--- |
| `ax` | Existing axes, or `None` to create a figure. |
| `language` | Label language, `"en"` (default) or `"es"`. |
| `kwargs` | Forwarded to the band bars. |

**Returns:** The axes.

### TonalSurveyAssessment.prominent

*property*

Whether each band holds a prominent tone; the two end bands never do.

Judged settled: a band 5 dB above its neighbours in decimal reaches the
threshold whichever way the last bits of the subtraction fall.

### TonalSurveyAssessment.tone_frequencies

*property*

The centres of the bands that hold a prominent tone, in Hz.

## uncertainty_from_repeated_measurements

```python
uncertainty_from_repeated_measurements(
    levels: NumericArrayLike,
) -> RepeatedMeasurementResult
```

Energy mean and its uncertainty from repeated levels (Formulae (17)–(20)).

$L_k = 10 \log_{10}((1/N) \cdot \sum 10^{0.1 \cdot L_i})$ (Formula (18)).
The standard
uncertainty follows the primary §10.5 route: the sample standard
deviation `sk` of the energy values $10^{0.1 \cdot L_i}$
(Formula (17))
propagated back to level,
$u_k = 10 \log_{10}(10^{0.1 \cdot L_k} + s_k) - L_k$
(Formula (19)). The Note 2 level-domain approximation
$\sqrt{\sum (L_i - L_k)^2/(N - 1)}$ (Formula (20)) is also
reported as
`approximate_uncertainty`; it is valid only "if the difference between
different Li is small", so a spread above 3 dB triggers an
[`EnvironmentalMeasurementWarning`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#environmentalmeasurementwarning) (e.g. [50, 60, 70] dB gives
3.94 dB by Formulae (17)+(19) but 12.18 dB by Formula (20)).

**Parameters**

| Name | Description |
| :--- | :--- |
| `levels` | The repeated measured levels `Li`, in dB (at least two). |

**Returns:** A [`RepeatedMeasurementResult`](https://docs.jmrp.io/phonometry/reference/api/environment/measurement/#repeatedmeasurementresult).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If fewer than two finite levels are given. |
| TypeError | if `levels` holds a text or a value that is not a real number. |
