Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/jmrplens/phonometry. Standards-conformant acoustics library for Python: measurement and metrology, docs.jmrp.io/phonometry
Something went wrong. Try again.
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] (for cheby2/ellip) |
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] |
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 blocktw.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 |
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] |
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: ... |
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) |
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] |
Notes #
zero_phase=True(inOctaveFilterBank.filterandspectrogram) filters forward-backward (sosfiltfilt): no group delay, doubled effective attenuation, offline analysis only. Incompatible withstateful=True.mode='peak'includes the filter's onset transient; a tone that starts abruptly can overshoot by ~1 dB. See Calibration and dBFS.octavefilter()caches filter bank designs internally (32 entries), so repeated calls with the same parameters skip the design phase. For explicit control useOctaveFilterBank.