building.measurement.ratings

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.

Single-number weighted ratings of sound insulation and their spectrum adaptation terms (ISO 717-1 airborne, ISO 717-2 impact).

ISO 717 rates a curve, not a room. Whatever produced the band values (a field measurement to ISO 16283, a laboratory measurement to ISO 10140, a prediction to ISO 12354), both parts of ISO 717 reduce them to a single number by the same reference-curve method: one shift search, one pair of deviation bounds, one rounding rule, run against the airborne reference curve of ISO 717-1 or the impact reference curve of ISO 717-2, whose only structural difference is the sign an unfavourable deviation has. That shared machinery, with the Table 3 reference curves and the Table 4 / Table B.1 spectra it reads, is the subject of this module.

Weighted rating (ISO 717-1). The reference-curve method of Clause 4.4 shifts the reference curve of Table 3 in 1 dB steps towards the measured curve until the sum of unfavourable deviations (measured below the shifted reference) is as large as possible but not more than 32,0 dB for the 16 one-third-octave bands (100 Hz to 3150 Hz) or 10,0 dB for the 5 octave bands (125 Hz to 2000 Hz). The weighted rating (Rw, R'w, Dn,w, DnT,w …) is the shifted reference read at 500 Hz. The spectrum adaptation terms are $C = X_{A 1} - X_{w}$ and $C_{tr} = X_{A 2} - X_{w}$ with $X_{A j} = - 10 lo g_{10} \sum 1 0^{(L_{ij} - X_{i}) /10}$ rounded to an integer, using the A-weighted spectra No. 1 (pink noise, C) and No. 2 (urban traffic, Ctr) of Table 4 (Clause 4.5, Formula (1) and (2)). Input levels are reduced to one decimal place before use (Clause 4.4, footnote 1). The reference values, spectra and shifting rule are identical in the 2013 and 2020 editions of ISO 717-1.

Enlarged frequency ranges (ISO 717-1 Annex B; ISO 717-2 A.2.1 NOTE). When measurements cover an enlarged range, additional adaptation terms are stated with the range as a subscript: C50-3150, C50-5000, C100-5000 (and the Ctr counterparts) with the Table B.1 spectra, and CI,50-2500 for impact. weighted_rating_extended and weighted_impact_rating_extended compute them alongside the core rating. Both accept one_decimal=True for the “1/10 dB for the expression of uncertainty” variant of Clauses 4.4/4.5 (reference-curve shift in 0,1 dB steps and one-decimal reductions), which ISO 12999-1:2020 Annex B requires when stating the uncertainty of single-number values.

Weighted impact rating (ISO 717-2). The reference-curve method of Clause 4.3 shifts the Table 3 impact reference curve towards the measured curve until the sum of unfavourable deviations (here where the measurement exceeds the reference, the sign opposite to airborne) is as large as possible but not more than 32,0 dB (16 one-third-octave bands) or 10,0 dB (5 octave bands). The rating (Ln,w, L'n,w, L'nT,w) is the shifted reference read at 500 Hz, reduced by a further 5 dB for octave bands (Clause 4.3.2). The spectrum adaptation term $C_{I} = L_{n, sum} - 15 - L_{n, w}$ uses the energetic sum Ln,sum over 100 Hz to 2500 Hz (one-third octave) or 125 Hz to 2000 Hz (octave), rounded to an integer (Clause A.2.1, Formulae (A.1) to (A.3)). The Table 3 reference values, the shifting rule and CI are identical in the 2013 and 2020 editions of ISO 717-2 (the 2020 edition only adds Annex D for the rubber-ball heavy/soft impactor, out of scope here).

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

ExtendedImpactRatingResult

ExtendedImpactRatingResult(
    rating: float,
    ci: float,
    ci_50_2500: float | None,
    core: ImpactRatingResult,
    band_centers: np.ndarray | None = None,
    measured: np.ndarray | None = None,
)

Weighted impact rating with CI,50-2500 (ISO 717-2:2020 A.2.1 NOTE).

Values are integers unless computed with one_decimal=True.

Attributes

Name	Description
`rating`	Weighted impact rating (`Ln,w`, …) from the core 100-3150 Hz bands, in dB.
`ci`	Core spectrum adaptation term `CI` (100-2500 Hz), in dB.
`ci_50_2500`	Enlarged-range term `CI,50-2500`, in dB, or `None` when the supplied bands do not cover 50-2500 Hz.
`core`	The integer-mode `ImpactRatingResult` of the core bands (independent of `one_decimal`).
`band_centers`	Band centre frequencies of the full (enlarged-range) measured curve, in Hz. Defaults to `None` for backward-compatible construction.
`measured`	The measured impact levels over the full enlarged range (after the one-decimal reduction of Clause 4.3), in dB. Defaults to `None`.

ExtendedImpactRatingResult.plot()

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

Plot the enlarged-range curve vs the shifted reference (ISO 717-2).

The measured curve is drawn over the full enlarged range, the ISO 717-2 reference curve (after the final shift) over the 16 core bands 100-3150 Hz, with the unfavourable deviations (measurement above the reference) shaded on the core bands and the bands outside the core range marked as the enlarged range; the title carries the impact rating with CI and, when covered, CI,50-2500. Requires matplotlib (pip install phonometry[plot]); returns the Axes.

ExtendedWeightedRatingResult

ExtendedWeightedRatingResult(
    rating: float,
    c: float,
    ctr: float,
    c_50_3150: float | None,
    c_50_5000: float | None,
    c_100_5000: float | None,
    ctr_50_3150: float | None,
    ctr_50_5000: float | None,
    ctr_100_5000: float | None,
    core: WeightedRatingResult,
    band_centers: np.ndarray | None = None,
    measured: np.ndarray | None = None,
)

Weighted rating with the enlarged-range adaptation terms (ISO 717-1 Annex B).

All values are integers unless the result was computed with one_decimal=True (the “1/10 dB for the expression of uncertainty” variant of Clauses 4.4/4.5), in which case they carry one decimal place. An extended term is None when the supplied bands do not cover its frequency range.

Attributes

Name	Description
`rating`	Weighted rating (`Rw`, `R'w`, …) from the core 100-3150 Hz bands, in dB.
`c`	Core spectrum adaptation term `C` (100-3150 Hz), in dB.
`ctr`	Core spectrum adaptation term `Ctr` (100-3150 Hz), in dB.
`c_50_3150`	`C50-3150`, in dB, or `None`.
`c_50_5000`	`C50-5000`, in dB, or `None`.
`c_100_5000`	`C100-5000`, in dB, or `None`.
`ctr_50_3150`	`Ctr,50-3150`, in dB, or `None`.
`ctr_50_5000`	`Ctr,50-5000`, in dB, or `None`.
`ctr_100_5000`	`Ctr,100-5000`, in dB, or `None`.
`core`	The integer-mode `WeightedRatingResult` of the core bands (independent of `one_decimal`), for plotting and the unfavourable-deviation sum.
`band_centers`	Band centre frequencies of the full (enlarged-range) measured curve, in Hz. Defaults to `None` for backward-compatible construction.
`measured`	The measured band quantities over the full enlarged range (after the one-decimal reduction of Clause 4.4), in dB. Defaults to `None`.

ExtendedWeightedRatingResult.plot()

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

Plot the enlarged-range curve vs the shifted reference (Annex B).

The measured curve is drawn over the full enlarged range, the ISO 717-1 reference curve (after the final shift) over the 16 core bands 100-3150 Hz, with the unfavourable deviations shaded on the core bands and the bands outside the core range marked as the enlarged range; the title carries Rw (C; Ctr) and every Annex B adaptation term the input covered. Requires matplotlib (pip install phonometry[plot]); returns the Axes.

impact_improvement_adaptation_term

impact_improvement_adaptation_term(
    delta_l: Sequence[float] | np.ndarray,
) -> int

Adaptation term CI,Δ of a floor covering (ISO 717-2:2020 A.2.2).

$C_{I, Δ} = C_{I, r, 0} - C_{I, r}$ (Formula (A.4)) with $C_{I, r, 0} = - 11$ dB (the bare Table 4 reference floor) and CI,r the ISO 717-2 spectrum adaptation term of the reference floor with the covering under test, $L_{n, r} = L_{n, r, 0} - Δ L$ (Formula (1)). Together with weighted_impact_improvement it yields the single-number reduction for a flat spectrum, $Δ L_{lin} = Δ L_{w} + C_{I, Δ}$ (Formula (A.5)). ISO 16251-1 Clause 8 e) requires this term in the statement of results.

