DSPkit

Documentation

A lightweight Digital Signal Processing (DSP) toolkit for time series data. Mostly for plotting and visual analysis. Based on NumPy + SciPy + Matplotlib.

---

Features

Module	Functions
spectral	FFT amplitude spectrum, Welch PSD, CSD, coherence, autocorrelation
filters	Lowpass / highpass / bandpass / bandstop / notch filters, decimation
utils	Detrend, RMS, peak, crest factor, integration, differentiation
timefreq	STFT spectrogram, CWT scalogram (Morlet), Wigner-Ville, Smoothed Pseudo WVD
instantaneous	Hilbert envelope, instantaneous phase & frequency
emd	Empirical Mode Decomposition, Hilbert-Huang Transform, marginal spectrum
peaks	Peak detection, bandwidth / Q-factor estimation, harmonic identification
indicators	Spectral entropy, kurtosis, skewness, RMS / energy / frequency tracking
multisensor	Correlation matrix, coherence matrix, PSD matrix
fdd	Frequency Domain Decomposition (FDD/EFDD) — natural frequencies, mode shapes, damping
statistics	PDF estimation (KDE), histograms, joint distributions, covariance, Mahalanobis distance
plots	Thin matplotlib wrappers for every analysis output

---

Installation

pip install git+https://github.com/LuigiCaglio/DSPkit.git

Requirements: Python ≥ 3.10, NumPy ≥ 1.24, SciPy ≥ 1.10, Matplotlib ≥ 3.7

---

Quick start

import numpy as np
import dspkit as dsp

# Simulate a 2DOF structural response
from dspkit._testing import generate_2dof, natural_frequencies_2dof

fs = 1000.0
t, a1, a2 = generate_2dof(duration=60.0, fs=fs, noise_std=1.0,
                           output="acceleration", seed=42)

# Welch PSD
freqs, Pxx = dsp.psd(a1, fs, nperseg=4096)
dsp.plot_psd(freqs, Pxx, title="Welch PSD — mass 1")

# Peak detection
peak_freqs, peak_vals, proms = dsp.find_peaks(freqs, Pxx, distance_hz=5.0)
dsp.plot_peaks(freqs, Pxx, peak_freqs, peak_vals, db=True)

# FDD — Operational Modal Analysis
data = np.vstack([a1, a2])
freqs, S, U = dsp.fdd_svd(data, fs, nperseg=4096)
peak_freqs, peak_idx = dsp.fdd_peak_picking(freqs, S, distance_hz=5.0, max_peaks=2)
modes = dsp.fdd_mode_shapes(U, peak_idx)
dsp.plot_singular_values(freqs, S, peak_freqs=peak_freqs)

# Bandpass filter around first mode
fn1, fn2 = natural_frequencies_2dof()
a1_bp = dsp.bandpass(a1, fs, low=fn1 - 3, high=fn1 + 3)

# Hilbert envelope
env, phase, fi = dsp.hilbert_attributes(a1_bp, fs)

# EMD
imfs, residue = dsp.emd(a1)
envs, inst_freqs = dsp.hht(imfs, fs)

# PDF estimation
xi, density = dsp.pdf_estimate(a1)
dsp.plot_pdf(xi, density, hist_data=a1)

---

Examples

Runnable scripts with plots are in the examples/ folder:

Script	Demonstrates
example_spectral.py	FFT, Welch PSD, coherence, autocorrelation
example_filters_utils.py	Filtering, notch, decimation, integration, signal metrics
example_timefreq.py	STFT, CWT, Wigner-Ville, Smoothed Pseudo WVD
example_instantaneous.py	Hilbert envelope, instantaneous frequency & phase
example_emd.py	EMD, HHT time-frequency scatter, marginal spectrum, damping
example_peaks_indicators.py	Peak detection, bandwidth, harmonics, SHM indicators
example_fdd.py	FDD/EFDD: singular values, mode shapes, damping estimation
example_multisensor_stats.py	Correlation/coherence matrices, PDF, joint distributions, Mahalanobis

python examples/example_spectral.py

---

Documentation

Full API reference and narrative guides: https://LuigiCaglio.github.io/DSPkit

To build docs locally:

pip install -e ".[docs]"
mkdocs serve

---

Development

pip install -e ".[dev]"
pytest

---

License

MIT