Ir al contenido

building.measurement.uncertainty

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.

Measurement uncertainty in building acoustics (ISO 12999-1:2020).

This module supplies the measurement uncertainty of the sound-insulation quantities produced by the field/lab/prediction modules (phonometry.building.measurement.insulation, phonometry.building.measurement.laboratory_insulation, phonometry.building.prediction.simplified_model). ISO 12999-1 does not re-measure anything; it tabulates standard uncertainties u derived from inter-laboratory tests (ISO 5725) and prescribes how to expand and combine them.

Three measurement situations (Clause 5.2) fix which standard deviation is the standard uncertainty u:

  • A: laboratory characterisation (ISO 10140); u = reproducibility σR.
  • B: same location, different teams; u = in-situ σsitu.
  • C: same location, same operator/equipment repeated; u = repeatability σr.

Tabulated standard uncertainties (one-third-octave and single-number):

  • Airborne R/R'/Dn/DnT: Table 2 (bands) and Table 3 (ratings).
  • Impact Ln/L'n/L'nT: Table 4 (bands, situations B/C only) and Table 5 (ratings). ISO 12999-1:2020 Table 4 has no 500 Hz band (the 2014 edition did).
  • Reduction of impact noise by floor coverings ΔL/ΔLw: Table 6 (bands) and Table 7 (rating), situation A only.
  • Upper 95 % limit of airborne reproducibility σR95: Annex D Tables D.1/D.2 (situation A; informative). In ISO 12999-1:2014 these were extra columns of Tables 2/3.
  • Maximum repeatability standard deviation for lab self-verification: Table 1.

Expansion (Clause 8). (Formula 2) with the coverage factor k of Table 8 (a minimum of is enforced). Declaring conformity with a requirement uses the one-sided factor (Formulae 4/5); reporting a two-sided interval (Formula 3) uses the two-sided factor.

Combination. Uncorrelated quadrature (Formula C.2); prediction input uncertainty (Formula A.1); model/reality combination (Formula A.2); reduction by m independent measurements (Formula A.7); and the uncorrelated single-number combination of Annex B (Formula B.2).

Clause/table numbers refer to ISO 12999-1:2020(E).

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

assess_requirement_conformity(
rating: float,
expanded_uncertainty_db: float,
required_rating: float,
*,
bound: Literal['minimum', 'maximum'],
) -> RequirementConformity

Does a measured value meet a requirement beyond its uncertainty? (Clause 8).

The expanded uncertainty is worked with the one-sided coverage factor of Table 8 (insulation_coverage_factor with one_sided=True) and then taken off the best estimate for a minimum, (Formula (5)), or added to it for a maximum, (Formula (4)): an apparent sound reduction index R'w provably above its minimum, a normalized impact level L'n,w provably below its maximum.

Parameters

Name Description
rating The best estimate , in dB.
expanded_uncertainty_db , one-sided, in dB.
required_rating , in dB.
bound "minimum" (Formula (5)) or "maximum" (Formula (4)).

Returns: The verdict, as a RequirementConformity.

Raises

Exception When
TypeError For a rating, expanded_uncertainty_db or required_rating that is not one number, or a bound that is not a text.
ValueError For an unknown bound, a value that is not finite or a negative uncertainty.
band_uncertainty(
measurand: Literal['airborne', 'impact', 'impact_reduction'],
situation: Literal['A', 'B', 'C'],
*,
upper_limit: bool = False,
) -> BandUncertainty

The one-third-octave standard uncertainties for a measurand.

Airborne (Table 2) offers situations A/B/C; impact (Table 4) only B/C; the reduction ΔL (Table 6) only A. upper_limit=True selects the σR95 upper limit for airborne, situation A (Annex D Table D.1).

Parameters

Name Description
measurand "airborne", "impact" or "impact_reduction".
situation Measurement situation "A", "B" or "C" (Clause 5.2).
upper_limit Select the σR95 upper limit (airborne, situation A).

Raises

Exception When
ValueError Unknown measurand, or a situation not tabulated for it.
TypeError if measurand or situation is not a text.
BandUncertainty(
measurand: Literal['airborne', 'impact', 'impact_reduction'],
situation: Literal['A', 'B', 'C'],
frequencies: tuple[float, ...],
uncertainties: tuple[float, ...],
*,
upper_limit: bool = False,
)

One-third-octave-band standard uncertainties (ISO 12999-1 Tables 2/4/6/D.1).

Attributes

Name Description
measurand "airborne", "impact" or "impact_reduction".
situation Measurement situation "A", "B" or "C" (Clause 5.2).
frequencies Band centre frequencies, in Hz.
uncertainties Standard uncertainty u per band, in dB.
upper_limit True for the σR95 upper limit (Annex D Table D.1).
BandUncertainty.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the per-band standard uncertainty spectrum.

Requires matplotlib (the [plot] extra); returns the Axes.

Parameters

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

Constant (mapping).