Parameters

Name	Description
`delta_l`	The reduction of impact sound pressure level `ΔL` per band, in dB; 16 one-third-octave values from 100 Hz to 3150 Hz.

Returns: The spectrum adaptation term CI,Δ, in dB (integer).

Raises

Exception	When
ValueError	If `delta_l` is not 16 one-third-octave values, or is non-finite.

ImpactRatingResult

ImpactRatingResult(
    rating: int,
    ci: int,
    unfavourable_sum: float,
    band_centers: np.ndarray | None = None,
    measured: np.ndarray | None = None,
    shifted_reference: np.ndarray | None = None,
    quantity: str = 'impact',
)

Single-number weighted impact rating and CI (ISO 717-2).

Attributes

Name	Description
`rating`	Weighted impact rating (`Ln,w`, `L'n,w`, `L'nT,w`), the shifted reference read at 500 Hz, in dB (Clause 4.3; octave-band ratings include the -5 dB reduction of Clause 4.3.2). Integer.
`ci`	Spectrum adaptation term `CI` (Clause A.2.1), in dB. Integer.
`unfavourable_sum`	Sum of unfavourable deviations at the final shift, in dB (Clause 4.3); at most 32,0 (16 bands) or 10,0 (5 bands).
`band_centers`	Band centre frequencies of the measured curve, in Hz. Defaults to `None` for backward-compatible construction.
`measured`	The measured impact levels used for the rating (after the one-decimal reduction of Clause 4.3.1), in dB. Defaults to `None`.
`shifted_reference`	Table 3 impact reference curve after the final shift, in dB. Defaults to `None`.
`quantity`	Always `"impact"` (ISO 717-2), selecting the impact labels of the ISO 717 Annex C report.

