scitex-dsp

Digital signal processing for scientific Python — PAC, Hilbert, wavelet, filters, resampling, demo signals.

Full Documentation · uv pip install scitex-dsp[all]

Problem and Solution

Installation

pip install scitex-dsp

Architecture

scitex_dsp is organised as flat building blocks plus four sub-modules. Public entry points compose left-to-right into typical neuroscience pipelines:

flowchart LR
    raw[(raw LFP / EEG)] --> ensure_3d
    ensure_3d --> reference[reference.common_average]
    reference  --> filt[filt.bandpass]
    filt --> hilbert
    hilbert --> psd
    hilbert --> wavelet
    wavelet --> modulation_index
    modulation_index --> pac
    hilbert --> detect_ripples[detect_ripples]
    psd  --> band_powers[per-band power]

src/scitex_dsp/
├── _hilbert.py   _psd.py        _wavelet.py
├── _pac.py       _modulation_index.py
├── _detect_ripples.py
├── _resample.py  _crop.py       _ensure_3d.py
├── _demo_sig.py  _transform.py
├── filt.py       norm.py        reference.py
├── add_noise.py  params.py      example.py
└── utils/        # ensure_*, zero-pad, differential filters

All public functions accept (channels, samples) or (batch, channels, samples).

Feature Extraction

A named-scalar feature front-end turns a signal (or a PAC map) into a flat, self-documenting {names, values} descriptor — every value is traceable to its registry entry.

import scitex_dsp as dsp

# Canonical PAC-summary set from a PAC map (+ its provenance registry).
feats = dsp.pac_features(pac_z)          # {"names": [...], "values": [...]}
dsp.PAC_FEATURE_REGISTRY                  # what each feature means / how it is computed

# Multi-backend front-end over many engines (pac + catch22) in one call.
out = dsp.extract_all(x, fs)              # {"names": [...], "values": [...]}
dsp.AVAILABLE_BACKENDS                     # ("pac", "catch22")
dsp.extract_all_registry()                 # provenance for every emitted feature

# Real GPU-PAC engine (opt-in); "auto" keeps the CPU-safe default.
pac, f_pha, f_amp = dsp.pac(x, fs, backend="gpac")

# Quantify how much a mixed feature set duplicates itself.
dsp.feature_correlation(X, names)
dsp.redundancy_summary(X, names)
dsp.pca_loadings(X, names)
dsp.correlation_by_group(X, names)

The pip-installable optionals (tensorpac, pycatch22, scikit-learn, sounddevice, and the gpu-pac GPU-PAC engine behind pac(backend="gpac")) ship in a single [all] extra: pip install scitex-dsp[all] (or, for just the GPU engine, pip install gpu-pac).

2 Interfaces

import scitex_dsp as dsp

xx, tt, fs = dsp.demo_sig(sig_type="chirp", fs=1024)
psd, ff = dsp.psd(xx, fs)
xf = dsp.filt.bandpass(xx, fs, bands=[[8, 12]])
hp = dsp.hilbert(xx)
pac, freqs_pha, freqs_amp = dsp.pac(xx, fs)

import scitex
scitex.dsp.demo_sig(sig_type="chirp")  # `scitex.dsp` aliases `scitex_dsp`

Demo

A 13-notebook progressive tutorial lives in examples/, committed with executed cell outputs — read on GitHub without running anything locally.

flowchart LR
    A[01 demo_sig] --> B[02 ensure_3d / crop]
    B --> C[03 norm]
    C --> D[04 filt]
    D --> E[05 hilbert]
    E --> F[06 psd]
    E --> G[07 wavelet]
    D --> H[08 resample]
    A --> I[09 add_noise]
    B --> J[10 reference]
    E --> K[11 modulation_index]
    K --> L[12 pac]
    E --> M[13 detect_ripples]

See examples/README.md for the full index and suggested reading paths.

Re-run them all with ./examples/00_run_all.sh.

Part of SciTeX

scitex-dsp is part of SciTeX.

Install via the umbrella with pip install scitex[dsp], then access as scitex.dsp or run scitex dsp from the CLI.

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.