← [Documentation index](README.md)
# API Reference
All core functionality can be imported directly from the `phonometry` package.
| Name | Type | Description (Inputs) | Usage Snippet (Outputs) |
| :--- | :--- | :--- | :--- |
| `octavefilter` | `function` | **High-level analysis.**
• `x`: Signal array
• `fs`: Sample rate [Hz]
• `fraction`: 1, 3, etc. (Default: 1)
• `order`: Filter order (Default: 6)
• `limits`: [f_min, f_max] (Default: [12, 20000])
• `filter_type`: 'butter', 'cheby1', 'cheby2', 'ellip', 'bessel' (Default: 'butter')
• `sigbands`: Return time signals (Default: False)
• `detrend`: Remove DC offset (Default: True)
• `calibration_factor`: Sensitivity multiplier (Default: 1.0)
• `dbfs`: Output in dBFS instead of dB SPL (Default: False)
• `mode`: 'rms' or 'peak' (Default: 'rms')
• `nominal`: IEC 61260-1 nominal labels (Default: False)
• `show`: Plot response (Default: False)
• `plot_file`: Path to save plot (Default: None)
• `ripple`: Passband ripple [dB] (for cheby1/ellip)
• `attenuation`: Stopband atten. [dB] (Default: 72; for cheby2/ellip — cheby2 needs >= 70 dB for class 1) | `spl, freq = octavefilter(x, fs, ...)`
• `spl`: levels [dB]
• `freq`: frequencies [Hz]
**With `sigbands=True`:**
`spl, freq, xb = octavefilter(x, fs, sigbands=True)`
• `xb`: List of filtered signals (one per band)
**Calibrated usage:**
`spl, f = octavefilter(x, fs, calibration_factor=0.05)` |
| `OctaveFilterBank` | `class` | **Efficient bank implementation.**
• `fs`: Sample rate [Hz]
• `fraction`: 1, 3, etc.
• `order`: Filter order
• `limits`: [f_min, f_max] (Default: [12, 20000])
• `filter_type`: Architecture name
• `show`: Plot response (Default: False)
• `plot_file`: Path to save the plot (Default: None)
• `calibration_factor`: Sensitivity multiplier
• `dbfs`: Use dBFS (Default: False)
• `stateful`: Carry filter state between calls (Default: False)
• `steady_ic`: Steady-state initial conditions (Default: False)
• `resample`: Multirate decimation (Default: True)
• `ripple`: Passband ripple [dB]
• `attenuation`: Stopband attenuation [dB] (Default: 72; cheby2 needs >= 70 dB for class 1) | `bank = OctaveFilterBank(fs=48000, fraction=3, order=6, filter_type='butter')`
`spl, f = bank.filter(x, sigbands=False, mode='rms', detrend=True, zero_phase=False)`
• `bank`: Instance of the filter bank
• `bank.freq` / `bank.freq_d` / `bank.freq_u` / `bank.sos`: computed properties |
| `OctaveFilterBank.spectrogram` | `method` | **Band levels over time.**
• `x`: Signal array (1D or 2D)
• `window_time`: Window length [s] (Default: 0.125)
• `overlap`: Fraction in [0, 1) (Default: 0.5)
• `mode`: 'rms' or 'peak'
• `zero_phase`: Group-delay-free frames (Default: False) | `levels, freq, times = bank.spectrogram(x)`
• `levels`: (bands, frames) or (channels, bands, frames)
• `times`: window centers [s] |
| `weighting_filter` | `function` | **Acoustic weighting.**
• `x`: Signal array
• `fs`: Sample rate [Hz]
• `curve`: 'A', 'C', 'G' (ISO 7196 infrasound) or 'Z' (Default: 'A')
• `high_accuracy`: IEC class 1 HF accuracy via internal oversampling (Default: True) | `y = weighting_filter(x, fs, curve='A')`
• `y`: weighted signal |
| `WeightingFilter` | `class` | **Reusable weighting filter.**
• `fs`: Sample rate [Hz]
• `curve`: 'A', 'C', 'G' or 'Z'
• `stateful`: Block processing (Default: False)
• `steady_ic`: Steady-state initial conditions (Default: False)
• `high_accuracy`: Defaults to True except stateful | `wf = WeightingFilter(fs, 'A')`
`y = wf.filter(x)` |
| `time_weighting` | `function` | **Energy capture.**
• `x`: Raw signal array (squared internally; time is the last axis)
• `fs`: Sample rate [Hz]
• `mode`: 'fast', 'slow', or 'impulse'
• `initial_state`: None, 'zero', 'first', scalar, or array (Default: None) | `env = time_weighting(x, fs, mode='fast')`
• `env`: energy envelope (Mean Square), same shape as `x` |
| `TimeWeighting` | `class` | **Stateful time weighting.**
• `fs`: Sample rate [Hz]
• `mode`: 'fast', 'slow', 'impulse' (Default: 'fast') | `tw = TimeWeighting(fs, mode='fast')`
`env = tw.process(block)` per block
`tw.reset()` to start over |
| `leq` | `function` | **Equivalent level (Leq).**
• `x`: Signal array (1D or 2D)
• `calibration_factor`: Sensitivity multiplier (Default: 1.0)
• `dbfs`: Output in dBFS (Default: False) | `level = leq(x, calibration_factor=s)`
• `level`: Scalar (1D) or per-channel array (2D) |
| `laeq` | `function` | **A-weighted Leq (LAeq).**
• `x`: Signal array (1D or 2D)
• `fs`: Sample rate [Hz]
• `calibration_factor` / `dbfs`: as `leq` | `level = laeq(x, fs, calibration_factor=s)`
• `level`: Scalar (1D) or per-channel array (2D) |
| `ln_levels` | `function` | **Statistical levels (LN).**
• `x`: Signal array (1D or 2D)
• `fs`: Sample rate [Hz]
• `n`: Exceedance percentiles (Default: (10, 50, 90))
• `mode`: 'fast', 'slow', 'impulse' (Default: 'fast')
• `weighting`: 'A', 'C', 'G', 'Z' or None (Default: None)
• `calibration_factor` / `dbfs`: as `leq` | `stats = ln_levels(x, fs, n=(10, 50, 90), weighting='A')`
• `stats`: Dict `{10: L10, 50: L50, 90: L90}` |
| `lc_peak` | `function` | **C-weighted peak (LCpeak).**
• `x`: Signal array (1D or 2D)
• `fs`: Sample rate [Hz]
• `calibration_factor`: as `leq`
• `dbfs`: 0 dBFS = full-scale *peak* (amplitude 1.0), unlike the RMS reference of `leq`
• `oversample`: HF inter-sample peak recovery (Default: 8; 1 = on-grid, under-reads up to ~1.15 dB at 48 kHz) | `peak = lc_peak(x, fs)`
• IEC 61672-1 §5.13; verified against Table 5 |
| `sel` | `function` | **Sound exposure level (SEL/LAE).**
• `x`: Whole-event signal (1D or 2D)
• `fs`: Sample rate [Hz]
• `weighting`: 'A', 'C', 'G', 'Z' or None (Default: None)
• `calibration_factor` / `dbfs`: as `leq` | `lae = sel(x, fs, weighting='A')`
• Event level normalized to 1 s |
| `sound_exposure` | `function` | **A-weighted exposure E (IEC 61252).**
• `x`: Signal (1D or 2D)
• `fs`: Sample rate [Hz]
• `duration_hours`: exposure period represented (Default: recording length)
• `calibration_factor` | `E = sound_exposure(x, fs, duration_hours=8)`
• `E`: Pa²·h |
| `lex_8h` | `function` | **Daily exposure LEX,8h / LEP,d.**
• Same params as `sound_exposure` | `lex = lex_8h(x, fs, duration_hours=4)`
• Normalized 8 h level [dB] |
| `loudness_zwicker` | `function` | **Zwicker loudness (ISO 532-1:2017).**
• `x`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz]
• `field`: 'free' or 'diffuse' (Default: 'free')
• `stationary`: Clause 5 stationary method (Default: False)
• `calibration_factor`: Digital units to Pa (Default: 1.0) | `res = loudness_zwicker(x, fs)`
• `ZwickerLoudness`; time-varying runs add N5/N10 and the 500 Hz N(t) trace |
| `loudness_zwicker_from_spectrum` | `function` | **Stationary loudness from band levels.**
• `levels`: 28 one-third-octave levels, 25 Hz-12.5 kHz [dB SPL]
• `field`: 'free' or 'diffuse' (Default: 'free') | `res = loudness_zwicker_from_spectrum(levels)`
• `res.loudness` [sone], `res.loudness_level` [phon] |
| `ZwickerLoudness` | `dataclass` | **Loudness result.**
• `loudness`: N [sone]
• `loudness_level`: LN [phon]
• `specific`: N′(z), 240 bins of 0.1 Bark
• `n5` / `n10`: percentile loudness (time-varying only)
• `time` / `loudness_vs_time`: 500 Hz trace | `res.loudness, res.n5`
• Time-varying fields are `None` for stationary results |
| `sharpness_din` | `function` | **Sharpness in acum (DIN 45692).**
• `x`: Signal (1D)
• `fs`: Sample rate [Hz]
• `field`: 'free' or 'diffuse' (Default: 'free')
• `method`: 'din', 'aures' or 'bismarck' (Default: 'din')
• `calibration_factor`: Digital units to Pa (Default: 1.0) | `s = sharpness_din(x, fs)`
• `s`: sharpness [acum] |
| `sharpness_din_from_specific` | `function` | **Sharpness from a specific-loudness pattern.**
• `specific`: N′(z), 240 values at 0.1 Bark (e.g. `ZwickerLoudness.specific`)
• `method`: 'din', 'aures' or 'bismarck' (Default: 'din') | `s = sharpness_din_from_specific(res.specific)`
• `s`: sharpness [acum] |
| `loudness_moore_glasberg` | `function` | **Moore-Glasberg loudness (ISO 532-2:2017).**
• `x`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz]
• `field`: 'free', 'diffuse' or 'eardrum' (Default: 'free')
• `presentation`: 'binaural'/'diotic' or 'monaural' (Default: 'binaural') | `res = loudness_moore_glasberg(x, fs)`
• `MooreGlasbergLoudness` (roex excitation pattern) |
| `loudness_moore_glasberg_from_spectrum` | `function` | **Exact loudness from sinusoidal components (ISO 532-2 §5.2/5.4).**
• `components`: sequence of (frequency [Hz], level [dB SPL]) pairs
• `field`: 'free'/'diffuse'/'eardrum' (Default: 'free')
• `presentation`: (Default: 'binaural') | `res = loudness_moore_glasberg_from_spectrum([(1000.0, 40.0)])`
• 1 kHz/40 dB → 1.000 sone |
| `loudness_moore_glasberg_from_third_octave` | `function` | **Loudness from 29 one-third-octave band levels (ISO 532-2 §5.5).**
• `band_levels`: 29 levels, 25 Hz–16 kHz [dB SPL]
• `field` / `presentation`: as above | `res = loudness_moore_glasberg_from_third_octave(levels)`
• `MooreGlasbergLoudness` |
| `MooreGlasbergLoudness` | `dataclass` | **Moore-Glasberg loudness result.**
• `loudness`: N [sone]
• `loudness_level`: LN [phon]
• `specific`: N′(i), 372 bins of 0.1 Cam
• `erb_number` / `centre_frequencies`: Cam / Hz axes
• `field` / `presentation`
• `.plot()`: specific loudness N′(i) over Cam | `res.loudness, res.loudness_level` |
| `loudness_moore_glasberg_time` | `function` | **Time-varying loudness (ISO 532-3:2023).**
• `signal`: Calibrated Pa; 1D (diotic) or (n, 2) ears
• `fs`: Sample rate [Hz]
• `field`: 'free'/'diffuse'/'eardrum' (Default: 'free')
• `presentation`: (Default: 'binaural')
• `percentiles`: exceedance % (Default: (1,5,10,50,90,95)) | `res = loudness_moore_glasberg_time(x, fs)`
• `MooreGlasbergTimeVaryingLoudness` |
| `MooreGlasbergTimeVaryingLoudness` | `dataclass` | **Time-varying loudness result.**
• `time`: 1 ms grid [s]
• `short_term_loudness` / `long_term_loudness`: S′(t)/S″(t) [sone]
• `short_term_loudness_level` / `long_term_loudness_level` [phon]
• `n_max` / `loudness_level_max`: peak long-term loudness
• `percentiles`: dict {percent: sone}
• `.plot()`: STL and LTL vs time | `res.n_max, res.percentiles[5.0]` |
| `loudness_ecma` | `function` | **Sottek Hearing Model loudness (ECMA-418-2:2025).**
• `signal_in`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz] (resampled to 48 kHz)
• `field`: 'free' or 'diffuse' (Default: 'free') | `res = loudness_ecma(x, fs)`
• `EcmaLoudness`; 1 kHz/40 dB ≈ 1 sone_HMS |
| `EcmaLoudness` | `dataclass` | **Sottek loudness result.**
• `loudness`: N [sone_HMS]
• `specific_loudness`: N′(z), 53 Bark_HMS bands
• `bark` / `centre_frequencies`: z / Hz axes
• `time` / `loudness_vs_time`: N(l) at 187.5 Hz
• `field`
• `.plot()`: N′(z) + N(l) | `res.loudness, res.specific_loudness` |
| `tonality_ecma` | `function` | **Sottek tonality (ECMA-418-2:2025).**
• `signal_in`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz] (resampled to 48 kHz)
• `field`: 'free' or 'diffuse' (Default: 'free')
• `f_low` / `f_high`: optional user band [Hz] (Default: None) | `res = tonality_ecma(x, fs)`
• `EcmaTonality`; 1 kHz/40 dB ≈ 1 tu_HMS |
| `EcmaTonality` | `dataclass` | **Sottek tonality result.**
• `tonality`: T [tu_HMS]
• `specific_tonality`: T′(z), 53 bands
• `tonal_frequencies`: f_ton,z per band [Hz]
• `bark` / `centre_frequencies`
• `time` / `tonality_vs_time` / `tonal_frequency_vs_time`: T(l), f_ton(l)
• `field`
• `.plot()`: T′(z) + T(l) | `res.tonality, res.tonal_frequencies` |
| `roughness_ecma` | `function` | **Sottek roughness (ECMA-418-2:2025), new capability.**
• `signal_in`: Calibrated signal in Pa (1D)
• `fs`: Sample rate [Hz] (resampled to 48 kHz)
• `field`: 'free' or 'diffuse' (Default: 'free') | `res = roughness_ecma(x, fs)`
• `EcmaRoughness`; 1 kHz/70 Hz/100 %-AM/60 dB ≈ 1 asper |
| `EcmaRoughness` | `dataclass` | **Sottek roughness result.**
• `roughness`: R [asper] (90th percentile of R(l50))
• `specific_roughness`: R′(z), 53 bands
• `bark` / `centre_frequencies`
• `time` / `roughness_vs_time`: R(l50) at 50 Hz
• `specific_roughness_vs_time`: (n_times, 53)
• `field`
• `.plot()`: R(l50) + specific-roughness heatmap | `res.roughness, res.specific_roughness` |
| `equal_loudness_contour` | `function` | **ISO 226:2023 equal-loudness contour.**
• `phon`: Loudness level, 20-90 phon | `freqs, spl = equal_loudness_contour(40.0)`
• SPL at the 29 preferred frequencies |
| `loudness_level` | `function` | **Loudness level of a pure tone (phon).**
• `spl`: Tone SPL [dB]
• `frequency`: One of the 29 Table 1 frequencies [Hz] | `phon = loudness_level(73.0, 63.0)` |
| `hearing_threshold` | `function` | **Threshold of hearing (ISO 226 Table 1).**
• (no parameters) | `freqs, tf = hearing_threshold()` |
| `tone_to_noise_ratio` | `function` | **Tone-to-noise ratio (ECMA-418-1 §11).**
• `x`: Signal (1D)
• `fs`: Sample rate [Hz]
• `tone_freq`: Tone to assess [Hz] (Default: highest peak)
• `resolution_hz`: FFT bin spacing (Default: 1.0) | `r = tone_to_noise_ratio(x, fs)`
• `ToneAssessment(frequency, ratio_db, criterion_db, prominent)` |
| `prominence_ratio` | `function` | **Prominence ratio (ECMA-418-1 §12).**
• Same params as `tone_to_noise_ratio` | `r = prominence_ratio(x, fs, tone_freq=1000)`
• `ToneAssessment(...)` |
| `ToneAssessment` | `dataclass` | **Tone prominence verdict.**
• `frequency`: Assessed tone [Hz]
• `ratio_db`: TNR or PR [dB]
• `criterion_db`: Prominence limit at that frequency [dB]
• `prominent`: bool | `r = tone_to_noise_ratio(x, fs)`
`if r.prominent: ...` |
| `sti_from_impulse_response` | `function` | **Full STI, indirect method (IEC 60268-16 Ed. 5).**
• `ir`: Impulse response (1D)
• `fs`: Sample rate [Hz] (>= 22500)
• `snr`: SNR [dB], scalar or 7 bands (Default: None)
• `level`: 7 speech band levels [dB SPL]; enables masking + reception threshold (Default: None)
• `ambient`: 7 noise band levels [dB SPL]; requires `level` | `res = sti_from_impulse_response(ir, fs, snr=25.0)`
• `STIResult` with `mtf` (7×14) |
| `stipa` | `function` | **STIPA direct method (Annex B).**
• `x`: Recorded STIPA signal (1D), 15-25 s
• `fs`: Sample rate [Hz] (>= 22500)
• `reference`: Measured source signal instead of the nominal m = 0.55 (Default: None)
• `level` / `ambient`: as `sti_from_impulse_response`
• warns (`UserWarning`) if the recording is < 15 s (STI biased low) | `res = stipa(recording, fs)`
• `STIResult` with `mtf` (7×2) |
| `stipa_signal` | `function` | **STIPA test-signal generator (A.4/A.6.1).**
• `fs`: Sample rate [Hz] (>= 22500)
• `seconds`: Duration [s] (Default: 18.0)
• `level_db`: RMS level [dB SPL] (Default: None → RMS 0.1)
• `seed`: Pink-noise seed (Default: None) | `sig = stipa_signal(48000, seconds=18.0)`
• 1D test signal, Ed. 5 male spectrum |
| `STIResult` | `dataclass` | **STI result.**
• `sti`: 0 to 1
• `mti`: band indices (7,)
• `mtf`: corrected m values (7×14 or 7×2)
• `band_levels`: levels used or None
• `rating`: Annex F letter 'A+'…'U' | `res = stipa(x, fs)`
`print(res.sti, res.rating)` |
| `sound_intensity` | `function` | **p-p sound intensity (IEC 61043).**
• `p1`, `p2`: Microphone signals [Pa], equal length
• `fs`: Sample rate [Hz]
• `spacing`: Microphone separation Δr [m]
• `rho`: Air density (Default: 1.204)
• `c`: Speed of sound (Default: 343.0)
• `fraction`: None, 1 or 3 (Default: None)
• `limits`: [f_min, f_max] (Default: [12, 20000])
• `bias_correct`: undo finite-difference under-read of band/broadband totals near `max_valid_frequency` (Default: False) | `res = sound_intensity(p1, p2, fs, spacing=0.012, fraction=3)`
• `IntensityResult` |
| `IntensityResult` | `dataclass` | **Intensity result.**
• Per band (with `fraction`): `frequency`, `intensity` [W/m²], `intensity_level`, `pressure_level`, `pressure_intensity_index`, `direction` (±1), `bias_correction`
• Broadband: `total_*` counterparts
• `max_valid_frequency`: 0.1·c/Δr | `res.total_intensity_level`
`res.total_direction` |
| `field_indicators` | `function` | **ISO 9614-1 Annex A field indicators.**
• `pressure_levels`: Lpi per position [dB]
• `normal_intensity`: Signed Ini per position [W/m²] | `fi = field_indicators(lp, i_n)`
• `FieldIndicators(f2, f3, f4)` |
| `dynamic_capability_index` | `function` | **Dynamic capability Ld (ISO 9614-1 §3.12).**
• `pressure_residual_intensity_index`: δpI0 [dB]
• `bias_error_factor`: K [dB] (Default: 10.0) | `ld = dynamic_capability_index(18.0)`
• Adequate when `Ld > F2` (criterion 1) |
| `CalibrationWarning` | `warning class` | **Unreliable calibration recording.**
Emitted by `calculate_sensitivity` — with `fs` given and `validate=True` — when the tone is unstable (IEC 60942 limit) or too short | `warnings.simplefilter("error", CalibrationWarning)` |
| `lden` | `function` | **Day-evening-night level (ISO 1996-1 §3.6.4).**
• `lday`/`levening`/`lnight`: LAeq per period [dB]
• `hours`: Period durations (Default: (12, 4, 8)) | `l = lden(63.2, 58.1, 51.4)` |
| `ldn` | `function` | **Day-night level (ISO 1996-1 §3.6.5).**
• `lday`/`lnight`: LAeq per period [dB]
• `hours`: Default (15, 9) | `l = ldn(63.2, 51.4)` |
| `composite_rating_level` | `function` | **Whole-day composite rating (ISO 1996-1 §6.5).**
• `periods`: list of (level_db, hours, adjustment_db) summing 24 h | `r = composite_rating_level([(63, 12, 0), (58, 4, 5), (51, 8, 10)])` |
| `linkwitz_riley` | `function` | **Audio crossover.**
• `x`: Signal array
• `fs`: Sample rate [Hz]
• `freq`: Crossover frequency [Hz]
• `order`: Any even number (Default: 4) | `lo, hi = linkwitz_riley(x, fs, freq=1000, order=4)`
• `lo`: Low-pass filtered signal
• `hi`: High-pass filtered signal |
| `calculate_sensitivity` | `function`| **SPL Calibration.**
• `ref_signal`: Calibration signal
• `target_spl`: Level of calibrator (Default: 94.0)
• `ref_pressure`: Reference pressure (Default: 20e-6)
• `narrowband`: coherent Goertzel tone estimate that rejects broadband hum/noise (needs `fs`; Default: False) | `s = calculate_sensitivity(ref_signal, target_spl=94.0)`
• `s`: Float (multiplier for pressure) |
| `verify_filter_class` | `function` | **IEC 61260-1:2014 class check.**
• `bank`: an `OctaveFilterBank`
• `num_points`: frequency grid points per band (Default: 32768) | `result = verify_filter_class(bank)`
• `result["overall_class"]`: 1, 2 or None
• `result["bands"]`: per-band class and margins [dB] |
| `getansifrequencies` | `function` | **ANSI Frequency generator.**
• `fraction`: 1, 3, etc. (Required)
• `limits`: [f_min, f_max] (Default: [12, 20000]) | `f_cen, f_low, f_high, labels = getansifrequencies(fraction=3)`
• `f_cen`: List of center frequencies [Hz]
• `f_low`: List of lower edges [Hz]
• `f_high`: List of upper edges [Hz]
• `labels`: IEC nominal frequency labels |
| `normalizedfreq` | `function` | **Standard IEC Frequencies.**
• `fraction`: 1 or 3 | `freqs = normalizedfreq(fraction=3)`
• `freqs`: List of standard center frequencies [Hz] |
| `sweep_signal` | `function` | **ESS excitation (ISO 18233 Annex B).**
• `fs`: Sample rate [Hz]
• `f1`: Start frequency [Hz]
• `f2`: Stop frequency [Hz] (≤ fs/2)
• `seconds`: Duration [s]
• `amplitude`: Peak (Default: 1.0)
• `fade`: Half-Hann fraction (Default: 0.01) | `s = sweep_signal(48000, 20, 20000, 3.0)`
• 1D exponential sine sweep |
| `inverse_filter` | `function` | **Farina inverse filter for an ESS.**
• Same parameters as `sweep_signal` | `inv = inverse_filter(48000, 20, 20000, 3.0)`
• Time-reversed, +6 dB/oct compensated sweep |
| `impulse_response` | `function` | **Sweep deconvolution (ISO 18233 B.5).**
• `recorded`: Recorded response (1D)
• `reference`: Emitted sweep (1D)
• `fs`: Sample rate [Hz]
• `method`: 'spectral' (Default) or 'farina'
• `f_range`: (f1, f2) for 'farina'
• `regularization`: Tikhonov term (Default: 1e-6)
• `length`: causal samples (Default: len(recorded))
• `return_full`: keep distortion tail (Default: False) | `ir = impulse_response(rec, sweep, fs)`
• 1D impulse response |
| `mls_signal` | `function` | **Maximum-length sequence (ISO 18233 Annex A).**
• `order`: Register length N, 2-20 | `mls = mls_signal(16)`
• Bipolar sequence, length 2**N − 1 |
| `mls_impulse_response` | `function` | **IR from a periodic MLS.**
• `recorded`: Response spanning whole MLS periods (1D)
• `mls`: Excitation sequence
• `length`: IR samples (Default: 2**N − 1) | `ir = mls_impulse_response(rec, mls)`
• Circular cross-correlation / averaging |
| `decay_curve` | `function` | **Schroeder decay curve (ISO 3382-1 5.3.3).**
• `ir`: Impulse response (1D)
• `fs`: Sample rate [Hz]
• `band`: Band centre [Hz] (Default: None → broadband)
• `fraction`: 1 or 3 (Default: 1)
• `zero_phase`: forward-backward band filtering, halves the 125 Hz short-T bias (Default: False) | `dc = decay_curve(ir, fs)` → `DecayCurve`
`time, level = dc` still unpacks (`time` [s], `level` [dB], 0 dB at t=0)
`dc.plot()` draws the decay + EDT/T20/T30 fits |
| `room_parameters` | `function` | **Room acoustics (ISO 3382-1/2).**
• `ir`: Impulse response (1D)
• `fs`: Sample rate [Hz]
• `limits`: (f_min, f_max) or None (Default: (125, 4000))
• `fraction`: 1 or 3 (Default: 1)
• `zero_phase`: forward-backward octave filtering, halves the 125 Hz short-T T30 bias (Default: False) | `res = room_parameters(ir, fs)`
• `RoomAcousticsResult` per band |
| `RoomAcousticsResult` | `dataclass` | **Per-band room parameters.**
• `frequency` [Hz]
• `edt`, `t20`, `t30` [s]
• `c50`, `c80` [dB], `d50`, `ts` [s]
• `dynamic_range` [dB]
• `edt_valid`/`t20_valid`/`t30_valid`
• `curvature` [%] | `res.t30, res.c80, res.t30_valid`
• Arrays with one entry per band |
| `open_plan_metrics` | `function` | **Open-plan office metrics (ISO 3382-3).**
• `positions_m`: Source distances [m] (≥ 4)
• `spl_a_speech`: A-weighted speech level per position [dB]
• `sti_values`: STI per position | `m = open_plan_metrics(r, lp, sti)`
• `OpenPlanResult` |
| `OpenPlanResult` | `dataclass` | **Open-plan single numbers.**
• `d2s`: Spatial decay rate [dB/doubling]
• `lp_as_4m`: Speech level at 4 m [dB]
• `rd`: Distraction distance [m]
• `rp`: Privacy distance [m] | `m.d2s, m.rd, m.rp`
• `nan` when undefined |
| `airborne_insulation` | `function` | **Field airborne insulation (ISO 16283-1).**
• `l1`/`l2`: Source/receiving levels [dB], 1D or (positions, bands)
• `t2`: Receiving-room T per band [s]
• `area`: Partition S [m²] (for R')
• `volume`: Receiving V [m³] (for R')
• `t0`: Reference T0 [s] (Default: 0.5) | `ins = airborne_insulation(l1, l2, t2, area=10, volume=50)`
• `AirborneInsulationResult` |
| `weighted_rating` | `function` | **Single-number rating + C/Ctr (ISO 717-1).**
• `values_by_band`: 16 thirds or 5 octaves [dB]
• `bands`: 'third-octave', 'octave' or None | `w = weighted_rating(R)`
• `WeightedRatingResult` (Rw, C, Ctr) |
| `energy_average_level` | `function` | **Energy-average level (ISO 16283-1 (9)).**
• `levels`: Levels [dB] to average
• `axis`: Averaging axis (Default: -1) | `L = energy_average_level([60, 66])`
• `10 lg( mean(10^(Li/10)) )` |
| `AirborneInsulationResult` | `dataclass` | **Field insulation per band.**
• `d`: Level difference D [dB]
• `dnt`: Standardized DnT [dB]
• `r_prime`: Apparent R' [dB] or None | `res.d, res.dnt, res.r_prime` |
| `WeightedRatingResult` | `dataclass` | **Weighted rating result.**
• `rating`: Rw/DnT,w … [dB], int
• `c`: Spectrum term C, int
• `ctr`: Spectrum term Ctr, int
• `unfavourable_sum`: [dB]
• `band_centers`: Measured-curve centres [Hz] or None
• `measured`: Measured band values [dB] or None
• `shifted_reference`: Shifted Table 3 reference [dB] or None | `w.rating, w.c, w.ctr` |
| `impact_insulation` | `function` | **Field impact insulation (ISO 16283-2).**
• `li`: Impact SPL [dB], 1D or (positions, bands)
• `t2`: Receiving-room T per band [s]
• `volume`: Receiving V [m³] (for L'n)
• `t0`: Reference T0 [s] (Default: 0.5) | `imp = impact_insulation(li, t2, volume=50)`
• `ImpactInsulationResult` (`l_n_t`, `l_n`) |
| `weighted_impact_rating` | `function` | **Single-number impact rating + CI (ISO 717-2).**
• `values_by_band`: 16 thirds (100-3150 Hz) or 5 octaves (125-2000 Hz) [dB]
• `bands`: 'third-octave', 'octave' or None | `r = weighted_impact_rating(imp.l_n_t)`
• `ImpactRatingResult` (Ln,w, CI); octave rating carries the -5 dB rule |
| `ImpactInsulationResult` | `dataclass` | **Impact insulation per band.**
• `l_n_t`: Standardized L'nT [dB]
• `l_n`: Normalized L'n [dB] or None | `imp.l_n_t, imp.l_n` |
| `ImpactRatingResult` | `dataclass` | **Weighted impact rating.**
• `rating`: Ln,w/L'n,w/L'nT,w [dB], int
• `ci`: Spectrum term CI, int
• `unfavourable_sum`: [dB]
• `band_centers`: Measured-curve centres [Hz] or None
• `measured`: Measured impact levels [dB] or None
• `shifted_reference`: Shifted impact reference [dB] or None | `r.rating, r.ci` |
| `facade_insulation` | `function` | **Field façade insulation (ISO 16283-3).**
• `l1_2m`/`l2`: Level 2 m in front / receiving levels [dB], 1D or (positions, bands)
• `t2`: Receiving-room T per band [s]
• `area`: Element S [m²], `volume`: Receiving V [m³], `surface_level`: L1,s [dB] (all three for R')
• `method`: 'loudspeaker' (−1.5 dB) / 'road_traffic' (−3 dB)
• `t0`: Reference T0 [s] (Default: 0.5)
• `frequencies` [Hz] | `fac = facade_insulation(l1_2m, l2, t2, volume=50, area=11.5, surface_level=ls)`
• `FacadeInsulationResult` |
| `FacadeInsulationResult` | `dataclass` | **Façade insulation per band.**
• `d_2m`: Level difference D2m [dB]
• `d_2m_nt`: Standardized D2m,nT [dB]
• `d_2m_n`: Normalized D2m,n [dB] or None
• `r_prime`: Apparent R'45°/R'tr,s [dB] or None
• `frequencies` [Hz] or None
• `.plot()` | `fac.d_2m_nt, fac.r_prime` |
| `lab_airborne_insulation` | `function` | **Laboratory airborne insulation (ISO 10140-2).**
• `l1`/`l2`: Source/receiving levels [dB], 1D or (positions, bands)
• `t2`: Receiving-room T per band [s]
• `area`: Free test-opening S [m²]
• `volume`: Receiving V [m³] | `lab = lab_airborne_insulation(l1, l2, t2, area=10, volume=50)`
• `LabAirborneInsulationResult` |
| `lab_impact_insulation` | `function` | **Laboratory impact insulation (ISO 10140-3).**
• `li`: Tapping-machine impact SPL [dB], 1D or (positions, bands)
• `t2`: Receiving-room T per band [s]
• `volume`: Receiving V [m³] | `imp = lab_impact_insulation(li, t2, volume=50)`
• `LabImpactInsulationResult` |
| `background_correction` | `function` | **Background-noise correction (ISO 10140-4 §4.3).**
• `signal_and_background`: Combined Lsb per band [dB]
• `background`: Lb per band [dB]
• 6–15 dB margin corrected, ≤6 dB capped at 1.3 dB, ≥15 dB unchanged | `L = background_correction(lsb, lb)`
• Corrected levels [dB] (`LabInsulationWarning` at the limit of measurement) |
| `LabAirborneInsulationResult` | `dataclass` | **Laboratory airborne result.**
• `r`: Sound reduction index R [dB]
• `absorption`: A = 0.16 V/T [m²]
• `rating`: `WeightedRatingResult` or None
• `.plot()` (needs the rating) | `lab.r, lab.rating.rating` |
| `LabImpactInsulationResult` | `dataclass` | **Laboratory impact result.**
• `l_n`: Normalized impact level Ln [dB]
• `absorption`: A [m²]
• `rating`: `ImpactRatingResult` or None
• `.plot()` (needs the rating) | `imp.l_n, imp.rating.rating` |
| `LabInsulationWarning` | `warning class` | **Limit-of-measurement condition (ISO 10140-4).**
Emitted by `background_correction` when a band's signal-to-background margin is ≤ 6 dB (fixed 1.3 dB cap applied) | `warnings.simplefilter('error', LabInsulationWarning)` |
| `predicted_airborne_insulation` | `function` | **Predicted apparent airborne R'w (EN 12354-1 Formula 26).**
• `r_direct`: Separating-element Rs,w [dB]
• `flanking_paths`: sequence of `FlankingPath` (Default: ())
• `delta_r_direct`: Lining ΔRDd,w [dB] (Default: 0) | `res = predicted_airborne_insulation(r_direct=57, flanking_paths=paths)`
• `AirbornePredictionResult` |
| `predicted_impact_insulation` | `function` | **Predicted apparent impact L'n,w (EN 12354-2 Formula 21).**
• `ln_w_eq`: Bare-floor equivalent Ln,w,eq [dB]
• `delta_l_w`: Covering improvement ΔLw [dB] (Default: 0)
• `k_correction`: Flanking K [dB] (Default: 0) | `imp = predicted_impact_insulation(ln_w_eq=76.2, delta_l_w=33, k_correction=2)`
• `ImpactPredictionResult` |
| `junction_vibration_reduction` | `function` | **Vibration reduction index Kij (EN 12354-1 Annex E).**
• `junction_type`: 'rigid_cross'/'rigid_t'/'flexible_t'/'lightweight_facade'
• `path`: 'through' (K13) / 'corner' (K12=K23)
• `mass_ratio`: m'⊥,i/m'i
• `frequency` [Hz] (Default: 500), `f1` [Hz] (Default: 125) | `k = junction_vibration_reduction('rigid_cross', 'through', 1.61)`
• Kij [dB] |
| `junction_min_vibration_reduction` | `function` | **Minimum Kij,min (EN 12354-1 Formula 29).**
• `coupling_length`: lf [m]
• `s_i`, `s_j`: Element areas [m²] | `kmin = junction_min_vibration_reduction(4.5, 11.5, 11.5)`
• Kij,min [dB] |
| `flanking_path` | `function` | **One flanking path Rij,w (EN 12354-1 Formula 28a).**
• `label`, `kind`: 'Ff'/'Df'/'Fd'
• `r_source`/`r_receive`: element indices [dB]
• `k_ij` [dB], `separating_area` Ss [m²], `coupling_length` lf [m]
• `delta_r` [dB] (Default: 0), `kij_min` [dB] clamp (Default: None) | `p = flanking_path(label='f', kind='Ff', r_source=49, r_receive=49, k_ij=12.4, separating_area=11.5, coupling_length=4.5)`
• `FlankingPath` |
| `flanking_element` | `function` | **The three paths (Ff, Df, Fd) of one flanking element.**
• `label`, `r_flanking`, `r_separating` [dB]
• `k_ff`/`k_fd`/`k_df` [dB]
• `separating_area` Ss [m²], `coupling_length` lf [m]
• `delta_r_ff`/`delta_r_fd`/`delta_r_df` [dB] (Default: 0) | `ff, df, fd = flanking_element(label='floor', r_flanking=49, r_separating=57, k_ff=12.4, k_fd=8.9, k_df=8.9, separating_area=11.5, coupling_length=4.5)` |
| `combine_linings` | `function` | **Combine two lining improvements (EN 12354-1 Formulas 30/31).**
• `delta_a`, `delta_b` [dB] (pass 0 for a single lining) | `dr = combine_linings(14.0, 14.0)`
• max(a,b) + min(a,b)/2 = 21.0 [dB] |
| `equivalent_impact_level` | `function` | **Bare-floor equivalent Ln,w,eq (EN 12354-2 Annex B).**
• `mass_per_area`: m' [kg/m²] | `lneq = equivalent_impact_level(322.0)`
• 164 − 35 lg(m') = 76.2 [dB] |
| `impact_flanking_correction` | `function` | **Flanking correction K (EN 12354-2 Table 1).**
• `separating_mass`, `flanking_mass` [kg/m²] (nearest tabulated) | `k = impact_flanking_correction(322.0, 145.0)`
• K = 2 [dB], int |
| `standardized_impact_level` | `function` | **Standardized L'nT,w (EN 12354-2 Formula 3).**
• `l_prime_n_w`: L'n,w [dB]
• `volume`: Receiving V [m³], V0 = 30 m³ | `lnt = standardized_impact_level(45.2, 50.0)`
• L'nT,w = 43.0 [dB] |
| `AirbornePredictionResult` | `dataclass` | **Predicted airborne insulation.**
• `r_prime_w`: Apparent R'w [dB]
• `r_direct_w`: Direct RDd,w [dB]
• `paths`: tuple of `PathContribution`
• `dominant`: highest-energy path | `res.r_prime_w, res.dominant.label` |
| `ImpactPredictionResult` | `dataclass` | **Predicted impact insulation.**
• `l_prime_n_w`: Apparent L'n,w [dB]
• `ln_w_eq`, `delta_l_w`, `k_correction` [dB] | `imp.l_prime_n_w` |
| `FlankingPath` | `dataclass` | **One flanking transmission path.**
• `label`, `kind`: 'Ff'/'Df'/'Fd'
• `r_ij_w`: Flanking index Rij,w [dB] | `p.r_ij_w` |
| `PathContribution` | `dataclass` | **A path with its energy share.**
• `label`, `kind`: 'Dd'/'Ff'/'Df'/'Fd'
• `r_w`: Path index [dB]
• `fraction`: share of transmitted energy (0–1) | `c.r_w, c.fraction` |
| `band_uncertainty` | `function` | **One-third-octave standard uncertainty u (ISO 12999-1 Tables 2/4/6).**
• `measurand`: 'airborne'/'impact'/'impact_reduction'
• `situation`: 'A'/'B'/'C'
• `upper_limit`: σR95 (airborne A, Annex D) (Default: False) | `u = band_uncertainty('airborne', 'B')`
• `BandUncertainty` |
| `single_number_uncertainty` | `function` | **Single-number standard uncertainty u (ISO 12999-1 Tables 3/5/7).**
• `quantity`: 'r_w'/'ln_w'/'delta_lw' (+ aliases, +c/+ctr variants)
• `situation`: 'A'/'B'/'C'
• `upper_limit` (Default: False) | `u = single_number_uncertainty('r_w', 'B')`
• u [dB] (0.9) |
| `single_number_uncertainty_uncorrelated` | `function` | **Uncorrelated single-number u from bands (ISO 12999-1 Formula B.2).**
• `band_uncertainties`: per-band u_i [dB]
• `reference_differences`: L_i − R_i [dB] | `u = single_number_uncertainty_uncorrelated(u_i, d_i)`
• Energy-weighted quadrature u [dB] |
| `maximum_repeatability_standard_deviation` | `function` | **Max repeatability σx per band (ISO 12999-1 Table 1).**
• (no parameters) | `b = maximum_repeatability_standard_deviation()`
• `BandUncertainty` (lab self-verification) |
| `coverage_factor` | `function` | **Coverage factor k (ISO 12999-1 Table 8).**
• `confidence`: fraction (Default: 0.95)
• `one_sided` (Default: False) | `k = coverage_factor(0.95)`
• 1.96 (two-sided) / 1.65 (one-sided) |
| `expanded_uncertainty` | `function` | **Expanded uncertainty U = k·u (ISO 12999-1 Formula 2).**
• `u` [dB]
• `coverage`: fraction (Default: 0.95)
• `one_sided` (Default: False); enforces k ≥ 1 | `U = expanded_uncertainty(0.9)`
• 1.764 [dB] |
| `uncertain_value` | `function` | **Attach U to a rating (ISO 12999-1 Clause 8).**
• `value` [dB], `quantity`, `situation`
• `coverage` (Default: 0.95), `one_sided` (Default: False), `upper_limit` (Default: False) | `uv = uncertain_value(52.0, 'rprime_w', 'B')`
• `UncertainValue` (value ± U) |
| `combine_uncertainties` | `function` | **Quadrature combination (ISO 12999-1 Formula C.2).**
• `*components`: non-negative u_i [dB] | `uc = combine_uncertainties(1.0, 0.6)`
• sqrt(Σ u_i²) = 1.166 [dB] |
| `prediction_input_uncertainty` | `function` | **Prediction input uncertainty (ISO 12999-1 Formula A.1).**
• `sigma_reproducibility`, `sigma_product` [dB]
• `n`: measurements (≥ 1) | `u = prediction_input_uncertainty(1.8, 1.0, 3)`
• sqrt((σR²+σp²)/n + σp²) [dB] |
| `reduce_by_independent_measurements` | `function` | **Reduce u by m measurements (ISO 12999-1 Formula A.7).**
• `u` [dB]
• `m`: independent measurements (≥ 1) | `ur = reduce_by_independent_measurements(1.0, 4)`
• u/√m = 0.5 [dB] |
| `satisfies_lower_requirement` | `function` | **Conformity to a minimum (ISO 12999-1 Formula 5).**
• `value`, `expanded_uncertainty_value`, `requirement` [dB] | `ok = satisfies_lower_requirement(52.0, 1.485, 50.0)`
• True when value − U > requirement |
| `satisfies_upper_requirement` | `function` | **Conformity to a maximum (ISO 12999-1 Formula 4).**
• `value`, `expanded_uncertainty_value`, `requirement` [dB] | `ok = satisfies_upper_requirement(45.0, 1.5, 50.0)`
• True when value + U < requirement |
| `BandUncertainty` | `dataclass` | **Per-band standard uncertainty (ISO 12999-1).**
• `measurand`, `situation`
• `frequencies` [Hz], `uncertainties` [dB]
• `upper_limit`: σR95 flag
• `.to_arrays()` | `b.frequencies, b.uncertainties` |
| `UncertainValue` | `dataclass` | **A value with its expanded uncertainty.**
• `value`, `standard_uncertainty`, `expanded_uncertainty` [dB]
• `coverage_factor`, `confidence`, `one_sided`
• `.lower` = y − U, `.upper` = y + U | `uv.lower, uv.upper` |
| `COVERAGE_FACTORS` | `mapping` | **Table 8 coverage factors (read-only).**
Keyed by `(confidence, one_sided)` → k | `COVERAGE_FACTORS[(0.95, False)] # 1.96` |
| `sound_power_pressure` | `function` | **Sound power from surface pressure (ISO 3744/3746).**
• `levels_positions`: (NM, NB) SPL [dB]
• `surface`: 'hemisphere' / 'box'
• `radius` [m] or `dimensions`+`distance` [m]
• `reflecting_planes`: 1/2/3 (Default: 1)
• `background_levels`: for K1
• `frequencies` [Hz]: for LWA
• `reverberation_time`+`room_volume` / `absorption_area` / `mean_absorption_coefficient`+`room_surface`: for K2
• `grade`: 'engineering' (Default) / 'survey'
• `omc_uncertainty` [dB] (Default: 0) | `res = sound_power_pressure(levels, 'hemisphere', radius=1.5, frequencies=f)`
• `SoundPowerResult` |
| `measurement_positions` | `function` | **Hemisphere mic coordinates (ISO 3744 Annex B).**
• `surface`: 'hemisphere'
• `radius` [m]
• `reflecting_planes`: 1/2/3
• `tones`: Table B.1 vs B.2 (Default: True)
• `grade`: 'engineering'/'survey' | `xyz = measurement_positions('hemisphere', radius=1.5)`
• (N, 3) coordinates [m] |
| `background_noise_correction` | `function` | **Background correction K1 (ISO 3744 Eq. 16).**
• `source_levels` [dB]
• `background_levels` [dB]
• `grade`: 'engineering'/'survey' | `k1 = background_noise_correction(src, bg)`
• K1 per band [dB] |
| `environmental_correction` | `function` | **Environmental correction K2 (ISO 3744 Eq. A.2).**
• `surface_area` S [m²]
• `absorption_area` A, or `reverberation_time`+`room_volume`, or `mean_absorption_coefficient`+`room_surface` | `k2 = environmental_correction(14.1, reverberation_time=0.6, room_volume=300)`
• K2 [dB] |
| `SoundPowerResult` | `dataclass` | **Surface-pressure sound power.**
• `sound_power_level` [dB]
• `surface_pressure_level`, `mean_pressure_level` [dB]
• `background_correction`, `environmental_correction` [dB]
• `directivity_index` [dB] `(NM, NB)`
• `surface_area` [m²]
• `sound_power_level_a` [dB]
• `uncertainty` [dB]
• `grade` | `res.sound_power_level, res.sound_power_level_a` |
| `sound_power_reverberation` | `function` | **Reverberation-room LW, direct (ISO 3741).**
• `levels`: mean room SPL [dB] (1D or (NM, NB))
• `t60` [s]
• `volume` V [m³]
• `surface_area` S [m²]
• `frequencies` [Hz] (required)
• `background_levels`: for K1
• `temperature` [°C] (Default: 23)
• `static_pressure` [kPa] (Default: 101.325) | `rev = sound_power_reverberation(lp, t60, 200, 220, f)`
• `ReverberationSoundPowerResult` |
| `sound_power_comparison` | `function` | **Reverberation-room LW, comparison (ISO 3741).**
• `levels`, `levels_ref`: room SPL [dB]
• `lw_ref`: reference-source LW [dB]
• `frequencies` [Hz]
• `background_levels`, `background_levels_ref`
• `temperature`, `static_pressure` | `cmp = sound_power_comparison(lp, lp_ref, lw_ref)`
• `ReverberationSoundPowerResult` (method='comparison') |
| `ReverberationSoundPowerResult` | `dataclass` | **Reverberation-room sound power.**
• `frequencies` [Hz] (or `None`)
• `sound_power_level` [dB]
• `mean_pressure_level` [dB]
• `absorption_area` [m²]
• `waterhouse_correction` [dB]
• `background_correction`, `c1`, `c2` [dB]
• `speed_of_sound` [m/s]
• `sound_power_level_a` [dB]
• `method` | `rev.sound_power_level, rev.waterhouse_correction` |
| `sound_power_intensity` | `function` | **Sound power by intensity scanning (ISO 9614-2).**
• `normal_intensity`: (N_seg, N_bands) [W/m²]
• `areas`: segment Si [m²]
• `normal_intensity_2`: 2nd sweep (criterion 3)
• `pressure_levels`: for FpI
• `pressure_residual_index`: δpI0 [dB]
• `frequencies` [Hz]
• `band_type`: 'third' (Default)/'octave'
• `grade`: 'engineering'/'survey'
• `repeatability_limit`: override s | `ir = sound_power_intensity(scan1, areas, frequencies=f, band_type='octave')`
• `SoundPowerIntensityResult` |
| `SoundPowerIntensityResult` | `dataclass` | **Scanning sound power.**
• `partial_power`, `partial_power_level`
• `sound_power`, `sound_power_level` [dB] (NaN where `negative_band`)
• `negative_band`: per-band bool (True where P ≤ 0)
• `surface_pressure_intensity_index` (FpI)
• `negative_partial_power_index` (F+/-)
• `repeatability`, `dynamic_capability_index` (Ld)
• `achieved_grade`
• `surface_area`, `sound_power_level_a`, `grade` | `ir.sound_power_level, ir.achieved_grade` |
| `absorption_area` | `function` | **Equivalent absorption area (ISO 354 Eq. 5/7).**
• `t60`: T [s]
• `volume` V [m³]
• `temperature` [°C] (Default: 20)
• `speed_of_sound` [m/s] (overrides temperature)
• `m`: air attenuation [1/m] (Default: 0) | `A = absorption_area(t60, volume=200)`
• A [m²] |
| `absorption_coefficient` | `function` | **Sound absorption coefficient (ISO 354 Eq. 9).**
• `t1`, `t2`: empty / with-specimen T [s]
• `volume` V [m³]
• `sample_area` S [m²]
• `temperature1`/`temperature2` [°C]
• `speed_of_sound1`/`2`, `m1`/`m2` | `a = absorption_coefficient(t1, t2, 200, 10.8)`
• α_s (unclamped, may exceed 1) |
| `attenuation_from_alpha` | `function` | **ISO 9613-1 α → m (ISO 354 8.1.2.1).**
• `alpha`: attenuation [dB/m] | `m = attenuation_from_alpha(0.01)`
• m = α/(10 lg e) [1/m] |
| `air_attenuation` | `function` | **Atmospheric attenuation coefficient α (ISO 9613-1 Eq. 5).**
• `frequencies` [Hz]
• `temperature` [°C] (Default: 20)
• `relative_humidity` [%] (Default: 50)
• `pressure` [kPa] (Default: 101.325)
• `exact_midband`: snap to Table 1 midbands (Default: False) | `a = air_attenuation([1000, 4000], 20, 50)`
• α [dB/m] (×1000 = dB/km); out-of-range warns |
| `air_attenuation_m` | `function` | **ISO 354 power attenuation m from conditions (ISO 9613-1 + ISO 354).**
• Same parameters as `air_attenuation` | `m = air_attenuation_m([1000, 4000], 20, 50)`
• m = α/(10 lg e) [1/m] |
| `AtmosphericAbsorptionWarning` | `warning class` | **ISO 9613-1 out-of-range advisory.**
Emitted by `air_attenuation` when temperature/humidity/frequency leave the tabulated ranges or pressure exceeds 200 kPa; the result still returns | `warnings.simplefilter('error', AtmosphericAbsorptionWarning)` |
| `geometric_divergence` | `function` | **Geometrical divergence Adiv (ISO 9613-2 Eq. 7).**
• `distance` d [m] | `a = geometric_divergence(100.0)`
• 20 lg(d/d₀) + 11 = 51 dB at 100 m |
| `atmospheric_absorption` | `function` | **Atmospheric absorption term Aatm (ISO 9613-2 Eq. 8).**
• `distance` d [m]
• `frequencies` [Hz]
• `temperature`/`humidity`/`pressure` | `aatm = atmospheric_absorption(200, bands)`
• α·d per band [dB] |
| `ground_attenuation` | `function` | **Ground effect Agr, general method (ISO 9613-2 7.3.1, Eq. 9).**
• `distance` d, `source_height` hs, `receiver_height` hr [m]
• `frequencies` [Hz]
• `ground_source`/`ground_middle`/`ground_receiver` G ∈ [0,1]
• `projected_distance` dp [m] | `agr = ground_attenuation(200, 2, 2, bands, 1, 1, 1)`
• As+Ar+Am per band [dB] (negative = gain) |
| `ground_attenuation_alternative` | `function` | **Ground effect Agr, A-weighted method (ISO 9613-2 7.3.2, Eq. 10).**
• `distance` d [m]
• `mean_height` hm [m] | `agr = ground_attenuation_alternative(200, 2)`
• 4.8 − (2hm/d)·(17+300/d) ≥ 0 [dB] |
| `directivity_omega` | `function` | **Solid-angle directivity index DΩ (ISO 9613-2 Eq. 11).**
• `source_height` hs, `receiver_height` hr, `projected_distance` dp [m] | `dw = directivity_omega(1.5, 1.5, 200)`
• 0…~3 dB (add to Dc for the 7.3.2 method) |
| `Barrier` | `dataclass` | **Barrier diffraction geometry (ISO 9613-2 7.4).**
• `source_to_edge` dss, `edge_to_receiver` dsr [m]
• `parallel_distance` a [m] (Default: 0)
• `edge_separation` e [m] (Default: None → single diffraction)
• `ground_reflections_by_image` (Default: False → C₂=20)
• `lateral` (Default: False → top-edge) | `b = Barrier(source_to_edge=101, edge_to_receiver=101)`
• `.is_double` when e is given |
| `barrier_attenuation` | `function` | **Barrier diffraction Dz (ISO 9613-2 Eq. 14).**
• `barrier`: `Barrier`
• `distance` d [m]
• `frequencies` [Hz] | `dz = barrier_attenuation(b, 200, bands)`
• 10 lg[3+(C₂/λ)C₃ z Kmet], capped 20/25 dB |
| `meteorological_correction` | `function` | **Meteorological correction Cmet (ISO 9613-2 Eq. 21/22).**
• `projected_distance` dp, `source_height` hs, `receiver_height` hr [m]
• `c0`: factor C₀ [dB] | `c = meteorological_correction(200, 1.5, 1.5, 2.0)`
• C₀[1 − 10(hs+hr)/dp] ≥ 0 [dB] |
| `outdoor_propagation_attenuation` | `function` | **Total octave-band attenuation A (ISO 9613-2 Eq. 4).**
• `distance` d, `source_height` hs, `receiver_height` hr [m]
• `frequencies` [Hz]
• `ground_source`/`ground_middle`/`ground_receiver` G
• `barrier`: `Barrier` or None
• `temperature`/`humidity`/`pressure` (Default: 20 °C/70 %/101.325 kPa, a Table 2 reference atmosphere)
• `projected_distance` dp [m] | `att = outdoor_propagation_attenuation(200, 2, 2, bands, 1, 1, 1)`
• `OutdoorAttenuation` term breakdown |
| `predicted_receiver_level` | `function` | **Predicted octave-band receiver level (ISO 9613-2 Eq. 3/6).**
• `sound_power_level` Lw [dB]
• same geometry/ground/barrier/atmosphere params as `outdoor_propagation_attenuation`
• `directivity_index` Di, `d_omega` DΩ [dB]
• `c0`: subtract Cmet (Default: None) | `lp = predicted_receiver_level(lw, 200, 2, 2, bands)`
• LfT(DW) = Lw + Dc − A per band [dB] |
| `OutdoorAttenuation` | `dataclass` | **Per-band ISO 9613-2 attenuation breakdown.**
• `frequencies` [Hz]
• `a_div`, `a_atm`, `a_gr`, `a_bar` [dB]
• `a_total` = Adiv+Aatm+Agr+Abar [dB]
• `d_omega` [dB] | `att.a_div, att.a_bar, att.a_total` |
| `DEFAULT_FREQUENCIES` | `tuple` | **ISO 9613-2 nominal octave bands.**
(no parameters) | `DEFAULT_FREQUENCIES # (63, …, 8000)` |
| `task_based_exposure` | `function` | **Task-based daily exposure LEX,8h + U (ISO 9612 Clause 9).**
• `tasks`: sequence of `Task`
• `instrument`: 'class1'/'class2'/'personal_exposimeter' (Default)
• `u3` [dB] (Default: 1.0)
• `include_duration_uncertainty` (Default: True)
• `warn` (Default: True) | `res = task_based_exposure(tasks)`
• `ExposureResult` with per-task breakdown |
| `job_based_exposure` | `function` | **Job-based daily exposure LEX,8h + U (ISO 9612 Clause 10).**
• `samples` Lp,A,eqT [dB]
• `effective_duration_hours` Te [h]
• `instrument`, `u3`
• `n_workers`/`sample_duration_hours`: Table 1 check | `res = job_based_exposure(samples, 7.5)`
• `ExposureResult` (Eq C.9 / Table C.4 budget) |
| `full_day_exposure` | `function` | **Full-day daily exposure LEX,8h + U (ISO 9612 Clause 11).**
• `samples` whole-day Lp,A,eqT [dB]
• `effective_duration_hours` Te [h]
• `instrument`, `u3`, `warn` | `res = full_day_exposure(samples, 9.25)`
• `ExposureResult`; 3 samples spanning ≥3 dB advise |
| `Task` | `dataclass` | **One task of a task-based measurement (ISO 9612 Clause 9).**
• `samples` [dB], `duration_hours` [h]
• `duration_samples`/`duration_range` (for u1b)
• `label`, `instrument` | `Task(samples=(80.1, 82.2), duration_hours=5.0)` |
| `ExposureResult` | `dataclass` | **Daily exposure and uncertainty (ISO 9612).**
• `lex_8h` [dB]
• `combined_standard_uncertainty` u [dB]
• `expanded_uncertainty` U = 1.65 u [dB]
• `upper_limit` = LEX,8h + U [dB]
• `strategy`, `sampling_advisory`, `tasks` | `res.lex_8h, res.upper_limit` |
| `TaskContribution` | `dataclass` | **Per-task breakdown inside `ExposureResult.tasks` (ISO 9612 Clause 9).**
• `label`, `lp_aeqt` (Eq. 7), `duration_hours`
• `lex_8h_contribution` (Eq. 8) [dB]
• uncertainty terms `u1a`, `u1b`, `c1a`, `c1b`, `u2`, `u3` | `res.tasks[0].lex_8h_contribution` |
| `table_c4_contribution` | `function` | **Sampling contribution c₁u₁ [dB] from Table C.4 (ISO 9612 job/full-day).**
• `n_samples`: N (clamped to [3, 30])
• `u1`: sampling standard uncertainty [dB]
• bilinear interpolation, anchored at u₁ = 0 | `table_c4_contribution(6, 2.0) # 1.4` |
| `minimum_cumulative_duration_hours` | `function` | **Minimum cumulative measurement duration [h] (ISO 9612 Table 1).**
• `n_workers`: group size n_G (> 40 → 17 h; the standard advises splitting the group) | `minimum_cumulative_duration_hours(18) # 10.75` |
| `COVERAGE_FACTOR` | `float` | **ISO 9612 coverage factor k = 1.65 (Clause 14).**
One-sided 95 % confidence: U = 1.65 u, upper limit LEX,8h + U | `COVERAGE_FACTOR # 1.65` |
| `INSTRUMENT_U2` | `mapping` | **Instrument standard uncertainty u2 [dB] (ISO 9612 Table C.5).**
Keyed by `'class1'` (0.7), `'class2'` (1.5), `'personal_exposimeter'` (1.5) | `INSTRUMENT_U2['class1'] # 0.7` |
| `ExposureWarning` | `warning class` | **ISO 9612 sampling advisory.**
Emitted for the 3 dB task spread (Clause 9.3), c₁u₁ > 3.5 dB (Clause 10.4) or a short Table 1 cumulative duration | `warnings.simplefilter('error', ExposureWarning)` |
| `SoundPowerWarning` | `warning class` | **ISO 3744/3746/3741/9614-2 qualification issue.**
Emitted when the background margin is below the criterion, K2 exceeds the validity limit, a band's power is negative, or the room fails qualification; levels are then upper bounds | `warnings.simplefilter('error', SoundPowerWarning)` |
| `AbsorptionWarning` | `warning class` | **ISO 354 advisory.**
Emitted for a room below 150 m³, a sample area outside 10-12 m², an out-of-range temperature, or a non-physical α_s ≤ 0; the result still returns | `warnings.simplefilter('error', AbsorptionWarning)` |
| `.plot()` | `method` | **One-line canonical figure on every result object (soft matplotlib dependency).**
Available on `ZwickerLoudness`, `MooreGlasbergLoudness`, `MooreGlasbergTimeVaryingLoudness`, `EcmaLoudness`, `EcmaTonality`, `EcmaRoughness`, `STIResult`, `RoomAcousticsResult`, `DecayCurve`, `WeightedRatingResult`, `ImpactRatingResult`, `FacadeInsulationResult`, `LabAirborneInsulationResult`, `LabImpactInsulationResult`, `SoundPowerResult`, `ReverberationSoundPowerResult`, `SoundPowerIntensityResult` and `IntensityResult`.
• `ax`: existing Axes, or None to build a fresh figure (Default: None)
• returns the Matplotlib `Axes` (an array of Axes for multi-panel figures); never calls `plt.show()`
• needs matplotlib (`pip install phonometry[plot]`) | `res.plot()`
`decay_curve(ir, fs).plot()` |
## Notes
- `zero_phase=True` (in `OctaveFilterBank.filter` and `spectrogram`) filters
forward-backward (`sosfiltfilt`): no group delay, doubled effective
attenuation, offline analysis only. Incompatible with `stateful=True`. The
passband also narrows, lowering the measured broadband band level by ~0.2 to
0.3 dB per band (a pure in-band tone is unaffected); prefer forward filtering
when the absolute band SPL must match single-pass conventions, and reserve
zero-phase for when the temporal envelope matters (e.g. reverberation decay).
- `mode='peak'` includes the filter's onset transient; a tone that starts
abruptly can overshoot by ~1 dB. See [Calibration and dBFS](calibration.md).
- `octavefilter()` caches filter bank designs internally (32 entries), so
repeated calls with the same parameters skip the design phase. For explicit
control use `OctaveFilterBank`.