COVERAGE_FACTORS = {(0.68, False): 1.0, (0.8, False): 1.28, (0.9, False): 1.65, (0.95, False): 1.96, (0.99, False): 2.58, (0.999, False): 3.29, (0.84, True): 1.0, (0.9, True): 1.28, (0.95, True): 1.65, (0.975, True): 1.96, (0.995, True): 2.58, (0.9995, True): 3.29}
insulation_coverage_factor(
coverage: float = 0.95,
*,
one_sided: bool = False,
) -> float

The coverage factor k for a coverage probability (Table 8).

Parameters

Name Description
coverage Coverage probability as a fraction. Two-sided values are 0.68, 0.80, 0.90, 0.95, 0.99, 0.999; one-sided values are 0.84, 0.90, 0.95, 0.975, 0.995, 0.9995.
one_sided Use the one-sided column (conformity checks, Formulae 4/5).

Raises

Exception When
ValueError Coverage probability not tabulated in Table 8.
TypeError if coverage is not a single number.
insulation_expanded_uncertainty(
u: float,
coverage: float = 0.95,
*,
one_sided: bool = False,
) -> float

The expanded uncertainty (Formula 2, Clause 8).

The coverage factor k is taken from Table 8 for the requested coverage probability; a minimum of is enforced (Clause 8).

Parameters

Name Description
u Standard uncertainty u, in dB (must be non-negative).
coverage Coverage probability as a fraction (see insulation_coverage_factor).
one_sided Use the one-sided coverage factor (conformity checks).

Raises

Exception When
ValueError Negative u or an untabulated coverage probability.
TypeError if u is not a single number.
max_repeatability_standard_deviation() -> BandUncertainty

Table 1: the maximum repeatability standard deviation per band (Clause 5.8).

A laboratory verifies its own procedure when the repeatability standard deviation of nx repeated measurements stays below these values.

prediction_input_uncertainty(
sigma_reproducibility: float,
sigma_product: float,
n: int | np.integer[Any],
) -> float

The prediction input uncertainty u_input (Formula A.1).

combines the reproducibility standard deviation with the product-homogeneity scatter over n measurements of nominally identical specimens.

Parameters

Name Description
sigma_reproducibility Reproducibility standard deviation σR, in dB.
sigma_product Product-homogeneity standard deviation σ_product, in dB.
n Number of measurements of the product ().

Raises

Exception When
ValueError A non-integer or non-positive n, or a negative standard deviation.
TypeError if sigma_product or sigma_reproducibility is not a single number, or n is a flag, a text or an array where a count goes.
reduce_by_independent_measurements(
u: float,
m: int | np.integer[Any],
) -> float

Reduce a standard uncertainty by m independent measurements (Formula A.7).

: measurements by different persons with different equipment lower the in-situ uncertainty.

Parameters

Name Description
u Standard uncertainty of a single measurement, in dB (non-negative).
m Number of independent measurements ().

Raises

Exception When
ValueError an m that is not a whole number from 1, or a negative u.
TypeError if u is not a single number, or m is a flag, a text or an array where a count goes.
RequirementConformity(
rating: float,
expanded_uncertainty_db: float,
required_rating: float,
*,
bound: Literal['minimum', 'maximum'],
)

A measured value against a requirement, with its uncertainty (Clause 8).

ISO 12999-1:2020 Clause 8 declares conformity only when the whole one-sided interval clears the requirement: for a minimum (Formula (5)) and for a maximum (Formula (4)). Both are strict, so a value that clears the requirement by exactly does not conform. The margin and the verdict are read from the three values and the side, so they are not fields: a record cannot be built to conform with a value the clause refuses.

Attributes

Name Description
rating The best estimate , in dB.
expanded_uncertainty_db , worked with the one-sided coverage factor, in dB.
required_rating , in dB.
bound "minimum" when the requirement is a value to exceed (an apparent sound reduction index R'w) or "maximum" when it is one to stay under (a normalized impact level L'n,w).

property

How far the uncertain interval clears the requirement, in dB.

for a minimum and for a maximum: positive when the value conforms. Settled, so a value exactly from the requirement in decimal gives a margin of zero whichever way the last bits of the subtraction fall.

property

The verdict: the margin is positive, Formula (5) or (4) holds.

single_number_uncertainty(
quantity: Literal['r_w', 'r_w+c_50_3150', 'r_w+c_50_5000', 'r_w+c_100_3150', 'r_w+c_100_5000', 'r_w+ctr_50_3150', 'r_w+ctr_50_5000', 'r_w+ctr_100_3150', 'r_w+ctr_100_5000', 'ln_w', 'ln_w+ci', 'delta_lw', 'rprime_w', 'r_prime_w', 'dn_w', 'dnw', 'dnt_w', 'dntw', 'lprime_n_w', 'lnprime_w', 'lnt_w', 'lprime_nt_w', 'delta_l_w'],
situation: Literal['A', 'B', 'C'],
*,
upper_limit: bool = False,
) -> float