ImpactRatingResult.plot()

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

Plot the measured curve vs the shifted reference (ISO 717-2).

Unfavourable deviations (measurement above the reference, the sign opposite to airborne) are shaded and Ln,w (CI) annotated. Requires matplotlib (pip install phonometry[plot]); returns the Axes.

ImpactRatingResult.report()

ImpactRatingResult.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = 'en',
    symbol: str | None = None,
) -> str

Render an ISO 717-2 impact-insulation fiche to a PDF.

Writes a one-page accredited-laboratory report for impact sound: the standard-basis line, an optional metadata header block, the band table beside the measured-versus-shifted-reference plot (the result’s own plot), the boxed Ln,w (CI) result, an optional verdict row and a footer with the fixed disclaimer.

Parameters

Name	Description
`path`	Destination path of the PDF file.
`metadata`	Optional `ReportMetadata`; `None` produces a prediction fiche (body, result and disclaimer only).
`engine`	Rendering back end; only `"reportlab"` is supported.
`verbose`	When `True`, the table uses the ISO 717 Annex C columns (frequency, measured value, shifted reference, unfavourable deviation) instead of the two-column `f \| value` table.
`language`	Fiche language: `"en"` (default, English) or `"es"` (Spanish, with a comma decimal separator).
`symbol`	The reported single-number quantity, as plain text: `"Ln,w"` (the default when `None`), `"L'n,w"` or `"L'nT,w"` per ISO 717-2 Table 1, so a field measurement is not mislabelled with the laboratory descriptor.

Returns: The written path as a str.

Raises

Exception	When
ValueError	If `engine` is not `"reportlab"`, `symbol` is not a valid quantity-symbol shape, or the result was built without the per-band data (`band_centers`, `measured`, `shifted_reference`).
ImportError	If reportlab is not installed (`pip install phonometry[report]`), or matplotlib is missing for the embedded figure (`pip install phonometry[plot]`).

weighted_impact_improvement

weighted_impact_improvement(delta_l: Sequence[float] | np.ndarray) -> int

Weighted reduction of impact level ΔLw (ISO 717-2:2020 §5).

Relates a measured improvement spectrum ΔL to the heavyweight reference floor of Table 4: the reference level with the covering is $L_{n, r} = L_{n, r, 0} - Δ L$ (Formula (1)) and the weighted improvement is $Δ L_{w} = L_{n, r, 0, w} - L_{n, r, w} = 78 - L_{n, r, w}$ (Formula (2)), where Ln,r,w is the ISO 717-2 weighted rating of Ln,r from weighted_impact_rating.

Parameters

Name	Description
`delta_l`	The reduction of impact sound pressure level `ΔL` per band, in dB; 16 one-third-octave values from 100 Hz to 3150 Hz (e.g. from a floor-covering measurement to ISO 10140-3 or ISO 16251-1).

Returns: The weighted reduction ΔLw, in dB (rounded, per ISO 717-2).

Raises

Exception	When
ValueError	If `delta_l` is not 16 one-third-octave values, or is non-finite.

weighted_impact_rating

weighted_impact_rating(
    values_by_band: Sequence[float] | np.ndarray,
    bands: str | None = None,
) -> ImpactRatingResult

Single-number weighted impact rating and CI per ISO 717-2.

