building.measurement.uncertainty

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.lab_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). $U=ku$ (Formula 2) with the coverage factor k of Table 8 (a minimum of $k=1$ is enforced). Declaring conformity with a requirement uses the one-sided factor (Formulae 4/5); reporting a two-sided interval $Y=y\pm U$ (Formula 3) uses the two-sided factor.

Combination. Uncorrelated quadrature $u_{\mathrm{c}}=\sqrt{\sum u_i^2}$ (Formula C.2); prediction input uncertainty (Formula A.1); model/reality combination (Formula A.2); reduction by m independent measurements $u/\sqrt{m}$ (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.

band_uncertainty(
    measurand: Measurand,
    situation: Situation,
    *,
    upper_limit: bool = False,
) -> BandUncertainty

Return 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

Raises

BandUncertainty(
    measurand: str,
    situation: str,
    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

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

Plot the per-band standard uncertainty spectrum.

Requires matplotlib (pip install phonometry[plot]); returns the Axes.

BandUncertainty.to_arrays() -> tuple[np.ndarray, np.ndarray]

Return (frequencies, uncertainties) as float numpy.ndarray.

combine_uncertainties(*components: float) -> float

Combine independent standard uncertainties in quadrature (Formula C.2).

$u_{\mathrm{c}}=\sqrt{\sum u_i^2}$ for uncorrelated contributions with unit sensitivity coefficients, also the model/reality combination of Formula (A.2).

Parameters

Raises

Constant (mappingproxy).

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(
    confidence: float = 0.95,
    one_sided: bool = False,
) -> float

Return the coverage factor k for a confidence level (Table 8).

Parameters

Raises

insulation_expanded_uncertainty(
    u: float,
    coverage: float = 0.95,
    one_sided: bool = False,
) -> float

Return the expanded uncertainty $U=ku$ (Formula 2, Clause 8).

The coverage factor k is taken from Table 8 for the requested confidence level; a minimum of $k=1$ is enforced (Clause 8).

Parameters

Raises

maximum_repeatability_standard_deviation() -> BandUncertainty

Return 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,
) -> float

Return 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

Raises

reduce_by_independent_measurements(u: float, m: int) -> float

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

$u_{\mathrm{reduced}}=u/\sqrt{m}$: measurements by different persons with different equipment lower the in-situ uncertainty.

Parameters

Raises

satisfies_lower_requirement(
    value: float,
    expanded_uncertainty_value: float,
    requirement: float,
) -> bool

Test a minimum requirement with one-sided uncertainty (Formula 5).

Returns True when $\text{value}-U>\text{requirement}$, e.g. an apparent sound reduction index R'w provably exceeds a minimum. U should be computed with the one-sided coverage factor.

satisfies_upper_requirement(
    value: float,
    expanded_uncertainty_value: float,
    requirement: float,
) -> bool

Test a maximum requirement with one-sided uncertainty (Formula 4).

Returns True when $\text{value}+U<\text{requirement}$, e.g. a normalized impact level L'n,w provably stays below a maximum. U should be computed with the one-sided coverage factor.

single_number_uncertainty(
    quantity: str,
    situation: Situation,
    *,
    upper_limit: bool = False,
) -> float

Return the tabulated single-number standard uncertainty u, in dB.

Descriptors (case-insensitive, 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

Raises

single_number_uncertainty_uncorrelated(
    band_uncertainties: Sequence[float] | np.ndarray,
    reference_differences: Sequence[float] | np.ndarray,
) -> 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

Raises

uncertain_value(
    value: float,
    quantity: str,
    situation: Situation,
    *,
    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 ($y\pm U$) without modifying the rating dataclasses. For conformity checks pass one_sided=True and read UncertainValue.lower / UncertainValue.upper (Formulae 4/5).

Parameters

UncertainValue(
    value: float,
    standard_uncertainty: float,
    coverage_factor: float,
    expanded_uncertainty: float,
    confidence: float,
    one_sided: bool,
)

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

Attributes

property

Lower interval bound $y-U$ (Formula 3/5).

property

Upper interval bound $y+U$ (Formula 3/4).