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.
phonometry generate_graphs.py
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426import osimport sysfrom typing import Any
import matplotlib.pyplot as pltimport numpy as npfrom scipy import signal as scipy_signal
# Add src to path to use the local packagesys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "src")))
from phonometry import OctaveFilterBank
# Constants for professional styling# ---------------------------------------------------------------------------# Language support: every figure is also generated in Spanish ("_es" suffix).# Translation happens at savefig time by walking the figure's Text artists,# so the generator functions stay single-language (English) internally._LANG = "en"_LANG_SUFFIX = ""
_ES_EXACT = { "Frequency [Hz]": "Frecuencia [Hz]", "Level [dB]": "Nivel [dB]", "Time [s]": "Tiempo [s]", "Amplitude": "Amplitud", "Amplitude [dB]": "Amplitud [dB]", "Error [dB]": "Error [dB]", "Group delay [ms]": "Retardo de grupo [ms]", "Level re steady state [dB]": "Nivel re estado estacionario [dB]", "Normalized Response": "Respuesta normalizada", "Normalized frequency f / fm": "Frecuencia normalizada f / fm", "Relative attenuation \u0394A [dB]": "Atenuaci\u00f3n relativa \u0394A [dB]", "Sound pressure level [dB re 20 \u00b5Pa]": "Nivel de presi\u00f3n sonora [dB re 20 \u00b5Pa]", "1/1 Octave Band Analysis": "An\u00e1lisis en bandas de octava 1/1", "1/3 Octave Band Analysis": "An\u00e1lisis en bandas de octava 1/3", "1/3 Octave Spectrogram (Fast windows, 50% overlap)": "Espectrograma 1/3 de octava (ventanas Fast, 50 % de solape)", "4 kHz Toneburst Response vs IEC 61672-1 Table 4 (FAST)": "Respuesta a r\u00e1fagas de 4 kHz vs Tabla 4 de IEC 61672-1 (FAST)", "A-Weighting": "Ponderaci\u00f3n A", "C-Weighting": "Ponderaci\u00f3n C", "Z-Weighting (Flat)": "Ponderaci\u00f3n Z (plana)", "G-weighting (ISO 7196)": "Ponderaci\u00f3n G (ISO 7196)", "G Frequency Weighting for Infrasound (ISO 7196:1995)": "Ponderaci\u00f3n frecuencial G para infrasonido (ISO 7196:1995)", "Bessel": "Bessel", "Bilinear error": "Error del dise\u00f1o bilineal", "Butterworth": "Butterworth", "Butterworth (Flat)": "Butterworth (plano)", "Butterworth order 6 (1 kHz octave band)": "Butterworth de orden 6 (banda de octava de 1 kHz)", "Causal filtering (group delay)": "Filtrado causal (retardo de grupo)", "Chebyshev I": "Chebyshev I", "Chebyshev II": "Chebyshev II", "Class 1 lower limit @ 12.5 kHz": "L\u00edmite inferior de clase 1 @ 12,5 kHz", "Class 2 minimum attenuation": "Atenuaci\u00f3n m\u00ednima de clase 2", "Continuous (whole signal)": "Continuo (se\u00f1al completa)", "Elliptic": "El\u00edptico", "FAST envelope": "Envolvente FAST", "Fast (125ms)": "Fast (125 ms)", "Fast level $L_p(t)$": "Nivel Fast $L_p(t)$", "Filter Architecture Comparison (Order 6, 1kHz Band)": "Comparativa de arquitecturas de filtro (orden 6, banda de 1 kHz)", "Filter Bank Frequency Response": "Respuesta en frecuencia del banco de filtros", "Forbidden for class 1 (too little attenuation)": "Prohibido para clase 1 (atenuaci\u00f3n insuficiente)", "Forbidden for class 1 (too much attenuation)": "Prohibido para clase 1 (atenuaci\u00f3n excesiva)", "Frequency Weighting Curves (IEC 61672-1)": "Curvas de ponderaci\u00f3n frecuencial (IEC 61672-1)", "Group Delay Comparison (1 kHz Octave Band, Order 6)": "Comparativa de retardo de grupo (banda de 1 kHz, orden 6)", "Hearing threshold $T_f$ (Table 1)": "Umbral de audici\u00f3n $T_f$ (Tabla 1)", "High Pass (LR4)": "Paso alto (LR4)", "IEC 61672-1 analytic curve": "Curva anal\u00edtica IEC 61672-1", "ISO 7196 Table 2 nominals": "Nominales de la Tabla 2 de ISO 7196", "Impulse (35ms/1.5s)": "Impulse (35 ms/1,5 s)", "Independent blocks (state reset)": "Bloques independientes (estado reiniciado)", "Input Burst (Normalized)": "R\u00e1faga de entrada (normalizada)", "Input burst (250 Hz)": "R\u00e1faga de entrada (250 Hz)", "Left Channel: Pink Noise": "Canal izquierdo: ruido rosa", "Linkwitz-Riley Crossover (4th Order @ 1kHz)": "Crossover Linkwitz-Riley (4\u00ba orden @ 1 kHz)", "Low Pass (LR4)": "Paso bajo (LR4)", "Multichannel Analysis (Stereo Input)": "An\u00e1lisis multicanal (entrada est\u00e9reo)", "No state: each block restarts the filter transient": "Sin estado: cada bloque reinicia el transitorio del filtro", "Normal Equal-Loudness-Level Contours (ISO 226:2023)": "L\u00edneas isof\u00f3nicas normales (ISO 226:2023)", "Original Signal (250 Hz + 1000 Hz Sum) @ 48 kHz": "Se\u00f1al original (suma de 250 Hz + 1000 Hz) @ 48 kHz", "Oversampled (high_accuracy=True)": "Sobremuestreado (high_accuracy=True)", "Plain bilinear (high_accuracy=False)": "Bilineal simple (high_accuracy=False)", "Raw PSD": "PSD sin filtrar", "Raw Signal Spectrum (PSD)": "Espectro de la se\u00f1al (PSD)", "Relative Attenuation vs IEC 61260-1:2014 Class Limits": "Atenuaci\u00f3n relativa vs l\u00edmites de clase de IEC 61260-1:2014", "Right Channel: Log Sine Sweep": "Canal derecho: barrido senoidal logar\u00edtmico", "Slow (1000ms)": "Slow (1000 ms)", "Stateful blocks (state carried)": "Bloques con estado (estado conservado)", "Statistical Levels L10 / L50 / L90 (Fast envelope)": "Niveles estad\u00edsticos L10 / L50 / L90 (envolvente Fast)", "Sum (Flat)": "Suma (plana)", "Time Weighting Ballistics (IEC 61672-1)": "Ponderaci\u00f3n temporal F/S/I (IEC 61672-1)", "Zero-Phase Filtering: Group Delay Elimination (250 Hz Band)": "Filtrado de fase cero: eliminaci\u00f3n del retardo de grupo (banda de 250 Hz)", "Zoom at -3 dB (Log Scale)": "Zoom en -3 dB (escala log)", "Zoom: A-weighting is positive (max +1.27 dB @ 2.5 kHz)": "Zoom: la ponderaci\u00f3n A es positiva (m\u00e1x +1,27 dB @ 2,5 kHz)", "block boundary:\nfilter transient restarts": "frontera de bloque:\nse reinicia el transitorio del filtro", "high_accuracy error": "Error con high_accuracy", "stateful=True: block outputs equal the continuous result": "stateful=True: los bloques igualan el resultado continuo", "zero_phase=True (aligned)": "zero_phase=True (alineado)", "0 dB @ 10 Hz": "0 dB @ 10 Hz", "Stable tone (good coupling)": "Tono estable (buen acoplamiento)", "3% AM tone (loose coupling)": "Tono con AM del 3 % (acoplamiento flojo)", "IEC 60942:2017 class 1 limit (deviation from mean)": "L\u00edmite de clase 1 de IEC 60942:2017 (desviaci\u00f3n de la media)", "Calibration Tone Stability Check (IEC 60942:2017, 5.3.3)": "Comprobaci\u00f3n de estabilidad del tono de calibraci\u00f3n (IEC 60942:2017, 5.3.3)", "F-weighted level re mean [dB]": "Nivel con ponderaci\u00f3n F re media [dB]", "Fast level of the event": "Nivel Fast del evento", "Leq over the whole event": "Leq de todo el evento", "SEL: same energy in 1 s": "SEL: la misma energ\u00eda en 1 s", "equal energy": "igual energ\u00eda", "Sound Exposure Level: the event normalized to 1 s": "Nivel de exposici\u00f3n sonora: el evento normalizado a 1 s", "Level [dBFS]": "Nivel [dBFS]", "Hourly LAeq": "LAeq horario", "Lday (+0 dB)": "Ld\u00eda (+0 dB)", "Levening + 5 dB": "Ltarde + 5 dB", "Lnight + 10 dB": "Lnoche + 10 dB", "Day-Evening-Night Level Lden (ISO 1996-1)": "Nivel d\u00eda-tarde-noche Lden (ISO 1996-1)", "Hour of day": "Hora del d\u00eda", "Averaged FFT spectrum (Hann)": "Espectro FFT promediado (Hann)", "Critical band around the tone": "Banda cr\u00edtica en torno al tono", "Tone-to-Noise Ratio (ECMA-418-1, clause 11)": "Relaci\u00f3n tono-ruido (ECMA-418-1, apartado 11)", "Bin power [dB]": "Potencia por bin [dB]",}
_ES_PATTERNS = [ (r"^Octave Band: (.+) Hz$", r"Banda de octava: \1 Hz"), (r"^(\d+) phon$", r"\1 fonios"), (r"^TNR = (.+) dB\n\(criterion (.+) dB\)$", "TNR = \\1 dB\\n(criterio \\2 dB)"), (r"^Measured 1/(\d+) Octave Bands$", r"Bandas de 1/\1 de octava medidas"), (r"^IEC target (.+) dB$", r"Objetivo IEC \1 dB"), (r"^([\d.]+) ms burst$", "R\u00e1faga de \\1 ms"), (r"^A-Weighting High-Frequency Accuracy @ fs=(\d+) kHz$", "Precisi\u00f3n en alta frecuencia de la ponderaci\u00f3n A @ fs=\\1 kHz"), (r"^Impulse Response \((.+) Hz Band\) - Transient/Stability Comparison$", "Respuesta al impulso (banda de \\1 Hz) \u2014 transitorio y estabilidad"),]
def set_lang(lang: str) -> None: """Switch the output language ('en' or 'es').""" global _LANG, _LANG_SUFFIX _LANG = lang _LANG_SUFFIX = "" if lang == "en" else f"_{lang}"
def _translate_figure(fig: Any) -> None: """Rewrite every Text artist of *fig* into the active language.""" import re as _re
import matplotlib.text as _mtext
if _LANG == "en": return import re as _re2
from matplotlib.ticker import FixedFormatter as _FxF from matplotlib.ticker import FuncFormatter as _FF from matplotlib.ticker import ScalarFormatter as _SF
def _comma(s: str) -> str: return _re2.sub(r"(?<![\d.])(\d+)\.(\d+)(?![.\d])", r"\1,\2", s)
for ax in fig.get_axes(): for axis in (ax.xaxis, ax.yaxis): fmt = axis.get_major_formatter() if isinstance(fmt, _FxF): fmt.seq = [_comma(s) for s in fmt.seq] elif isinstance(fmt, _FF) and not getattr(fmt, "_phonometry_comma", False): wrapped = _FF(lambda v, pos, _f=fmt: _comma(str(_f(v, pos)))) wrapped._phonometry_comma = True # type: ignore[attr-defined] axis.set_major_formatter(wrapped) elif type(fmt) is _SF and axis.get_scale() == "linear": wrapped = _FF(lambda v, pos: _comma(f"{v:g}")) axis.set_major_formatter(wrapped) for artist in fig.findobj(_mtext.Text): s = artist.get_text() if not s: continue if s in _ES_EXACT: artist.set_text(_ES_EXACT[s]) else: for pat, repl in _ES_PATTERNS: new, n = _re.subn(pat, repl, s) if n: artist.set_text(new) break # Spanish decimal comma, applied uniformly to every text artist # (tick labels included) except code identifiers and mathtext. s = artist.get_text() if s and "$" not in s and "_" not in s and _re.search(r"\d\.\d", s): # Clause/version numbers like 5.3.3 keep their dots. artist.set_text(_re.sub(r"(?<![\d.])(\d+)\.(\d+)(?![.\d])", r"\1,\2", s))
LABEL_FREQ_HZ = "Frequency [Hz]"LABEL_LEVEL_DB = "Level [dB]"COLOR_PRIMARY = "#1f77b4"COLOR_SECONDARY = "#d62728"COLOR_TERTIARY = "#2ca02c"COLOR_GRID = "#e0e0e0"
# Theme state: every figure is generated twice (light + "_dark" suffix).# COLOR_FG replaces literal black so annotations stay visible on dark bg.COLOR_FG = "black"_FILENAME_SUFFIX = ""
# Global matplotlib configurationplt.rcParams.update( { "font.size": 10, "axes.grid": True, "grid.alpha": 0.5, "grid.linestyle": "--", "figure.figsize": (10, 6), "figure.dpi": 150, "savefig.bbox": "tight", })
def set_theme(dark: bool) -> None: """Switch between the light (default) and dark documentation themes.""" global COLOR_FG, COLOR_GRID, _FILENAME_SUFFIX if dark: plt.style.use("dark_background") COLOR_FG = "white" COLOR_GRID = "#555555" _FILENAME_SUFFIX = "_dark" else: plt.style.use("default") COLOR_FG = "black" COLOR_GRID = "#e0e0e0" _FILENAME_SUFFIX = "" plt.rcParams.update( { "font.size": 10, "axes.grid": True, "grid.alpha": 0.5, "grid.linestyle": "--", "figure.figsize": (10, 6), "figure.dpi": 150, "savefig.bbox": "tight", } )
def themed_path(output_dir: str, filename: str) -> str: """Return the output path for *filename*, adding language + theme suffixes.
Also translates the current figure's text artists into the active language: every generator calls ``plt.savefig(themed_path(...))``, so this runs right before each save without patching matplotlib globally. """ _translate_figure(plt.gcf()) stem, ext = os.path.splitext(filename) return os.path.join(output_dir, f"{stem}{_LANG_SUFFIX}{_FILENAME_SUFFIX}{ext}")
def apply_axis_styling(ax: Any, title: str, xlim: tuple[float, float] | None = None, ylim: tuple[float, float] | None = None) -> None: """Apply consistent styling to plots.""" ax.set_title(title, fontweight="bold", pad=12) ax.set_xlabel(LABEL_FREQ_HZ) ax.set_ylabel(LABEL_LEVEL_DB) ax.grid(which="major", color=COLOR_GRID, linestyle="-") ax.grid(which="minor", color=COLOR_GRID, linestyle=":", alpha=0.4)
if xlim: ax.set_xlim(xlim) if ylim: ax.set_ylim(ylim)
# Standard Octave Ticks xticks = [16, 31.5, 63, 125, 250, 500, 1000, 2000, 4000, 8000, 16000] xticklabels = ["16", "31.5", "63", "125", "250", "500", "1k", "2k", "4k", "8k", "16k"] ax.set_xticks(xticks) ax.set_xticklabels(xticklabels)
def plot_psd(ax: Any, x: np.ndarray, fs: int, label: str = "Raw Signal PSD", color: str = "gray", alpha: float = 0.3) -> None: """Calculate and plot the Power Spectral Density of the raw signal.""" # Use Welch's method for a smooth PSD estimate f, Pxx = scipy_signal.welch(x, fs, nperseg=4096) # Convert to dB (relative to max to match SPL scale roughly or just show shape) # Since SPL is calibrated differently, we just want to show the 'shape' of the spectrum # in the background. We can normalize Pxx to match the peak of the octave bands roughly # or just plot it as is if we had calibrated units. # Here we'll just plot relative dB # Avoid log(0) Pxx_db = 10 * np.log10(Pxx + 1e-12) # Normalize PSD peak to 0 dB for visualization shape, then shift down? # Or better: don't normalize, just plot. But PSD density vs Octave Band Power (integrated) # are different units (dB/Hz vs dB). # So we will plot it on a secondary Y axis or just scaled to fit nicely in background. # Let's shift it so its mean roughly aligns with the mean of the SPL for visualization # This is purely for qualitative comparison of "where the energy is". ax.semilogx(f, Pxx_db, color=color, alpha=alpha, linewidth=1, label=label, zorder=0)
def generate_filter_type_comparison(output_dir: str) -> None: """Compare different filter architectures with a zoom inset.""" print("Generating filter_type_comparison.png...") fs = 48000 fraction = 1 order = 6 # We want exactly the 1000Hz band limits = [800.0, 1200.0] filters = [ ("butter", "Butterworth", COLOR_PRIMARY, "-"), ("cheby1", "Chebyshev I", COLOR_SECONDARY, "--"), ("cheby2", "Chebyshev II", COLOR_TERTIARY, ":"), ("ellip", "Elliptic", "#9467bd", "-."), ("bessel", "Bessel", "#8c564b", "-"), ] _, ax = plt.subplots(figsize=(10, 7)) # Create inset axis for zoom (increased height to 45%) from mpl_toolkits.axes_grid1.inset_locator import inset_axes axins = inset_axes(ax, width="35%", height="45%", loc="upper left", borderpad=3) axins.set_xscale("log") # Explicitly set log scale for f_type, label, color, style in filters: bank = OctaveFilterBank(fs, fraction=fraction, order=order, limits=limits, filter_type=f_type) # Find index of 1000Hz band idx = np.argmin(np.abs(np.array(bank.freq) - 1000)) fsd = fs / bank.factor[idx] w, h = scipy_signal.sosfreqz(bank.sos[idx], worN=16384, fs=fsd) mag_db = 20 * np.log10(np.abs(h) + 1e-9) ax.semilogx(w, mag_db, label=label, color=color, linestyle=style) axins.plot(w, mag_db, color=color, linestyle=style)
ax.axhline(-3, color=COLOR_FG, linestyle=":", alpha=0.3, label="-3 dB") axins.axhline(-3, color=COLOR_FG, linestyle=":", alpha=0.3) apply_axis_styling(ax, "Filter Architecture Comparison (Order 6, 1kHz Band)", xlim=(100, 8000), ylim=(-80, 5)) # Sub-plot styling (Zoom around 1kHz and -3dB) axins.set_xlim(650, 1500) axins.set_ylim(-4, 0.5) # Adjusted: from -4 to 0.5 axins.grid(True, which="both", alpha=0.3) axins.set_title("Zoom at -3 dB (Log Scale)", fontsize=9)
# Fix x-ticks for log scale zoom to look right from matplotlib.ticker import NullFormatter, ScalarFormatter
axins.xaxis.set_major_formatter(ScalarFormatter()) axins.xaxis.set_minor_formatter(NullFormatter()) # Hide minor tick labels axins.xaxis.get_major_formatter().set_scientific(False) # Disable scientific notation axins.set_xticks([707, 1000, 1414]) axins.set_xticklabels(["707", "1000", "1414"], fontsize=8)
ax.legend(loc="lower right") plt.savefig(themed_path(output_dir, "filter_type_comparison.png")) plt.close()
def generate_filter_responses(output_dir: str) -> None: """Generate plots for the filter bank responses for different filter types.""" fs = 48000 # Filter types to generate filter_types = [ ("butter", "butter"), ("cheby1", "cheby1"), ("cheby2", "cheby2"), ("ellip", "ellip"), ("bessel", "bessel"), ]
configs = [ (1, 6), (3, 6), ]
for f_type_name, f_type in filter_types: for fraction, order in configs: filename = f"filter_{f_type_name}_fraction_{fraction}_order_{order}.png" print(f"Generating {filename}...") bank = OctaveFilterBank(fs=fs, fraction=fraction, order=order, limits=[12.0, 20000.0], filter_type=f_type) from phonometry.filter_design import _showfilter _showfilter(bank.sos, bank.freq, bank.freq_u, bank.freq_d, fs, bank.factor, show=False, plot_file=themed_path(output_dir, filename)) plt.close("all")
def generate_signal_responses(output_dir: str) -> None: """Generate spectral analysis plots for a complex signal.""" fs = 48000 duration = 5 t = np.linspace(0, duration, int(fs * duration), endpoint=False) freqs = [20, 100, 500, 2000, 4000, 15000] y = 100 * np.sum([np.sin(2 * np.pi * f * t) for f in freqs], axis=0)
for frac, filename, title in [ (1, "signal_response_fraction_1.png", "1/1 Octave Band Analysis"), (3, "signal_response_fraction_3.png", "1/3 Octave Band Analysis"), ]: print(f"Generating {filename}...") bank = OctaveFilterBank(fs=fs, fraction=frac, order=6, limits=[12.0, 20000.0]) spl, freq = bank.filter(y)
_, ax = plt.subplots() # Plot PSD of raw signal in background # We need to scale PSD to comparable levels. # A simple hack for visualization is to align the max of PSD to max of SPL f_psd, Pxx = scipy_signal.welch(y, fs, nperseg=8192) Pxx_db = 10 * np.log10(Pxx + 1e-12) # Shift PSD to match SPL peak roughly Pxx_db += (np.max(spl) - np.max(Pxx_db)) - 5 # Shift slightly below ax.semilogx(f_psd, Pxx_db, color="gray", alpha=0.6, linewidth=1.2, label="Raw Signal Spectrum (PSD)", zorder=0) ax.semilogx( freq, spl, marker="o", markersize=5, linestyle="-", color=COLOR_PRIMARY, linewidth=1.5, markerfacecolor="white", markeredgewidth=1.5, label=f"Measured 1/{frac} Octave Bands" ) apply_axis_styling(ax, title, xlim=(11, 25000)) ax.legend(loc="lower right") plt.savefig(themed_path(output_dir, filename)) plt.close()
def generate_multichannel_response(output_dir: str) -> None: """Generate analysis plot for a stereo signal with separate subplots.""" print("Generating signal_response_multichannel.png...") fs = 48000 duration = 5 t = np.linspace(0, duration, int(fs * duration), endpoint=False)
rng = np.random.default_rng(42) # Channel 1: Pink Noise (Voss-McCartney simplified) # Good enough for visualization white = rng.standard_normal(len(t)) b, a = scipy_signal.butter(1, 0.04) # -3dB/oct approx ch1 = scipy_signal.lfilter(b, a, white) ch1 = (ch1 - np.mean(ch1)) / np.max(np.abs(ch1))
# Channel 2: Logarithmic Sine Sweep ch2 = scipy_signal.chirp(t, f0=50, t1=duration, f1=10000, method="logarithmic")
x = np.vstack((ch1, ch2)) bank = OctaveFilterBank(fs=fs, fraction=3, order=6, limits=[20.0, 20000.0]) spl, freq = bank.filter(x)
fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 8), sharex=True)
# Calculate PSDs for background f_psd1, Pxx1 = scipy_signal.welch(x[0], fs, nperseg=4096) Pxx_db1 = 10 * np.log10(Pxx1 + 1e-12) Pxx_db1 += (np.max(spl[0]) - np.max(Pxx_db1)) # Align peaks f_psd2, Pxx2 = scipy_signal.welch(x[1], fs, nperseg=4096) Pxx_db2 = 10 * np.log10(Pxx2 + 1e-12) Pxx_db2 += (np.max(spl[1]) - np.max(Pxx_db2)) # Align peaks
# Plot Left Channel ax1.semilogx(f_psd1, Pxx_db1, color="gray", alpha=0.6, linewidth=1.2, label="Raw PSD", zorder=0) ax1.semilogx( freq, spl[0], marker="o", markersize=5, label="Left Channel: Pink Noise", color=COLOR_PRIMARY, linestyle="-", linewidth=1.5, markerfacecolor="white", markeredgewidth=1.2, ) # Use standard styling but override title apply_axis_styling(ax1, "Multichannel Analysis (Stereo Input)", xlim=(16, 20000)) ax1.legend(loc="lower right") # Let Y-axis autoscale
# Plot Right Channel ax2.semilogx(f_psd2, Pxx_db2, color="gray", alpha=0.6, linewidth=1.2, label="Raw PSD", zorder=0) ax2.semilogx( freq, spl[1], marker="s", markersize=5, label="Right Channel: Log Sine Sweep", color=COLOR_SECONDARY, linestyle="-", linewidth=1.5, markerfacecolor="white", markeredgewidth=1.2, ) apply_axis_styling(ax2, "", xlim=(16, 20000)) ax2.set_title("") # Remove title from bottom plot ax2.legend(loc="lower right") # Let Y-axis autoscale
plt.tight_layout() plt.savefig(themed_path(output_dir, "signal_response_multichannel.png")) plt.close()
def generate_decomposition_plot(output_dir: str) -> None: """Generate time-domain decomposition plot comparing two filter types (Butterworth vs Chebyshev II).""" print("Generating signal_decomposition.png with comparison (Butter vs Cheby2) @ 48kHz...") fs = 48000 duration = 0.5 t = np.linspace(0, duration, int(fs * duration), endpoint=False)
# Signal: sum of 250Hz and 1000Hz sines y = np.sin(2 * np.pi * 250 * t) + np.sin(2 * np.pi * 1000 * t)
# Filter into 1/1 octave bands with two different architectures # We use Chebyshev II (flat passband, no ripple) bank_butter = OctaveFilterBank(fs=fs, fraction=1, order=6, limits=[100.0, 2000.0], filter_type="butter") bank_cheby2 = OctaveFilterBank(fs=fs, fraction=1, order=6, limits=[100.0, 2000.0], filter_type="cheby2") # Cast to 3-tuple to satisfy mypy unpacking _, freq, xb_butter = bank_butter.filter(y, sigbands=True) _, _, xb_cheby2 = bank_cheby2.filter(y, sigbands=True)
if xb_butter is None or xb_cheby2 is None: raise ValueError("Signal bands should not be None")
num_plots = len(xb_butter) + 2 # +1 for original, +1 for impulse response fig, axes = plt.subplots(num_plots, 1, figsize=(10, 2.2 * num_plots), sharex=False)
# Fixed Y limits for decomposition y_lim = (-2.8, 2.8)
# 1. Original Signal axes[0].plot(t, y, color=COLOR_FG, linewidth=1.5) axes[0].set_title("Original Signal (250 Hz + 1000 Hz Sum) @ 48 kHz", fontweight="bold") axes[0].set_ylim(y_lim) axes[0].set_xlim(0, 0.04)
# 2. Filtered Bands Comparison for i, (f_center) in enumerate(freq): axes[i + 1].plot(t, xb_butter[i], color=COLOR_PRIMARY, linewidth=1.5, label="Butterworth (Flat)") axes[i + 1].plot(t, xb_cheby2[i], color=COLOR_SECONDARY, linewidth=1.2, linestyle="--", alpha=0.9, label="Chebyshev II") axes[i + 1].set_title(f"Octave Band: {f_center:.0f} Hz", fontsize=11, fontweight="bold") axes[i + 1].set_ylim(y_lim) axes[i + 1].set_xlim(0, 0.04) if i == 0: axes[i+1].legend(loc="upper right", fontsize=9, framealpha=0.8)
# 3. Impulse Response (Stability/Transient Visualization) impulse = np.zeros(len(t)) impulse[0] = 1.0 _, _, ir_butter = bank_butter.filter(impulse, sigbands=True) _, _, ir_cheby2 = bank_cheby2.filter(impulse, sigbands=True) idx_1000 = np.argmin(np.abs(np.array(freq) - 1000)) axes[-1].plot(t, ir_butter[idx_1000], color=COLOR_PRIMARY, linewidth=1.5, label="Butterworth") axes[-1].plot(t, ir_cheby2[idx_1000], color=COLOR_SECONDARY, linewidth=1.2, linestyle="--", alpha=0.9, label="Chebyshev II") axes[-1].set_title(f"Impulse Response ({freq[idx_1000]:.0f} Hz Band) - Transient/Stability Comparison", fontweight="bold") axes[-1].set_xlim(0, 0.04) axes[-1].set_xlabel("Time [s]") axes[-1].legend(loc="upper right", fontsize=9, framealpha=0.8)
for ax in axes: ax.set_ylabel("Amplitude") ax.grid(True, which="both", alpha=0.4, linestyle=":")
plt.tight_layout() plt.savefig(themed_path(output_dir, "signal_decomposition.png")) plt.close()
def measure_weighting_response( fs: int, curve: str, freqs: "np.ndarray | None" = None) -> tuple[np.ndarray, np.ndarray]: """ Measure a weighting curve the way the docs figure plots it: impulse response through the real filter path, evaluated with ``freqz`` (DTFT of the measured response).
The impulse is placed at the CENTER of the buffer: the high-accuracy weighting path resamples with polyphase FIRs, and an impulse at sample 0 loses the anti-causal half of the interpolation kernel (edge truncation), which once shipped a figure with curves ~2.4 dB low. Centering only adds linear phase, which does not affect the magnitude.
:param fs: Sample rate in Hz. :param curve: 'A', 'C' or 'Z'. :param freqs: Optional exact frequencies to evaluate; defaults to a dense 8192-point grid for plotting. :return: Tuple (frequencies, magnitude in dB). """ from phonometry import weighting_filter
impulse = np.zeros(fs) impulse[fs // 2] = 1.0 weighted = weighting_filter(impulse, fs, curve=curve)
worn = 8192 if freqs is None else np.asarray(freqs, dtype=float) w, h = scipy_signal.freqz(weighted, [1], worN=worn, fs=fs) mag_db = 20 * np.log10(np.abs(h) + 1e-9) if freqs is None: # Drop the 0 Hz point: it cannot be drawn on a log frequency axis. return w[1:], mag_db[1:] return w, mag_db
def generate_weighting_responses(output_dir: str) -> None: """Plot A, C and Z weighting frequency responses.""" print("Generating weighting_responses.png...") fs = 48000
_, ax = plt.subplots(figsize=(10, 7))
# Zoom inset: the A curve is POSITIVE (+1.27 dB max at ~2.5 kHz per # IEC 61672-1 Table 2), invisible at the full -50..5 dB scale. from mpl_toolkits.axes_grid1.inset_locator import inset_axes axins = inset_axes(ax, width="42%", height="38%", loc="lower center", borderpad=2) axins.set_xscale("log")
curves = [ ("A", "A-Weighting", COLOR_PRIMARY), ("C", "C-Weighting", COLOR_SECONDARY), ("Z", "Z-Weighting (Flat)", COLOR_FG) ]
for code, label, color in curves: # measure_weighting_response is covered by tests/test_graph_measurements.py w, mag_db = measure_weighting_response(fs, code) ax.semilogx(w, mag_db, label=label, color=color) axins.plot(w, mag_db, color=color)
ax.axhline(0, color=COLOR_FG, linestyle=":", alpha=0.3, linewidth=1) apply_axis_styling(ax, "Frequency Weighting Curves (IEC 61672-1)", xlim=(10, 22000), ylim=(-50, 5))
axins.axhline(0, color=COLOR_FG, linestyle=":", alpha=0.4, linewidth=1) axins.set_xlim(500, 8000) axins.set_ylim(-3, 2) axins.grid(True, which="both", alpha=0.3) axins.set_title("Zoom: A-weighting is positive (max +1.27 dB @ 2.5 kHz)", fontsize=9) axins.annotate( "+1.27 dB", xy=(2500, 1.27), xytext=(4200, 1.55), fontsize=8, arrowprops={"arrowstyle": "->", "lw": 0.8}, ) from matplotlib.ticker import NullFormatter, ScalarFormatter axins.xaxis.set_major_formatter(ScalarFormatter()) axins.xaxis.set_minor_formatter(NullFormatter()) axins.set_xticks([500, 1000, 2500, 5000, 8000]) axins.set_xticklabels(["500", "1k", "2.5k", "5k", "8k"], fontsize=8)
ax.legend(loc="lower right") plt.savefig(themed_path(output_dir, "weighting_responses.png")) plt.close()
def generate_g_weighting_response(output_dir: str) -> None: """Plot the ISO 7196 G-weighting curve against the Table 2 nominals.""" print("Generating g_weighting_response.png...") from scipy import signal as sp_signal
from phonometry import WeightingFilter
fs = 48000 # ISO 7196:1995 Table 2 - nominal one-third-octave frequency, response dB table2 = [ (0.25, -88.0), (0.5, -64.3), (1.0, -43.0), (2.0, -28.3), (4.0, -16.0), (8.0, -4.0), (10.0, 0.0), (16.0, 7.7), (20.0, 9.0), (31.5, -4.0), (63.0, -28.0), (125.0, -52.0), (250.0, -76.0), ] freqs = np.logspace(np.log10(0.1), np.log10(1000), 800) sos = WeightingFilter(fs, "G").sos _, h = sp_signal.sosfreqz(sos, worN=freqs, fs=fs) mag_db = 20 * np.log10(np.abs(h))
_, ax = plt.subplots(figsize=(10, 6)) ax.semilogx(freqs, mag_db, color=COLOR_PRIMARY, label="G-weighting (ISO 7196)") tf = [f for f, _ in table2] tv = [v for _, v in table2] ax.plot(tf, tv, "o", color=COLOR_SECONDARY, markersize=5, label="ISO 7196 Table 2 nominals", zorder=5) ax.axhline(0, color=COLOR_FG, linestyle=":", alpha=0.3, linewidth=1) ax.axvline(10, color=COLOR_FG, linestyle=":", alpha=0.3, linewidth=1) ax.annotate("0 dB @ 10 Hz", xy=(10, 0), xytext=(20, -18), fontsize=9, arrowprops={"arrowstyle": "->", "lw": 0.8}) apply_axis_styling( ax, "G Frequency Weighting for Infrasound (ISO 7196:1995)", xlim=(0.1, 1000), ylim=(-95, 15), ) from matplotlib.ticker import NullFormatter, ScalarFormatter ticks = [0.1, 0.25, 0.5, 1, 2, 5, 10, 20, 50, 125, 315, 1000] ax.set_xticks(ticks) ax.xaxis.set_major_formatter(ScalarFormatter()) ax.xaxis.set_minor_formatter(NullFormatter()) ax.set_xticklabels(["0.1", "0.25", "0.5", "1", "2", "5", "10", "20", "50", "125", "315", "1k"]) ax.legend(loc="upper right") plt.savefig(themed_path(output_dir, "g_weighting_response.png")) plt.close()
def generate_equal_loudness_contours(output_dir: str) -> None: """Plot the ISO 226:2023 normal equal-loudness-level contours.""" print("Generating equal_loudness_contours.png...") from phonometry import equal_loudness_contour, hearing_threshold
_, ax = plt.subplots(figsize=(10, 7)) for phon in [20, 40, 60, 80, 90]: freqs, spl = equal_loudness_contour(float(phon)) ax.semilogx(freqs, spl, color=COLOR_PRIMARY, linewidth=1.5) ax.annotate(f"{phon} phon", xy=(1000, phon), xytext=(1150, phon + 1), fontsize=9, color=COLOR_PRIMARY) ft, tf = hearing_threshold() ax.semilogx(ft, tf, color=COLOR_SECONDARY, linestyle="--", label="Hearing threshold $T_f$ (Table 1)") ax.plot(1000, 0, alpha=0) # keep 0 dB in view apply_axis_styling( ax, "Normal Equal-Loudness-Level Contours (ISO 226:2023)", xlim=(20, 12500), ylim=(-10, 130), ) ax.set_ylabel("Sound pressure level [dB re 20 \u00b5Pa]") ax.legend(loc="upper right") plt.savefig(themed_path(output_dir, "equal_loudness_contours.png")) plt.close()
def generate_time_weighting_plot(output_dir: str) -> None: """Visualize Fast, Slow and Impulse time weighting response to a burst.""" print("Generating time_weighting_analysis.png...") fs = 1000 t = np.linspace(0, 4, fs * 4, endpoint=False) # 500ms burst of noise starting at 1.0s rng = np.random.default_rng(42) x = np.zeros_like(t) start_idx = int(fs * 1.0) end_idx = int(fs * 1.5) x[start_idx:end_idx] = rng.standard_normal(end_idx - start_idx) from phonometry import time_weighting # Square for energy x_sq = x**2 fast = time_weighting(x, fs, mode="fast") slow = time_weighting(x, fs, mode="slow") impulse = time_weighting(x, fs, mode="impulse") _, ax = plt.subplots() # Normalize for better visualization # We normalized x_sq to peak at 1 for the plot peak = np.max(x_sq) x_sq /= peak fast /= peak slow /= peak impulse /= peak ax.plot(t, x_sq, color=COLOR_GRID, alpha=0.5, label="Input Burst (Normalized)") ax.plot(t, fast, color=COLOR_PRIMARY, label="Fast (125ms)") ax.plot(t, slow, color=COLOR_SECONDARY, label="Slow (1000ms)") ax.plot(t, impulse, color="purple", linestyle="-.", linewidth=1.5, label="Impulse (35ms/1.5s)") ax.set_title("Time Weighting Ballistics (IEC 61672-1)", fontweight="bold") ax.set_xlabel("Time [s]") ax.set_ylabel("Normalized Response") ax.legend(loc="upper right") ax.set_xlim(0.8, 3.5) plt.savefig(themed_path(output_dir, "time_weighting_analysis.png")) plt.close()
def generate_crossover_plot(output_dir: str) -> None: """Visualize Linkwitz-Riley 4th Order Crossover.""" print("Generating crossover_lr4.png...") fs = 48000 from phonometry import linkwitz_riley # Frequency analysis # Measure response using IR impulse = np.zeros(fs) impulse[0] = 1.0 lp_ir, hp_ir = linkwitz_riley(impulse, fs, freq=1000, order=4) w, h_lp = scipy_signal.freqz(lp_ir, worN=8192, fs=fs) _, h_hp = scipy_signal.freqz(hp_ir, worN=8192, fs=fs) _, ax = plt.subplots() ax.semilogx(w, 20 * np.log10(np.abs(h_lp) + 1e-9), color=COLOR_PRIMARY, label="Low Pass (LR4)") ax.semilogx(w, 20 * np.log10(np.abs(h_hp) + 1e-9), color=COLOR_SECONDARY, label="High Pass (LR4)") ax.semilogx(w, 20 * np.log10(np.abs(h_lp + h_hp) + 1e-9), color=COLOR_FG, linestyle="--", label="Sum (Flat)")
apply_axis_styling(ax, "Linkwitz-Riley Crossover (4th Order @ 1kHz)", xlim=(20, 20000), ylim=(-60, 5)) ax.legend(loc="lower right") plt.savefig(themed_path(output_dir, "crossover_lr4.png")) plt.close()
def generate_spectrogram_example(output_dir: str) -> None: """Visualize OctaveFilterBank.spectrogram on a time-varying signal.""" print("Generating spectrogram_example.png...") fs = 48000 duration = 4.0 t = np.linspace(0, duration, int(fs * duration), endpoint=False)
# Log sweep + two tone bursts to show time-frequency localization rng = np.random.default_rng(42) x = 0.5 * scipy_signal.chirp(t, f0=80, t1=duration, f1=8000, method="logarithmic") x[int(1.0 * fs):int(1.3 * fs)] += np.sin(2 * np.pi * 4000 * t[int(1.0 * fs):int(1.3 * fs)]) x[int(2.5 * fs):int(2.8 * fs)] += np.sin(2 * np.pi * 250 * t[int(2.5 * fs):int(2.8 * fs)]) x += 0.01 * rng.standard_normal(len(t))
bank = OctaveFilterBank(fs=fs, fraction=3, order=6, limits=[50.0, 12000.0]) levels, freq, times = bank.spectrogram(x, window_time=0.125, overlap=0.5)
_, ax = plt.subplots() mesh = ax.pcolormesh(times, freq, levels, shading="auto", cmap="magma") ax.set_yscale("log") ax.set_title("1/3 Octave Spectrogram (Fast windows, 50% overlap)", fontweight="bold", pad=12) ax.set_xlabel("Time [s]") ax.set_ylabel(LABEL_FREQ_HZ) yticks = [63, 125, 250, 500, 1000, 2000, 4000, 8000] ax.set_yticks(yticks) ax.set_yticklabels(["63", "125", "250", "500", "1k", "2k", "4k", "8k"]) plt.colorbar(mesh, ax=ax, label=LABEL_LEVEL_DB) plt.savefig(themed_path(output_dir, "spectrogram_example.png")) plt.close()
def generate_ln_levels_example(output_dir: str) -> None: """Visualize statistical LN levels over the Fast envelope.""" print("Generating ln_levels_example.png...") fs = 8000 duration = 30.0 t = np.linspace(0, duration, int(fs * duration), endpoint=False)
from phonometry import ln_levels, time_weighting
# Fluctuating "traffic-like" noise: background + random events rng = np.random.default_rng(42) x = 0.05 * rng.standard_normal(len(t)) for _ in range(12): start = rng.uniform(1, duration - 3) length = rng.uniform(0.5, 2.0) idx = (t >= start) & (t < start + length) envelope = np.hanning(int(idx.sum())) x[idx] += envelope * rng.uniform(0.3, 1.0) * rng.standard_normal(int(idx.sum()))
envelope_ms = time_weighting(x, fs, mode="fast") level_t = 10 * np.log10(np.maximum(envelope_ms, 1e-12) / (2e-5) ** 2) stats = ln_levels(x, fs, n=(10, 50, 90))
_, ax = plt.subplots() ax.plot(t, level_t, color=COLOR_PRIMARY, linewidth=0.8, label="Fast level $L_p(t)$") for n_value, color, style in [(10, COLOR_SECONDARY, "--"), (50, COLOR_FG, "-"), (90, COLOR_TERTIARY, "-.")]: ax.axhline( float(stats[n_value]), color=color, linestyle=style, linewidth=1.5, label=f"L{n_value} = {float(stats[n_value]):.1f} dB", ) ax.set_title("Statistical Levels L10 / L50 / L90 (Fast envelope)", fontweight="bold", pad=12) ax.set_xlabel("Time [s]") ax.set_ylabel(LABEL_LEVEL_DB) ax.set_xlim(0, duration) ax.legend(loc="lower right") plt.savefig(themed_path(output_dir, "ln_levels_example.png")) plt.close()
def generate_zero_phase_comparison(output_dir: str) -> None: """Compare causal vs zero-phase band filtering of a tone burst.""" print("Generating zero_phase_comparison.png...") fs = 48000 duration = 0.15 t = np.linspace(0, duration, int(fs * duration), endpoint=False)
# 250 Hz tone burst in the middle of the frame x = np.zeros_like(t) start, end = int(0.05 * fs), int(0.10 * fs) x[start:end] = np.sin(2 * np.pi * 250 * t[start:end]) * np.hanning(end - start)
bank = OctaveFilterBank(fs=fs, fraction=1, order=6, limits=[200.0, 300.0]) _, _, bands_fwd = bank.filter(x, sigbands=True, calculate_level=False) _, _, bands_zp = bank.filter(x, sigbands=True, calculate_level=False, zero_phase=True)
_, ax = plt.subplots() ax.plot(t, x, color="gray", alpha=0.5, linewidth=1.0, label="Input burst (250 Hz)") ax.plot(t, bands_fwd[0], color=COLOR_PRIMARY, linewidth=1.3, label="Causal filtering (group delay)") ax.plot(t, bands_zp[0], color=COLOR_SECONDARY, linewidth=1.3, linestyle="--", label="zero_phase=True (aligned)") ax.set_title("Zero-Phase Filtering: Group Delay Elimination (250 Hz Band)", fontweight="bold", pad=12) ax.set_xlabel("Time [s]") ax.set_ylabel("Amplitude") ax.legend(loc="upper right") plt.savefig(themed_path(output_dir, "zero_phase_comparison.png")) plt.close()
def generate_weighting_accuracy_hf(output_dir: str) -> None: """Compare A-weighting HF accuracy: analytic vs bilinear vs high_accuracy.""" print("Generating weighting_accuracy_hf.png...") fs = 48000
from phonometry import WeightingFilter
freqs = np.logspace(np.log10(1000), np.log10(20000), 40)
def analytic_a(f: np.ndarray) -> np.ndarray: ra = (12194**2 * f**4) / ( (f**2 + 20.6**2) * np.sqrt((f**2 + 107.7**2) * (f**2 + 737.9**2)) * (f**2 + 12194**2) ) return 20 * np.log10(ra) + 2.0
def measured_gains(wf: WeightingFilter) -> np.ndarray: gains = [] for f0 in freqs: tt = np.arange(int(fs * 0.2)) / fs x = np.sin(2 * np.pi * f0 * tt) y = wf.filter(x) n0 = int(0.05 * fs) # skip filter transient gains.append(20 * np.log10(np.std(y[n0:]) / np.std(x[n0:]))) return np.array(gains)
legacy = measured_gains(WeightingFilter(fs, "A", high_accuracy=False)) accurate = measured_gains(WeightingFilter(fs, "A")) reference = analytic_a(freqs)
_, (ax, ax_err) = plt.subplots(2, 1, figsize=(10, 8), sharex=True) ax.semilogx(freqs, reference, color=COLOR_FG, linewidth=2, label="IEC 61672-1 analytic curve") ax.semilogx(freqs, legacy, color=COLOR_SECONDARY, linestyle="--", label="Plain bilinear (high_accuracy=False)") ax.semilogx(freqs, accurate, color=COLOR_PRIMARY, linestyle="-.", label="Oversampled (high_accuracy=True)") ax.set_title(f"A-Weighting High-Frequency Accuracy @ fs={fs//1000} kHz", fontweight="bold", pad=12) ax.set_ylabel(LABEL_LEVEL_DB) ax.legend(loc="lower left")
ax_err.semilogx(freqs, legacy - reference, color=COLOR_SECONDARY, linestyle="--", label="Bilinear error") ax_err.semilogx(freqs, accurate - reference, color=COLOR_PRIMARY, linestyle="-.", label="high_accuracy error") ax_err.axhline(-2.5, color="gray", linestyle=":", label="Class 1 lower limit @ 12.5 kHz") ax_err.set_ylabel("Error [dB]") ax_err.set_xlabel(LABEL_FREQ_HZ) ax_err.set_ylim(-8, 2) ax_err.legend(loc="lower left")
for a in (ax, ax_err): xticks = [1000, 2000, 4000, 8000, 12500, 16000, 20000] a.set_xticks(xticks) a.set_xticklabels(["1k", "2k", "4k", "8k", "12.5k", "16k", "20k"])
plt.tight_layout() plt.savefig(themed_path(output_dir, "weighting_accuracy_hf.png")) plt.close()
def generate_group_delay_comparison(output_dir: str) -> None: """Group delay of the 1 kHz band for every architecture (docs: filter-banks).""" print("Generating group_delay_comparison.png...") fs = 48000 limits = [800.0, 1200.0]
filters = [ ("butter", "Butterworth", COLOR_PRIMARY, "-"), ("cheby1", "Chebyshev I", COLOR_SECONDARY, "--"), ("cheby2", "Chebyshev II", COLOR_TERTIARY, ":"), ("ellip", "Elliptic", "#9467bd", "-."), ("bessel", "Bessel", "#8c564b", "-"), ]
_, ax = plt.subplots() for f_type, label, color, style in filters: bank = OctaveFilterBank(fs, fraction=1, order=6, limits=limits, filter_type=f_type) idx = int(np.argmin(np.abs(np.array(bank.freq) - 1000))) fsd = fs / bank.factor[idx] # Group delay of an SOS cascade = sum of the sections' group delays. w = np.logspace(np.log10(500), np.log10(2000), 1024) gd = np.zeros_like(w) for section in bank.sos[idx]: w_s, gd_s = scipy_signal.group_delay((section[:3], section[3:]), w=w, fs=fsd) gd += gd_s ax.semilogx(w, gd / fsd * 1000, label=label, color=color, linestyle=style)
ax.set_title("Group Delay Comparison (1 kHz Octave Band, Order 6)", fontweight="bold", pad=12) ax.set_xlabel(LABEL_FREQ_HZ) ax.set_ylabel("Group delay [ms]") ax.set_xlim(500, 2000) from matplotlib.ticker import NullFormatter ax.xaxis.set_minor_formatter(NullFormatter()) ax.set_xticks([500, 707, 1000, 1414, 2000]) ax.set_xticklabels(["500", "707", "1k", "1.41k", "2k"]) ax.legend(loc="upper right") plt.savefig(themed_path(output_dir, "group_delay_comparison.png")) plt.close()
def generate_tone_burst_iec(output_dir: str) -> None: """FAST envelope response to 4 kHz tonebursts vs IEC 61672-1 Table 4 targets.""" print("Generating tone_burst_iec.png...") fs = 48000
from phonometry import time_weighting
cases = [(0.2, -1.0), (0.05, -4.8), (0.01, -11.1)] # Table 4, class 1 rows fig, axes = plt.subplots(1, 3, figsize=(12, 4.5), sharey=True)
t_all = np.arange(int(fs * 2.0)) / fs steady = np.sin(2 * np.pi * 4000 * t_all) ref = time_weighting(steady, fs, mode="fast")[int(1.5 * fs):].mean()
for ax, (duration, target) in zip(axes, cases): burst = np.zeros_like(t_all) start = int(0.5 * fs) burst[start:start + round(duration * fs)] = steady[start:start + round(duration * fs)] env_db = 10 * np.log10(np.maximum(time_weighting(burst, fs, mode="fast") / ref, 1e-6))
ax.plot(t_all, env_db, color=COLOR_PRIMARY, linewidth=1.3, label="FAST envelope") ax.axhline(target, color=COLOR_SECONDARY, linestyle="--", linewidth=1.2, label=f"IEC target {target} dB") ax.set_title(f"{duration * 1000:g} ms burst", fontsize=11, fontweight="bold") ax.set_xlim(0.4, 1.4) ax.set_ylim(-30, 3) ax.set_xlabel("Time [s]") ax.legend(loc="upper right", fontsize=8) axes[0].set_ylabel("Level re steady state [dB]")
fig.suptitle("4 kHz Toneburst Response vs IEC 61672-1 Table 4 (FAST)", fontweight="bold") plt.tight_layout() plt.savefig(themed_path(output_dir, "tone_burst_iec.png")) plt.close()
def generate_block_processing_continuity(output_dir: str) -> None: """Stateful vs stateless block processing (docs: block-processing).""" print("Generating block_processing_continuity.png...") fs = 8000 n_blocks, block = 4, 1000 rng = np.random.default_rng(42) x = rng.standard_normal(n_blocks * block) t = np.arange(len(x)) / fs
def band_output(stateful: bool) -> np.ndarray: bank = OctaveFilterBank(fs, fraction=1, limits=[900, 1100], stateful=stateful, resample=False) if stateful: parts = [ bank.filter(x[i * block:(i + 1) * block], sigbands=True, detrend=False, calculate_level=False)[2][0] for i in range(n_blocks) ] else: parts = [] for i in range(n_blocks): b2 = OctaveFilterBank(fs, fraction=1, limits=[900, 1100], resample=False) parts.append(b2.filter(x[i * block:(i + 1) * block], sigbands=True, detrend=False, calculate_level=False)[2][0]) return np.concatenate(parts)
continuous = OctaveFilterBank(fs, fraction=1, limits=[900, 1100], resample=False).filter( x, sigbands=True, detrend=False, calculate_level=False)[2][0] y_stateful = band_output(stateful=True) y_stateless = band_output(stateful=False)
fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 6.5), sharex=True) zoom = slice(int(0.9 * block), int(1.4 * block)) # around the first boundary
ax1.plot(t[zoom], continuous[zoom], color=COLOR_FG, linewidth=2.2, alpha=0.35, label="Continuous (whole signal)") ax1.plot(t[zoom], y_stateful[zoom], color=COLOR_PRIMARY, linewidth=1.1, label="Stateful blocks (state carried)") ax1.set_title("stateful=True: block outputs equal the continuous result", fontsize=11, fontweight="bold") ax1.legend(loc="upper right", fontsize=9)
ax2.plot(t[zoom], continuous[zoom], color=COLOR_FG, linewidth=2.2, alpha=0.35, label="Continuous (whole signal)") ax2.plot(t[zoom], y_stateless[zoom], color=COLOR_SECONDARY, linewidth=1.1, label="Independent blocks (state reset)") ax2.axvline(block / fs, color=COLOR_FG, linestyle=":", alpha=0.6) ax2.annotate("block boundary:\nfilter transient restarts", xy=(block / fs, 0), xytext=(block / fs + 0.02, ax2.get_ylim()[0] * 0.55 if ax2.get_ylim()[0] < 0 else -1), fontsize=8, arrowprops={"arrowstyle": "->", "lw": 0.8}) ax2.set_title("No state: each block restarts the filter transient", fontsize=11, fontweight="bold") ax2.set_xlabel("Time [s]") ax2.legend(loc="upper right", fontsize=9) for a in (ax1, ax2): a.set_ylabel("Amplitude")
plt.tight_layout() plt.savefig(themed_path(output_dir, "block_processing_continuity.png")) plt.close()
def generate_class_mask_overlay(output_dir: str) -> None: """Band response against the IEC 61260-1:2014 class limit mask.""" print("Generating class_mask_overlay.png...") fs = 48000
from phonometry.compliance import class_limits
bank = OctaveFilterBank(fs, fraction=1, order=6, limits=[800, 1200], filter_type="butter") idx = int(np.argmin(np.abs(np.array(bank.freq) - 1000))) fm = bank.freq[idx] fsd = fs / bank.factor[idx] w, h = scipy_signal.sosfreqz(bank.sos[idx], worN=2 ** 15, fs=fsd) attenuation = -20 * np.log10(np.abs(h) + 1e-12) a_ref = float(np.interp(fm, w, attenuation)) omega = w / fm valid = (omega > 0.05) & (omega < 8) omega, delta_a = omega[valid], (attenuation - a_ref)[valid]
grid = np.logspace(np.log10(0.05), np.log10(8), 2000) lo1, hi1 = class_limits(1.0, 1, grid) lo2, _ = class_limits(1.0, 2, grid)
_, ax = plt.subplots(figsize=(10, 6.5)) # Forbidden regions for class 1: below the minimum required attenuation # (stop band) and above the maximum allowed attenuation (pass band). ax.fill_between(grid, -10, lo1, color=COLOR_SECONDARY, alpha=0.15, label="Forbidden for class 1 (too little attenuation)") finite = np.isfinite(hi1) ax.fill_between(grid[finite], hi1[finite], 90, color="#9467bd", alpha=0.15, label="Forbidden for class 1 (too much attenuation)") ax.plot(grid, lo2, color=COLOR_TERTIARY, linestyle=":", linewidth=1.2, label="Class 2 minimum attenuation")
ax.plot(omega, delta_a, color=COLOR_PRIMARY, linewidth=1.6, label="Butterworth order 6 (1 kHz octave band)")
ax.set_xscale("log") ax.set_xlim(0.08, 8) ax.set_ylim(-6, 90) ax.set_title("Relative Attenuation vs IEC 61260-1:2014 Class Limits", fontweight="bold", pad=12) ax.set_xlabel("Normalized frequency f / fm") ax.set_ylabel("Relative attenuation ΔA [dB]") ax.set_xticks([0.125, 0.25, 0.5, 0.707, 1, 1.414, 2, 4, 8]) ax.set_xticklabels(["0.125", "0.25", "0.5", "0.707", "1", "1.41", "2", "4", "8"]) ax.legend(loc="upper left", fontsize=9) plt.savefig(themed_path(output_dir, "class_mask_overlay.png")) plt.close()
def generate_og_image(output_path: str = "site/public/og-image.png") -> None: """FALLBACK social preview card (1200x630) for the docs site.
Not wired into generate_all(): the committed site/public/og-image.png is a designed asset (AI-generated card chosen by the maintainer). Run this only if that asset is lost and a quick replacement is needed. """ print("Generating og-image.png...") fs = 48000
fig = plt.figure(figsize=(12, 6.3), dpi=100) fig.patch.set_facecolor("#0f1216")
# Background: 1/3-octave bank response, dimmed. ax_bg = fig.add_axes([0.0, 0.0, 1.0, 0.52]) ax_bg.set_facecolor("none") bank = OctaveFilterBank(fs=fs, fraction=3, order=6, limits=[20.0, 20000.0]) for idx in range(bank.num_bands): fsd = fs / bank.factor[idx] w, h = scipy_signal.sosfreqz(bank.sos[idx], worN=2048, fs=fsd) mag = 20 * np.log10(np.abs(h) + 1e-9) ax_bg.semilogx(w, mag, color="#1f77b4", alpha=0.55, linewidth=1.4) ax_bg.set_xlim(20, 20000) ax_bg.set_ylim(-40, 2) ax_bg.axis("off")
fig.text(0.055, 0.82, "phonometry", color="white", fontsize=46, fontweight="bold") fig.text(0.057, 0.70, "Fractional octave analysis for Python", color="#a6d0ee", fontsize=22) fig.text( 0.057, 0.60, "ANSI S1.11 / IEC 61260-1 filter banks · IEC 61672-1 A/C/Z & Fast/Slow/Impulse · Leq, LN, spectrograms", color="#8ea4b8", fontsize=13.5, ) # Exact 1200x630: bypass the global savefig.bbox="tight" rcParam. with plt.rc_context({"savefig.bbox": None}): fig.savefig(output_path, dpi=100, facecolor=fig.get_facecolor()) plt.close(fig)
def generate_calibration_stability(output_dir: str) -> None: """Stable vs unstable calibration tone against the IEC 60942 limit.""" print("Generating calibration_stability.png...") from phonometry import time_weighting
fs = 48000 seconds = 6.0 tt = np.arange(int(fs * seconds)) / fs stable = 0.5 * np.sin(2 * np.pi * 1000 * tt) # 3 % amplitude modulation at 2 Hz: ~0.14 dB deviation, clearly over unstable = 0.5 * (1 + 0.03 * np.sin(2 * np.pi * 2.0 * tt)) * np.sin(2 * np.pi * 1000 * tt)
_, ax = plt.subplots(figsize=(10, 6)) skip = fs # discard the F-integrator attack (~8*tau = 1 s) for x, color, label in [ (stable, COLOR_PRIMARY, "Stable tone (good coupling)"), (unstable, COLOR_SECONDARY, "3% AM tone (loose coupling)"), ]: env = time_weighting(x, fs, mode="fast")[skip:] level = 10 * np.log10(np.maximum(env, np.finfo(float).eps)) rel = level - np.mean(level) ax.plot(tt[skip:], rel, color=color, linewidth=1.4, label=label)
ax.axhline(0.07, color=COLOR_FG, linestyle="--", linewidth=1.2, alpha=0.7) ax.axhline(-0.07, color=COLOR_FG, linestyle="--", linewidth=1.2, alpha=0.7, label="IEC 60942:2017 class 1 limit (deviation from mean)") ax.fill_between([1, seconds], -0.07, 0.07, color=COLOR_PRIMARY, alpha=0.06) ax.set_title("Calibration Tone Stability Check (IEC 60942:2017, 5.3.3)", fontweight="bold", pad=12) ax.set_xlim(1, seconds) ax.set_ylim(-0.2, 0.2) ax.set_xlabel("Time [s]") ax.set_ylabel("F-weighted level re mean [dB]") ax.legend(loc="upper right", fontsize=9) plt.savefig(themed_path(output_dir, "calibration_stability.png")) plt.close()
def generate_sel_concept(output_dir: str) -> None: """SEL: the whole event compressed into one second of equal energy.""" print("Generating sel_concept.png...") from phonometry import leq, sel, time_weighting
fs = 48000 seconds = 8.0 tt = np.arange(int(fs * seconds)) / fs rng = np.random.default_rng(11) # A vehicle pass-by: noise with a gaussian energy envelope envelope = np.exp(-0.5 * ((tt - 4.0) / 1.1) ** 2) x = envelope * rng.standard_normal(tt.size) * 0.3
env = time_weighting(x, fs, mode="fast") level = 10 * np.log10(np.maximum(env, 1e-12)) l_sel = float(sel(x, fs, dbfs=True)) l_eq = float(leq(x, fs, dbfs=True))
_, ax = plt.subplots(figsize=(10, 6)) ax.plot(tt, level, color=COLOR_PRIMARY, linewidth=1.2, label="Fast level of the event") ax.hlines(l_eq, 0, seconds, color=COLOR_TERTIARY, linestyle="--", linewidth=1.6, label="Leq over the whole event") # SEL: same energy squeezed into 1 s (drawn as a 1 s block) ax.fill_between([3.5, 4.5], -55, l_sel, color=COLOR_SECONDARY, alpha=0.25) ax.hlines(l_sel, 3.5, 4.5, color=COLOR_SECONDARY, linewidth=2.2, label="SEL: same energy in 1 s") ax.annotate("equal energy", xy=(4.5, l_sel - 3), xytext=(5.6, l_sel - 1), fontsize=10, arrowprops={"arrowstyle": "->", "lw": 0.9}) ax.set_title("Sound Exposure Level: the event normalized to 1 s", fontweight="bold", pad=12) ax.set_xlim(0, seconds) ax.set_ylim(-55, l_sel + 6) ax.set_xlabel("Time [s]") ax.set_ylabel("Level [dBFS]") ax.legend(loc="lower left", fontsize=9) plt.savefig(themed_path(output_dir, "sel_concept.png")) plt.close()
def generate_lden_profile(output_dir: str) -> None: """A 24 h urban level profile with the Lden period weightings.""" print("Generating lden_profile.png...") from phonometry import lden
hours = np.arange(24) # Typical urban road profile (synthetic hourly LAeq, dB) laeq_h = np.array([48, 46, 45, 45, 46, 50, 56, 64, 66, 65, 63, 63, 64, 63, 63, 64, 65, 66, 65, 64, 63, 62, 61, 50], dtype=float)
def _period_leq(idx: "np.ndarray") -> float: return float(10 * np.log10(np.mean(10 ** (0.1 * laeq_h[idx]))))
ld = _period_leq(np.arange(7, 19)) # day 07-19 le = _period_leq(np.arange(19, 23)) # evening 19-23 ln_ = _period_leq(np.r_[np.arange(23, 24), np.arange(0, 7)]) # night 23-07 l_den = lden(ld, le, ln_)
_, ax = plt.subplots(figsize=(10, 6)) ax.axvspan(7, 19, color=COLOR_TERTIARY, alpha=0.10) ax.axvspan(19, 23, color="#e8a838", alpha=0.15) ax.axvspan(23, 24, color=COLOR_PRIMARY, alpha=0.12) ax.axvspan(0, 7, color=COLOR_PRIMARY, alpha=0.12) ax.step(np.r_[hours, 24], np.r_[laeq_h, laeq_h[-1]], where="post", color=COLOR_FG, linewidth=1.6, label="Hourly LAeq") ax.hlines(ld, 7, 19, color=COLOR_TERTIARY, linestyle="--", linewidth=2, label="Lday (+0 dB)") ax.hlines(le + 5, 19, 23, color="#e8a838", linestyle="--", linewidth=2, label="Levening + 5 dB") ax.hlines(ln_ + 10, 23, 24, color=COLOR_PRIMARY, linestyle="--", linewidth=2) ax.hlines(ln_ + 10, 0, 7, color=COLOR_PRIMARY, linestyle="--", linewidth=2, label="Lnight + 10 dB") ax.hlines(l_den, 0, 24, color=COLOR_SECONDARY, linewidth=2.4, label=f"Lden = {l_den:.1f} dB") ax.set_title("Day-Evening-Night Level Lden (ISO 1996-1)", fontweight="bold", pad=12) ax.set_xlim(0, 24) ax.set_ylim(42, 80) ax.set_xticks([0, 4, 7, 12, 16, 19, 23]) ax.set_xlabel("Hour of day") ax.set_ylabel("Level [dB]") ax.legend(loc="upper left", fontsize=9, ncol=2) plt.savefig(themed_path(output_dir, "lden_profile.png")) plt.close()
def generate_tonality_spectrum(output_dir: str) -> None: """Annotated spectrum for the tone-to-noise ratio method.""" print("Generating tonality_spectrum.png...") from phonometry import tone_to_noise_ratio from phonometry.tonality import _averaged_spectrum, _critical_band
fs = 48000 rng = np.random.default_rng(21) tt = np.arange(fs * 30) / fs x = (np.sqrt(2) * 0.1 * np.sin(2 * np.pi * 1000 * tt) + 0.05 * rng.standard_normal(tt.size)) result = tone_to_noise_ratio(x, fs) freqs, power, _ = _averaged_spectrum(x - np.mean(x), fs, 1.0) f1, f2, _ = _critical_band(result.frequency)
_, ax = plt.subplots(figsize=(10, 6)) sel_band = (freqs > 700) & (freqs < 1400) db = 10 * np.log10(np.maximum(power, 1e-18)) ax.plot(freqs[sel_band], db[sel_band], color=COLOR_PRIMARY, linewidth=1.0, label="Averaged FFT spectrum (Hann)") ax.axvspan(f1, f2, color=COLOR_TERTIARY, alpha=0.15, label="Critical band around the tone") ax.axvline(result.frequency, color=COLOR_SECONDARY, linewidth=1.4, linestyle="--") ax.annotate( f"TNR = {result.ratio_db:.1f} dB\n(criterion {result.criterion_db:.1f} dB)", xy=(result.frequency, db.max() - 2), xytext=(1120, db.max() - 8), fontsize=11, arrowprops={"arrowstyle": "->", "lw": 1.0}, ) ax.set_title("Tone-to-Noise Ratio (ECMA-418-1, clause 11)", fontweight="bold", pad=12) ax.set_xlim(700, 1400) ax.set_xlabel("Frequency [Hz]") ax.set_ylabel("Bin power [dB]") ax.legend(loc="upper right", fontsize=9) plt.savefig(themed_path(output_dir, "tonality_spectrum.png")) plt.close()
def generate_all(img_dir: str) -> None: """Generate every documentation figure for the currently active theme.""" generate_filter_type_comparison(img_dir) generate_filter_responses(img_dir) generate_signal_responses(img_dir) generate_multichannel_response(img_dir) generate_decomposition_plot(img_dir)
generate_weighting_responses(img_dir) generate_g_weighting_response(img_dir) generate_equal_loudness_contours(img_dir) generate_time_weighting_plot(img_dir) generate_crossover_plot(img_dir)
# Feature documentation plots (levels, spectrogram, zero-phase, weighting accuracy) generate_spectrogram_example(img_dir) generate_ln_levels_example(img_dir) generate_zero_phase_comparison(img_dir) generate_weighting_accuracy_hf(img_dir)
# Docs-enrichment plots (group delay, IEC toneburst, block continuity, class mask) generate_group_delay_comparison(img_dir) generate_tone_burst_iec(img_dir) generate_block_processing_continuity(img_dir) generate_class_mask_overlay(img_dir) generate_calibration_stability(img_dir) generate_sel_concept(img_dir) generate_lden_profile(img_dir) generate_tonality_spectrum(img_dir)
if __name__ == "__main__": img_dir = ".github/images" os.makedirs(img_dir, exist_ok=True)
# Every figure is produced four times: light/dark theme x English/Spanish # ("_dark" / "_es" / "_es_dark" suffixes) so both site languages can # follow the user's mode. for lang in ("en", "es"): set_lang(lang) for dark in (False, True): set_theme(dark) print(f"--- Generating {lang} {'dark' if dark else 'light'} theme figures ---") generate_all(img_dir)
print("Graphics generated successfully.")