Applies the reference-curve method of Clause 4.3: the Table 3 impact reference curve is shifted in 1 dB steps towards the measured curve until the sum of unfavourable deviations is as large as possible but not more than 32,0 dB (16 one-third-octave bands, 100 Hz to 3150 Hz) or 10,0 dB (5 octave bands, 125 Hz to 2000 Hz). For impact sound an unfavourable deviation occurs where the measurement exceeds the reference (the sign opposite to ISO 717-1 airborne). The rating is the shifted reference read at 500 Hz; for octave bands it is then reduced by 5 dB (Clause 4.3.2). The spectrum adaptation term CI follows Clause A.2.1. Input values are first reduced to one decimal place (Clause 4.3.1, footnote 1).

The shift search reuses the verified engine of weighted_rating on the negated curves: minimising $\sum max (0, measured - (ref + k))$ over k equals maximising $\sum max (0, (- ref) + (- k) - (- measured))$ , the airborne problem, so no separate search is duplicated.

Parameters

Name	Description
`values_by_band`	Measured impact levels (`Ln`, `L'n`, `L'nT`) in dB. 16 values are read as one-third-octave bands, 5 values as octave bands.
`bands`	`"third-octave"`, `"octave"` or `None` to infer the band set from the number of values.

Returns: ImpactRatingResult with rating, ci and unfavourable_sum.

Raises

Exception	When
ValueError	If the number of values does not match the band set, or if any value is non-finite.

weighted_impact_rating_extended

weighted_impact_rating_extended(
    values_by_band: Sequence[float] | np.ndarray,
    frequencies: Sequence[float] | np.ndarray | None = None,
    *,
    one_decimal: bool = False,
) -> ExtendedImpactRatingResult

Weighted impact rating with CI,50-2500 (ISO 717-2:2020 A.2.1).

Computes the weighted impact rating from the core one-third-octave bands 100-3150 Hz (Clause 4.3) and, when the input covers 50-2500 Hz, the enlarged-range spectrum adaptation term CI,50-2500 of the A.2.1 NOTE: the energetic sum runs over 50-2500 Hz instead of 100-2500 Hz in Formula (A.1), $C_{I} = L_{n, sum} - 15 - L_{n, w}$ .

With one_decimal=True the reference-curve shift runs in 0,1 dB steps and the sums keep one decimal place (Clauses 4.3.1/4.4; e.g. the reference floor yields $L_{n, r, 0, w} = 77.6$ dB and $C_{I, r, 0} = - 10.3$ dB as printed in A.2.2).

Parameters

Name	Description
`values_by_band`	Measured impact levels (`Ln`, `L'n`, `L'nT`) in dB, one-third-octave bands.
`frequencies`	Band centre frequencies, in Hz (one per value). `None` assumes exactly the 16 core bands 100-3150 Hz.
`one_decimal`	Use the 0,1 dB shift and one-decimal reductions.

Returns: An ExtendedImpactRatingResult.

Raises

Exception	When
ValueError	If the input is not one-dimensional and finite, the band counts differ, or the core bands are missing.

weighted_rating

weighted_rating(
    values_by_band: Sequence[float] | np.ndarray,
    bands: str | None = None,
) -> WeightedRatingResult

Single-number weighted rating and C / Ctr per ISO 717-1.

Applies the reference-curve method of Clause 4.4: the Table 3 reference curve is shifted in 1 dB steps towards the measured curve until the sum of unfavourable deviations is as large as possible but not more than 32,0 dB (16 one-third-octave bands, 100 Hz to 3150 Hz) or 10,0 dB (5 octave bands, 125 Hz to 2000 Hz). The rating is the shifted reference read at 500 Hz. The spectrum adaptation terms C and Ctr follow Clause 4.5 with the Table 4 spectra No. 1 and No. 2. Input values are first reduced to one decimal place (Clause 4.4, footnote 1).

Parameters

Name	Description
`values_by_band`	Measured band quantities (`R`, `R'`, `Dn`, `DnT` …) in dB. 16 values are read as one-third-octave bands, 5 values as octave bands.
`bands`	`"third-octave"`, `"octave"` or `None` to infer the band set from the number of values.

Returns: WeightedRatingResult with rating, c, ctr and unfavourable_sum.

Raises

Exception	When
ValueError	If the number of values does not match the band set, or if any value is non-finite.

weighted_rating_extended

weighted_rating_extended(
    values_by_band: Sequence[float] | np.ndarray,
    frequencies: Sequence[float] | np.ndarray | None = None,
    *,
    one_decimal: bool = False,
) -> ExtendedWeightedRatingResult

Weighted rating with enlarged-range adaptation terms (ISO 717-1 An. B).

Computes the weighted rating from the core one-third-octave bands 100-3150 Hz (Clause 4.4) and, for every enlarged frequency range covered by the input, the additional spectrum adaptation terms of Annex B (C50-3150, C50-5000, C100-5000 and the Ctr counterparts) with the Table B.1 spectra: $C_{j} = X_{A j} - X_{w}$ where XAj sums over the bands of the enlarged range (Clause 4.5 with Annex B).

