convolinear - Fluent Signal Processing for Python

Fluent signal processing for Python, one line at a time.

Pulse compression - the core of every radar, sonar and GPS receiver. The same echo is shown at -6 dB and at -20 dB SNR (echo power against noise power). At -20 dB the spectrogram shows nothing at all, and one correlate() call still collapses the echo into a spike at the exact round-trip delay. Reproduce with python examples/hero.py.

convolinear wraps the power of NumPy and SciPy in a fluent, readable API. Common DSP tasks - loading audio, filtering, mixing, and spectral analysis - become short, expressive one-liners instead of 10+ lines of boilerplate.

Extract data from a .wav file, bandpass it, normalise it, take the Fourier transform, and plot it. All in a single line of code:

Signal.from_wav("audio.wav").bandpass(300, 3000).normalize().fft().plot()

Installation

Core requirements: Python 3.11+, NumPy >= 1.23.2, SciPy >= 1.9.2

Optional dependencies unlock the following loaders and features:

MATLAB .mat files load through SciPy, already a core dependency - no extra needed.

With pip

convolinear is published on PyPi:

pip install convolinear

pip install "convolinear[plot,audio,pandas]"

With conda

convolinear is published on conda-forge:

conda install -c conda-forge convolinear

conda-forge packages don't support pip-style extras - install the optional dependencies as separate packages instead:

conda install -c conda-forge convolinear matplotlib soundfile pandas pyarrow

With uv

uv add convolinear

uv add "convolinear[plot,audio,pandas]"

Quickstart

Clean up a noisy tone, then find out what is in it:

from convolinear import Signal

tone = Signal.sine(440, duration=1.0, sample_rate=8000)
noise = Signal.noise(duration=1.0, sample_rate=8000, amplitude=0.5, seed=42)

cleaned = (tone + noise).bandpass(300, 600).normalize()

spectrum = cleaned.fft()
print(f"Dominant frequency: {spectrum.peak_frequency:.1f} Hz")   # ~440.0 Hz

for freq, magnitude in spectrum.top_n(3):
    print(f"{freq:7.1f} Hz   magnitude {magnitude:.4f}")

Every transformation returns a new object - the original is never modified, and a Signal's sample array is genuinely read-only - so branching from one source is always safe.

Not just audio

Sample rates are floats, and rates below 1 Hz work exactly like any other. Three years of daily temperatures, one sample per day:

sig = Signal(temps, sample_rate=1 / 86400)
cycle_hz = sig.remove_dc().fft(window="hann").peak_frequency
print(f"Dominant period: {1 / cycle_hz / 86400:.0f} days")   # Dominant period: 365 days

Capabilities

• Load from anywhere - WAV, FLAC/OGG/MP3 (via soundfile), CSV, Parquet, NumPy, pandas, MATLAB, or generated tones, noise and arbitrary functions. Sample rates are inferred from dated data.
• Transform - normalize, trim, gain, concat, resample, window, remove DC, reverse, clip, fade.
• Filter - Butterworth lowpass, highpass, bandpass and bandstop.
• Analyse - convolution and correlation, time-delay estimation, peak detection.
• Frequency domain - fft() returns a Spectrum of raw complex coefficients that inverts losslessly; psd() gives a Welch power spectral density; spectrogram() shows how content evolves over time.
• Plot - one-call matplotlib views of any signal, spectrum, PSD or spectrogram.

Documentation

• Full documentation and API reference
• Quickstart - five worked recipes.
• ECG: heart rate from raw samples - raw signal to beats per minute.
• Daily data: finding slow cycles - sub-1 Hz sample rates.
• Benchmarks - measured throughput.
• CHANGELOG - release history and migration notes.

Runnable scripts live in examples/.

Development

If you want to contribute to this project:

1. Fork the repository on GitHub.
2. Set up an editable clone with uv:

git clone https://github.com/yourusername/convolinear
cd convolinear
uv sync
uv run pytest

3. Make a new branch for your edits.
4. Make changes.
5. Run the same checks CI runs:

uv run ruff check .
uv run ruff format --check .
uv run mypy convolinear
uv run pytest

6. Commit changes to your fork.
7. Open a Pull Request.

License

This project is licensed under the MIT License.

Copyright © 2026 Sajid Ahmed