metrology.levels

Integrated and statistical sound levels (Leq, LAeq, LN percentiles).

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

laeq

laeq(
    x: list[float] | np.ndarray,
    fs: int,
    calibration_factor: float = 1.0,
    dbfs: bool = False,
) -> float | np.ndarray

A-weighted equivalent continuous sound level (LAeq).

Parameters

Name	Description
x	Input signal (1D or 2D [channels, samples]), raw pressure units.
fs	Sample rate in Hz.
calibration_factor	Multiplier converting digital units to Pascals.
dbfs	If True, return dBFS instead of dB SPL.

Returns: Scalar for 1D input, array of shape (channels,) for 2D input.

lc_peak

lc_peak(
    x: list[float] | np.ndarray,
    fs: int,
    calibration_factor: float = 1.0,
    dbfs: bool = False,
    oversample: int = 8,
) -> float | np.ndarray

C-weighted peak sound level, LCpeak (IEC 61672-1:2013, subclause 5.13).

The absolute maximum of the C-weighted signal, expressed in dB. This is the quantity used by occupational-noise regulations (e.g. 135/137/140 dB(C) action limits). Verified against the reference one-cycle and half-cycle responses of BS EN 61672-1:2013 Table 5 in the test suite.

The true peak of a continuous waveform generally falls between samples. A raw on-grid maximum therefore under-reads sustained high-frequency tones (worst near integer samples-per-cycle rates, e.g. an 8 kHz tone at fs = 48 kHz is 6.0 samples/cycle and under-reads by up to ~1.15 dB). The C-weighted signal is polyphase-oversampled by oversample before the maximum is taken, recovering the inter-sample peak to within about +/-0.5 dB of the analytic value.

Parameters

Name	Description
x	Input signal (1D or 2D [channels, samples]), raw pressure units.
fs	Sample rate in Hz.
calibration_factor	Multiplier converting digital units to Pascals.
dbfs	If True, return dBFS (0 dB = peak 1.0) instead of dB SPL.
oversample	Integer oversampling factor applied before peak detection (default 8, the audit-validated value). Use 1 to disable oversampling and detect the peak on the original sample grid.

Returns: Scalar for 1D input, array of shape (channels,) for 2D input.

leq

leq(
    x: list[float] | np.ndarray,
    calibration_factor: float = 1.0,
    dbfs: bool = False,
) -> float | np.ndarray

Equivalent continuous sound level (Leq) over the whole signal.

Parameters

Name	Description
x	Input signal (1D or 2D [channels, samples]), raw pressure units.
calibration_factor	Multiplier converting digital units to Pascals.
dbfs	If True, return dBFS (0 dB = RMS 1.0) instead of dB SPL.

Returns: Scalar for 1D input, array of shape (channels,) for 2D input.

lex_8h

lex_8h(
    x: list[float] | np.ndarray,
    fs: int,
    duration_hours: float | None = None,
    calibration_factor: float = 1.0,
) -> float | np.ndarray

Normalized 8-h average sound level, LEX,8h (IEC 61252, 3.3).

The daily personal noise exposure level: the steady level that, sustained over a nominal 8 h working day, carries the same A-weighted sound exposure as the measured event. Identical to LEP,d (Directive 86/188/EEC) and LEX,8h of ISO 1999 (BS EN 61252:1995, 3.3 NOTES 5-6).

Parameters

Name	Description
x	Input signal in raw pressure units (1D or 2D).
fs	Sample rate in Hz.
duration_hours	Exposure period the input represents, in hours. Default: the recording duration itself.
calibration_factor	Multiplier converting digital units to Pascals.

Returns: LEX,8h in dB (scalar or per-channel array).

ln_levels

ln_levels(
    x: list[float] | np.ndarray,
    fs: int,
    n: Sequence[int] = (10, 50, 90),
    mode: str = 'fast',
    weighting: str | None = None,
    calibration_factor: float = 1.0,
    dbfs: bool = False,
) -> dict[int, float | np.ndarray]

Statistical percentile levels (LN) from the time-weighted level envelope.

L10 is the level exceeded 10% of the time (90th percentile of the level distribution), L90 the level exceeded 90% of the time, etc.

Parameters

Name	Description
x	Input signal (1D or 2D [channels, samples]), raw pressure units.
fs	Sample rate in Hz.
n	Percentile exceedance values, e.g. (10, 50, 90).
mode	Time weighting for the envelope: ‘fast’, ‘slow’ or ‘impulse’.
weighting	Optional frequency weighting: ‘A’, ‘C’, ‘Z’ or None.
calibration_factor	Multiplier converting digital units to Pascals.
dbfs	If True, return dBFS instead of dB SPL.

Returns: Dict mapping each N to its level (scalar for 1D input, array (channels,) for 2D input).

sel

sel(
    x: list[float] | np.ndarray,
    fs: int,
    weighting: str | None = None,
    calibration_factor: float = 1.0,
    dbfs: bool = False,
) -> float | np.ndarray

Sound exposure level (SEL / LAE): the event level normalized to 1 second.

SEL = Leq,T + 10*log10(T / 1 s), the standard single-event metric (aircraft flyovers, train passes). With weighting="A" this is LAE as defined by IEC 61672-1:2013 (verified against the Table 4 toneburst reference responses, Equation 8, in the test suite).

Parameters

Name	Description
x	Input signal covering the whole event (1D or 2D).
fs	Sample rate in Hz.
weighting	Optional frequency weighting: ‘A’, ‘C’, ‘Z’ or None.
calibration_factor	Multiplier converting digital units to Pascals.
dbfs	If True, reference digital full scale instead of 20 uPa.

Returns: Scalar for 1D input, array of shape (channels,) for 2D input.

sound_exposure

sound_exposure(
    x: list[float] | np.ndarray,
    fs: int,
    duration_hours: float | None = None,
    calibration_factor: float = 1.0,
) -> float | np.ndarray

A-weighted sound exposure E in pascal-squared hours (IEC 61252, 3.1).

The time integral of the squared A-weighted sound pressure. By default the input is the whole event (E integrates over len(x)/fs); pass duration_hours to treat the input as a representative sample of a longer exposure period (E = mean-square * duration). Anchors from BS EN 61252:1995 (3.3 NOTE 4): 3.2 Pa²h <-> LEX,8h of exactly 90 dB.

Parameters

Name	Description
x	Input signal in raw pressure units (1D or 2D).
fs	Sample rate in Hz.
duration_hours	Exposure period the input represents, in hours. Default: the recording duration itself.
calibration_factor	Multiplier converting digital units to Pascals.

Returns: Exposure in Pa²·h (scalar or per-channel array).