With one_decimal=True the reference-curve shift runs in 0,1 dB steps and every reduction keeps one decimal place; the variant Clauses 4.4/4.5 prescribe “for the expression of uncertainty” and ISO 12999-1:2020 Annex B requires for the uncertainty of single-number values.

Parameters

Name	Description
`values_by_band`	Measured band quantities (`R`, `R'`, `Dn`, `DnT` …) in dB, one-third-octave bands.
`frequencies`	Band centre frequencies, in Hz (one per value). `None` assumes exactly the 16 core bands 100-3150 Hz. The 16 core bands must always be present; extended terms are formed for each Annex B range whose bands are all present.
`one_decimal`	Use the 0,1 dB shift and one-decimal reductions.

Returns: An ExtendedWeightedRatingResult.

Raises

Exception	When
ValueError	If the input is not one-dimensional and finite, the band counts differ, or the core bands are missing.

WeightedRatingResult

WeightedRatingResult(
    rating: int,
    c: int,
    ctr: int,
    unfavourable_sum: float,
    band_centers: np.ndarray | None = None,
    measured: np.ndarray | None = None,
    shifted_reference: np.ndarray | None = None,
    quantity: str = 'airborne',
)

Single-number weighted rating and adaptation terms (ISO 717-1).

Attributes

Name	Description
`rating`	Weighted rating (`Rw`, `R'w`, `DnT,w` …), the shifted reference read at 500 Hz, in dB (Clause 4.4). Integer.
`c`	Spectrum adaptation term `C` (spectrum No. 1), in dB (Clause 4.5). Integer.
`ctr`	Spectrum adaptation term `Ctr` (spectrum No. 2), in dB (Clause 4.5). Integer.
`unfavourable_sum`	Sum of unfavourable deviations at the final shift, in dB (Clause 4.4); at most 32,0 (16 bands) or 10,0 (5 bands).
`band_centers`	Band centre frequencies of the measured curve, in Hz. Defaults to `None` for backward-compatible construction.
`measured`	The measured band quantities used for the rating (after the one-decimal reduction of Clause 4.4), in dB. Defaults to `None`.
`shifted_reference`	Table 3 reference curve after the final shift, in dB. Defaults to `None`.
`quantity`	`"airborne"` (ISO 717-1, sound reduction index) or `"impact"` (ISO 717-2), selecting the labels of the ISO 717 Annex C report. Defaults to `"airborne"`.

WeightedRatingResult.plot()

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

Plot the measured curve vs the shifted reference (ISO 717-1).

Unfavourable deviations (reference above measurement) are shaded and Rw (C; Ctr) annotated. Requires matplotlib (pip install phonometry[plot]); returns the Axes.

WeightedRatingResult.report()

WeightedRatingResult.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = 'en',
    symbol: str | None = None,
) -> str

Render an ISO 717-1 airborne sound-insulation fiche to a PDF.

Writes a one-page accredited-laboratory report: the standard-basis line, an optional metadata header block, the band table beside the measured-versus-shifted-reference plot (the result’s own plot), the boxed Rw (C; Ctr) result, an optional verdict row and a footer with the fixed disclaimer.

Parameters

Name	Description
`path`	Destination path of the PDF file.
`metadata`	Optional `ReportMetadata`; `None` produces a prediction fiche (body, result and disclaimer only).
`engine`	Rendering back end; only `"reportlab"` is supported.
`verbose`	When `True`, the table uses the ISO 717 Annex C columns (frequency, measured value, shifted reference, unfavourable deviation) instead of the two-column `f \| value` table.
`language`	Fiche language: `"en"` (default, English) or `"es"` (Spanish, with a comma decimal separator).
`symbol`	The reported single-number quantity, as plain text: `"Rw"` (the default when `None`), `"R'w"`, `"Dn,w"`, `"DnT,w"` … per ISO 717-1 Tables 1-2, so a field measurement (e.g. a standardized level difference rated to `DnT,w`) is not mislabelled with the laboratory descriptor.

Returns: The written path as a str.

Raises

Exception	When
ValueError	If `engine` is not `"reportlab"`, `symbol` is not a valid quantity-symbol shape, or the result was built without the per-band data (`band_centers`, `measured`, `shifted_reference`).
ImportError	If reportlab is not installed (`pip install phonometry[report]`), or matplotlib is missing for the embedded figure (`pip install phonometry[plot]`).

Creado y mantenido por José Manuel Requena Plens ORCID Todos los proyectos