The tabulated single-number standard uncertainty u, in dB.

Descriptors, written as listed, with aliases, cover the ISO 717 ratings: "r_w" (also rprime_w/dn_w/dnt_w) and its spectrum-adaptation variants "r_w+c_50_5000" etc. (Table 3); "ln_w"/"ln_w+ci" (Table 5); "delta_lw" (Table 7). upper_limit=True selects the situation-A σR95 (Annex D Table D.2), defined for airborne descriptors only.

Parameters

Name Description
quantity Rating descriptor (see above). One of "r_w", "r_w+c_50_3150", "r_w+c_50_5000", "r_w+c_100_3150", "r_w+c_100_5000", "r_w+ctr_50_3150", "r_w+ctr_50_5000", "r_w+ctr_100_3150", "r_w+ctr_100_5000", "ln_w", "ln_w+ci", "delta_lw", "rprime_w", "r_prime_w", "dn_w", "dnw", "dnt_w", "dntw", "lprime_n_w", "lnprime_w", "lnt_w", "lprime_nt_w" or "delta_l_w".
situation Measurement situation "A", "B" or "C" (Clause 5.2).
upper_limit Select the σR95 upper limit (airborne, situation A).

Raises

Exception When
ValueError Unknown descriptor, an untabulated situation, or an upper_limit request outside airborne/situation A.
TypeError if quantity or situation is not a text.
single_number_uncertainty_uncorrelated(
band_uncertainties: NumericArrayLike,
reference_differences: NumericArrayLike,
) -> float

Uncorrelated single-number uncertainty from band uncertainties (Formula B.2).

with energy weights

derived from the reference spectrum. This is the no-correlation estimate of Annex B; the fully correlated bound (Formulae B.3-B.6) instead re-runs the ISO 717 rating and is not reproduced here.

Parameters

Name Description
band_uncertainties Per-band standard uncertainties u_i, in dB.
reference_differences Per-band (reference-spectrum level minus measured band value), in dB.

Raises

Exception When
ValueError Mismatched shapes, empty input, or negative u_i.
TypeError if band_uncertainties or reference_differences holds a text or a value that is not a real number.
uncertain_value(
value: float,
quantity: Literal['r_w', 'r_w+c_50_3150', 'r_w+c_50_5000', 'r_w+c_100_3150', 'r_w+c_100_5000', 'r_w+ctr_50_3150', 'r_w+ctr_50_5000', 'r_w+ctr_100_3150', 'r_w+ctr_100_5000', 'ln_w', 'ln_w+ci', 'delta_lw', 'rprime_w', 'r_prime_w', 'dn_w', 'dnw', 'dnt_w', 'dntw', 'lprime_n_w', 'lnprime_w', 'lnt_w', 'lprime_nt_w', 'delta_l_w'],
situation: Literal['A', 'B', 'C'],
*,
coverage: float = 0.95,
one_sided: bool = False,
upper_limit: bool = False,
) -> UncertainValue

Attach the ISO 12999-1 expanded uncertainty to a single-number rating.

Convenience wrapper combining single_number_uncertainty, insulation_coverage_factor and insulation_expanded_uncertainty into an UncertainValue () without modifying the rating dataclasses. For conformity checks pass one_sided=True and read UncertainValue.lower / UncertainValue.upper (Formulae 4/5).

Parameters

Name Description
value Best estimate y (e.g. Rw in dB).
quantity Rating descriptor (see single_number_uncertainty). One of "r_w", "r_w+c_50_3150", "r_w+c_50_5000", "r_w+c_100_3150", "r_w+c_100_5000", "r_w+ctr_50_3150", "r_w+ctr_50_5000", "r_w+ctr_100_3150", "r_w+ctr_100_5000", "ln_w", "ln_w+ci", "delta_lw", "rprime_w", "r_prime_w", "dn_w", "dnw", "dnt_w", "dntw", "lprime_n_w", "lnprime_w", "lnt_w", "lprime_nt_w" or "delta_l_w".
situation Measurement situation "A", "B" or "C" (Clause 5.2).
coverage Coverage probability as a fraction.
one_sided Use the one-sided coverage factor.
upper_limit Use the σR95 upper limit (airborne, situation A).

Raises

Exception When
TypeError if quantity or situation is not a text.
UncertainValue(
value: float,
standard_uncertainty: float,
coverage_factor: float,
expanded_uncertainty: float,
coverage: float,
*,
one_sided: bool,
)

A best estimate with its ISO 12999-1 expanded uncertainty (Clause 8).

Attributes

Name Description
value Best estimate y (e.g. a weighted rating), in dB.
standard_uncertainty Standard uncertainty u, in dB.
coverage_factor Coverage factor k (Table 8).
expanded_uncertainty , in dB.
coverage The coverage probability of expanded_uncertainty, as a fraction (e.g. 0.95).
one_sided True for a one-sided interval (conformity checks).

property

Lower interval bound (Formula 3/5).

property

Upper interval bound (Formula 3/4).