Skip to content

room.noise_criteria

Room-noise rating curves per ANSI/ASA S12.2-2019.

Implements the two spectrum-in rating methods of ANSI/ASA S12.2-2019, Criteria for Evaluating Room Noise:

  • Noise Criteria (NC) by the two-step procedure of clause 5.2.2. The speech interference level SIL (clause 3.2, the average of the 500, 1000, 2000 and 4000 Hz octave-band levels) selects the NC-(SIL) curve; when no octave band exceeds that curve, the spectrum is designated NC-(SIL), and otherwise the rating is determined by the tangency method (clause 5.2.3: the value of the highest NC curve of Table 1 touched by the spectrum, reported together with the governing band). The tangency rating is always evaluated and kept available on the result.
  • Room Criteria Mark II (RC) (Annex D, Table D.1). The numerical rating is the mid-frequency average LMF (500/1000/2000 Hz) rounded to the nearest decibel (clause D.4); the spectral tag N/R/H follows the deviation rules of clause D.3.

Both methods evaluate octave-band sound pressure levels over the 16 Hz to 8000 Hz bands tabulated by the standard. The RC Mark II curves are generated from the -5 dB/octave rule of Annex D (16 Hz equal to 31.5 Hz, with the low frequencies not dropping below 55 dB), which reproduces Table D.1 exactly.

The balanced noise criteria (NCB), the room noise criterion for fluctuating low-frequency noise (RNC, Annex A), the acoustically induced vibration and rattle classification (RV, clause D.3.4, which needs the Table 6 test) and the numeric quality-assessment index (QAI, clause D.5, which the standard defers to external references) are not implemented here.

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

nc_curve(index: float) -> NDArray[np.float64]

Octave-band levels of a Noise Criteria curve (ANSI/ASA S12.2-2019 Table 1).

Parameters

Name Description
index The NC designation. Integer designations from 15 to 70 in steps of five return the tabulated curve; intermediate values are linearly interpolated band by band.

Returns: The 10-band curve levels, in dB, aligned with NC_OCTAVE_BANDS_HZ.

Raises

Exception When
ValueError if index is outside the tabulated range.
TypeError if index is not a single number.

Constant (numpy.ndarray, shape (12, 10)).

Constant (numpy.ndarray, shape (10,)).

Constant (numpy.ndarray, shape (12,)).

NCResult(
rating: float,
governing_frequency: float,
frequencies: NDArray[np.float64],
levels: NDArray[np.float64],
sil: float = nan,
tangency_rating: float = nan,
method: Literal['SIL', 'tangency'] = 'tangency',
out_of_range: Literal['above', 'below'] | None = None,
)

Result of a Noise Criteria (NC) rating (ANSI/ASA S12.2-2019, 5.2).

Attributes

Name Description
rating The reported NC designation, following the two-step procedure of clause 5.2.2: when no octave band exceeds the NC-(SIL) curve chosen from the speech interference level, the designation is NC-(SIL); otherwise it is the tangency rating (clause 5.2.3). NaN when the spectrum lies outside the NC-15 to NC-70 family of Table 1 (see out_of_range).
governing_frequency Band, in hertz, where the tangency touch occurs (for a spectrum above the family, the band of maximum exceedance over the NC-70 curve); NaN for a SIL-designated spectrum, which has no governing band.
frequencies Octave-band centre frequencies evaluated, in hertz.
levels Measured octave-band sound pressure levels, in dB.
sil Speech interference level, in dB: the arithmetic average of the 500, 1000, 2000 and 4000 Hz octave-band levels (clause 3.2); NaN when any of the four bands is missing.
tangency_rating The tangency-method rating (clause 5.2.3), always evaluated; NaN when the spectrum lies outside the Table 1 family.
method "SIL" when the designation is the clause 5.2.2 NC-(SIL) value, "tangency" otherwise.
out_of_range None inside the NC-15 to NC-70 family; "above" when a band exceeds the NC-70 curve (no NC rating is defined, label reads ">NC-70"); "below" when every measured band lies below the NC-15 curve (label reads "<NC-15").

property

The textual NC designation.

