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
dB
(Formula (C.3)), and the
tonal adjustment is the piecewise function for
,
for and
for
(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).
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 maps the ISO/PAS 20065 mean
audibility ΔL to Kt (0–6 dB).
Residual-noise correction (Clause 10.4).
(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). (Formula (2)) expanded by (95 %) or (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
Section titled “assess_tonal_audibility”assess_tonal_audibility( tone_level: float, masking_noise_level: float, center_frequency: float,) -> TonalAssessmentResultAssess 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
| 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.
assess_tonal_survey
Section titled “assess_tonal_survey”assess_tonal_survey( levels: NumericArrayLike, *, frequencies: NumericArrayLike,) -> TonalSurveyAssessmentWhich 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; 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
Section titled “critical_bandwidth”critical_bandwidth(center_frequency: float) -> floatCritical 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
Section titled “environmental_expanded_uncertainty”environmental_expanded_uncertainty( standard_uncertainty: float, *, coverage: float = 0.95,) -> floatExpanded uncertainty (Clause 4).
Coverage factor for 95 % or for 80 %.
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
Section titled “EnvironmentalMeasurementWarning”Warning for unreliable environmental-noise determinations.
gaussian_residual_level
Section titled “gaussian_residual_level”gaussian_residual_level(l50: float, *, l90: float) -> float
gaussian_residual_level(l50: float, *, l95: float) -> floatEstimate the residual equivalent level from percentiles (Annex I).
(Formula (I.1)) or, with L95,
(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
Section titled “RepeatedMeasurementResult”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 , dB (Formula (18)). |
standard_uncertainty |
Standard uncertainty uk by the primary route, Formulae (17)+(19): the sample standard deviation sk of the energy values mapped back to level, , in dB. |
approximate_uncertainty |
The Note 2 substitute (Formula (20)), , 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
Section titled “residual_correction_uncertainty”residual_correction_uncertainty( measured_level: float, residual_level: float, measured_uncertainty: float, residual_uncertainty: float,) -> floatUncertainty of the residual-corrected level (Formulae (F.7)–(F.9)).
With , the sensitivity coefficients are and , and .
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
Section titled “residual_sound_correction”residual_sound_correction( measured_level: float, residual_level: float,) -> ResidualCorrectionResultCorrect a measured level for residual sound (Formula (16)).
. 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
| Name | Description |
|---|---|
measured_level |
Measured level L' including residual, in dB. |
residual_level |
Residual (background) level Lres, in dB. |
Returns: A 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
Section titled “ResidualCorrectionResult”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
Section titled “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
Section titled “tonal_adjustment”tonal_adjustment(audibility: float) -> floatTonal adjustment Kt from the audibility (Formulae (C.4)–(C.6)).
for ,
for
and
for . 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
Section titled “tonal_adjustment_from_mean_audibility”tonal_adjustment_from_mean_audibility( mean_audibility: float, *, coarse: bool = False,) -> intTonal 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 ( → 0,
→ 3, → 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
Section titled “tonal_audibility”tonal_audibility( tone_level: float, masking_noise_level: float, center_frequency: float,) -> floatTonal audibility above the masking threshold (Formula (C.3)).
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
Section titled “TonalAssessmentResult”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()
Section titled “TonalAssessmentResult.plot()”TonalAssessmentResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the Kt(ΔLta) adjustment curve with this tone marked.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
TonalSurveyAssessment
Section titled “TonalSurveyAssessment”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.
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
Section titled “TonalSurveyAssessment.level_differences”property
Each band less the louder of its two neighbours, in dB; NaN at the ends.
TonalSurveyAssessment.min_level_differences
Section titled “TonalSurveyAssessment.min_level_differences”property
The level difference Annex K asks of each band, in dB.
TonalSurveyAssessment.plot()
Section titled “TonalSurveyAssessment.plot()”TonalSurveyAssessment.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesDraw 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
Section titled “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
Section titled “TonalSurveyAssessment.tone_frequencies”property
The centres of the bands that hold a prominent tone, in Hz.
uncertainty_from_repeated_measurements
Section titled “uncertainty_from_repeated_measurements”uncertainty_from_repeated_measurements( levels: NumericArrayLike,) -> RepeatedMeasurementResultEnergy mean and its uncertainty from repeated levels (Formulae (17)–(20)).
(Formula (18)).
The standard
uncertainty follows the primary §10.5 route: the sample standard
deviation sk of the energy values
(Formula (17))
propagated back to level,
(Formula (19)). The Note 2 level-domain approximation
(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
| Name | Description |
|---|---|
levels |
The repeated measured levels Li, in dB (at least two). |
Returns: A 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. |