environment.assessment.measurement

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 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). tonal_seeking_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 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^{\prime }/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 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(
    tone_level: float,
    masking_noise_level: float,
    centre_frequency: float,
) -> TonalAssessmentResult

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

Combines tonal_audibility and tonal_adjustment with the critical_bandwidth into a plottable result.

Parameters

Returns: A TonalAssessmentResult.

combined_standard_uncertainty(
    contributions: Sequence[float] | Sequence[tuple[float, float]] | np.ndarray,
) -> float

Combined standard uncertainty (Formula (2)).

$u=\sqrt{\sum (c_j\cdot u_j{)}^2}$.

Parameters

Returns: The combined standard uncertainty, in dB.

Raises

critical_bandwidth(centre_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

Returns: Critical bandwidth, in Hz.

Raises

Warning for unreliable environmental-noise determinations.

expanded_uncertainty(
    standard_uncertainty: float,
    *,
    confidence: float = 0.95,
) -> float

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

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

Parameters

Returns: The expanded uncertainty U, in dB.

Raises

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

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

Raises

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

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

Attributes

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^{\prime }-L_{\mathrm{res}})}$, the sensitivity coefficients are $c_{L^{\prime }}=1/(1-m)$ and $c_{\mathrm{res}}=-m/(1-m)$, and $u_L=\sqrt{c_{L^{\prime }}^2\cdot u_{L^{\prime }}^2+c_{\mathrm{res}}^2\cdot u_{\mathrm{res}}^2}$.

Parameters

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

Raises

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^{\prime }/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 is issued; report reportable_upper_bound (= L'), not corrected_level.

Parameters

Returns: A ResidualCorrectionResult.

Raises

ResidualCorrectionResult(
    corrected_level: float,
    reportable_upper_bound: float,
    margin: float,
    reliable: bool,
)

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

Attributes

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

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

Raises

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

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

Raises

tonal_audibility(
    tone_level: float,
    masking_noise_level: float,
    centre_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

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

Raises

tonal_seeking_survey(
    levels: Sequence[float] | np.ndarray,
    frequencies: Sequence[float] | np.ndarray,
) -> np.ndarray

Flag prominent tones by the one-third-octave survey method (Annex K).

A band is flagged 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 (no pair of neighbours) are never flagged.

Parameters

Returns: Boolean array, True where a prominent tone is present.

Raises

TonalAssessmentResult(
    tone_level: float,
    masking_noise_level: float,
    centre_frequency: float,
    critical_bandwidth: float,
    audibility: float,
    adjustment: float,
)

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

Attributes

TonalAssessmentResult.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

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

uncertainty_from_repeated_measurements(
    levels: Sequence[float] | np.ndarray,
) -> 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 (e.g. [50, 60, 70] dB gives 3.94 dB by Formulae (17)+(19) but 12.18 dB by Formula (20)).

Parameters

Returns: A RepeatedMeasurementResult.

Raises