"NC-44" for a SIL-designated spectrum, "NC-51 (125 Hz)" for a tangency rating with its governing band (the form of clause 5.2.3), and ">NC-70 (63 Hz)" / "<NC-15" for a spectrum outside the Table 1 family, for which the standard defines no NC rating.

NCResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the measured spectrum against the NC curves.

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

Parameters

Name Description
language The language of the labels: "en" or "es".
NCResult.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render a Noise Criteria (NC) assessment fiche to a PDF.

Writes a one-page room-noise assessment report (ANSI/ASA S12.2-2019): the standard-basis line, an optional metadata header block, the measured octave-band levels beside the measured spectrum plotted against the NC curve family (the result’s own plot), the boxed NC designation (the clause 5.2.2 NC-(SIL) value, or the tangency rating with its governing band; ">NC-70" / "<NC-15" outside the Table 1 family), 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 bare assessment fiche (body, result and disclaimer only). A supplied requirement is read as the maximum acceptable NC rating (a lower rating is quieter, so the room passes at or below it).
engine Rendering back end; only "reportlab" is supported.
verbose When True, the table adds the per-band NC contour value read by the tangency method.
language Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator).

Returns: The written path as a str.

Raises

Exception When
ValueError If engine is not "reportlab".
ImportError If reportlab is not installed (the [report] extra), or matplotlib is missing for the embedded figure (the [plot] extra).
noise_criterion(
levels: NumericArrayLike,
*,
frequencies: NumericArrayLike | None = None,
) -> NCResult

Noise Criteria (NC) rating of a spectrum (ANSI/ASA S12.2-2019, 5.2.2).

Follows the standard’s two-step rating procedure. First the speech interference level SIL (clause 3.2: the average of the 500, 1000, 2000 and 4000 Hz levels) selects the NC-(SIL) curve; when no octave band exceeds that curve, the spectrum is designated NC-(SIL). Otherwise the rating is determined by the tangency method (clause 5.2.3): for each band the NC index whose Table 1 curve passes through the measured level is found by interpolation, the rating is the maximum over bands and the governing band is where that maximum occurs. The tangency rating is always evaluated and kept on tangency_rating; when the four SIL bands are not all supplied, the tangency rating is the designation.

A spectrum outside the Table 1 family has no NC rating: when a band exceeds the NC-70 curve the result is flagged out_of_range="above" (with the governing band at the maximum exceedance over NC-70), and when every measured band lies below the NC-15 curve it is flagged out_of_range="below"; in both cases rating is NaN and label reads ">NC-70" / "<NC-15".

Parameters

Name Description
levels Octave-band sound pressure levels, in dB. Without frequencies this must be the 10 bands from 16 Hz to 8000 Hz.
frequencies Optional band centre frequencies, in hertz, matching levels; a subset of the ANSI S12.2 octave bands may be supplied.

Returns: An NCResult with the designation and its .plot().

Raises

Exception When
ValueError for malformed inputs or unknown band frequencies.
TypeError if frequencies or levels holds a text or a value that is not a real number.

A room noise rating computed on fewer bands than its clause rates.

Emitted by room_criterion when the spectrum lacks one of the 31.5 Hz to 4000 Hz octave bands ANSI/ASA S12.2-2019 clause D.4 rates, which the spectral-tag deviation tests then skip.

rc_curve(index: float) -> NDArray[np.float64]

Octave-band levels of a Room Criteria Mark II curve (Annex D, Table D.1).

The curve has a constant slope of -5 dB/octave keyed to its value at 1000 Hz; the 31.5 Hz level does not drop below 55 dB and the 16 Hz level equals the 31.5 Hz level.

Parameters

Name Description
index The RC designation (value at 1000 Hz).

Returns: The 10-band curve levels, in dB, aligned with NC_OCTAVE_BANDS_HZ.

Raises

Exception When
TypeError if index is not a single number.
RCResult(
rating: int,
lmf: float,
classification: Literal['N', 'R', 'H', 'RH'],
reference_curve: NDArray[np.float64],
frequencies: NDArray[np.float64],
levels: NDArray[np.float64],
)

Result of a Room Criteria Mark II rating (ANSI/ASA S12.2-2019, Annex D).

Attributes

