Ir al contenido

environment.assessment.measurement

La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.

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(
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 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(
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; 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(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(
standard_uncertainty: float,
*,
coverage: float = 0.95,
) -> float

Expanded 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.

Warning for unreliable environmental-noise determinations.

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).

(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(
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(
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 , 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(
measured_level: float,
residual_level: float,
) -> ResidualCorrectionResult

Correct 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(
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).

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(audibility: float) -> float

Tonal 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(
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 ( → 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(
tone_level: float,
masking_noise_level: float,
center_frequency: float,
) -> float

Tonal 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(
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(
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(
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).

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(
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.

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.

property

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

uncertainty_from_repeated_measurements(
levels: NumericArrayLike,
) -> RepeatedMeasurementResult

Energy 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.