building.building_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.insulation, phonometry.lab_insulation, phonometry.building_prediction). 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 = k·u (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 ± U (Formula 3) uses the two-sided factor.

Combination. Uncorrelated quadrature uc = sqrt(Σ u_i²) (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

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

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.

BandUncertainty

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

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

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

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

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

combine_uncertainties

combine_uncertainties(*components: float) -> float

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

uc = sqrt(Σ u_i²) for uncorrelated contributions with unit sensitivity coefficients, also the model/reality combination of Formula (A.2).

Parameters

Name	Description
components	Standard-uncertainty contributions, in dB (non-negative).

Raises

Exception	When
ValueError	No components, or a negative component.

coverage_factor

coverage_factor(confidence: float = 0.95, one_sided: bool = False) -> float

Deprecated alias of insulation_coverage_factor.

COVERAGE_FACTORS

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}

expanded_uncertainty

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

Deprecated alias of insulation_expanded_uncertainty.

insulation_coverage_factor

insulation_coverage_factor(
    confidence: float = 0.95,
    one_sided: bool = False,
) -> float

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

Parameters

Name	Description
confidence	Confidence level 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	Confidence level not tabulated in Table 8.

insulation_expanded_uncertainty

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

Return the expanded uncertainty U = k·u (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

Name	Description
u	Standard uncertainty u, in dB (must be non-negative).
coverage	Confidence level 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 confidence level.

maximum_repeatability_standard_deviation

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

prediction_input_uncertainty(
    sigma_reproducibility: float,
    sigma_product: float,
    n: int,
) -> float

Return the prediction input uncertainty u_input (Formula A.1).

u_input = sqrt( (σR² + σ_product²)/n + σ_product² ) 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 (n >= 1).

Raises

Exception	When
ValueError	Non-positive n or a negative standard deviation.

reduce_by_independent_measurements

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

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

u_reduced = u / sqrt(m): 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 (m >= 1).

Raises

Exception	When
ValueError	Non-positive m or negative u.

satisfies_lower_requirement

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 value − U > 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

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 value + U < 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

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.

Note

For the impact descriptors ("ln_w"/"ln_w+ci", Table 5) the situation-A value is an estimate: no reproducibility results are available for impact sound insulation (Table 5, footnote a).

Parameters

Name	Description
quantity	Rating descriptor (see above).
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.

single_number_uncertainty_uncorrelated

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

u(Rw+C) = sqrt( Σ_i (w_i · u_i)² ) with energy weights w_i = 10^((L_i − R_i)/10) / Σ_j 10^((L_j − R_j)/10) 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 L_i − R_i (reference-spectrum level minus measured band value), in dB.

Raises

Exception	When
ValueError	Mismatched lengths, empty input, or negative u_i.

uncertain_value

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 (value ± U) 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).
situation	Measurement situation "A", "B" or "C" (Clause 5.2).
coverage	Confidence level as a fraction.
one_sided	Use the one-sided coverage factor.
upper_limit	Use the σR95 upper limit (airborne, situation A).

UncertainValue

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

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	U = k·u, in dB.
confidence	Confidence level as a fraction (e.g. 0.95).
one_sided	True for a one-sided interval (conformity checks).

UncertainValue.lower

property

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

UncertainValue.upper

property

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