Name Description
rating Numerical RC designation LMF rounded to the nearest dB.
lmf Mid-frequency average (500/1000/2000 Hz), in dB (clause D.4).
classification Spectral tag, "N" (neutral), "R" (rumble) or "H" (hiss) per clause D.3, or "RH" when both the rumble and the hiss deviation tests fire. Clause D.3.5 admits only the letters N, R, H or the combination RV, so the combined "RH" tag is a diagnostic extension of this library, not a clause D.3.5 designation. The vibration/rattle tag RV (clause D.3.4) needs the Table 6 criterion test and is not implemented.
reference_curve The RC Mark II curve used for classification, in dB.
frequencies Octave-band centre frequencies evaluated, in hertz.
levels Measured octave-band sound pressure levels, in dB.

property

The room-criterion label in the RC-NN(A) form of clause D.3.5.

Clause D.3.5 admits N, R, H or RV as the tag; when both the rumble and hiss deviations fire, this library labels the spectrum with the combined RH extension (see classification).

property

True when the rating falls outside the tabulated RC-25 to RC-50 family.

Table D.1 tabulates the RC Mark II curves for ratings 25 through 50 and clause D.3.5 defines the RC-NN(A) label for integers in that range. Outside it the reference curve is generated by the same -5 dB/octave rule of Annex D, but the designation extrapolates beyond the standard’s tabulated family.

RCResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the measured spectrum against the reference RC Mark II curve.

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

Parameters

Name Description
language The language of the labels: "en" or "es".
RCResult.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render a Room Criteria Mark II (RC) assessment fiche to a PDF.

Writes a one-page room-noise assessment report (ANSI/ASA S12.2-2019, Annex D): the standard-basis line, an optional metadata header block, the measured octave-band levels beside the measured spectrum plotted against the reference RC Mark II curve (the result’s own plot), the boxed RC-nn(tag) rating with its mid-frequency average and spectral-quality tag, 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 bare assessment fiche (body, result and disclaimer only). A supplied requirement is read as the maximum acceptable RC rating (a lower rating is quieter, so the room passes at or below it).
engine Rendering back end; only "reportlab" is supported.
verbose When True, the table adds the reference RC Mark II curve and the measured deviation from it.
language Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator).

Returns: The written path as a str.

Raises

Exception When
ValueError If engine is not "reportlab".
ImportError If reportlab is not installed (the [report] extra), or matplotlib is missing for the embedded figure (the [plot] extra).
room_criterion(
levels: NumericArrayLike,
*,
frequencies: NumericArrayLike | None = None,
) -> RCResult

Room Criteria Mark II rating (ANSI/ASA S12.2-2019, Annex D).

The numerical rating is the mid-frequency average LMF of the 500, 1000 and 2000 Hz levels rounded to the nearest decibel (clause D.4). The spectral tag is neutral ("N") when the levels at and below 500 Hz do not exceed the reference RC curve by more than 5 dB and the levels at and above 1000 Hz do not exceed it by more than 3 dB; rumble ("R") when a low band exceeds by more than 5 dB; hiss ("H") when a high band exceeds by more than 3 dB (clause D.3). When both deviations fire, the library tags the spectrum "RH", a diagnostic extension beyond the clause D.3.5 letters (see RCResult).

Clause D.4 evaluates a spectrum that includes at least the octave bands from 31.5 Hz through 4000 Hz; when any of those bands is missing a NoiseCriterionWarning is emitted, since the absent bands are skipped by the spectral-tag deviation tests. A rating outside the tabulated RC-25 to RC-50 family is flagged by RCResult.out_of_family.

Parameters

Name Description
levels Octave-band sound pressure levels, in dB. Without frequencies this must be the 10 bands from 16 Hz to 8000 Hz.
frequencies Optional band centre frequencies, in hertz, matching levels.

Returns: An RCResult with the rating, tag and its .plot().

Raises

Exception When
ValueError if the 500/1000/2000 Hz mid-frequency bands are absent.
TypeError if frequencies or levels holds a text or a value that is not a real number.

Warns

Warning When
NoiseCriterionWarning if a band from 31.5 Hz to 4000 Hz is absent.