SignalForge

See the structure in any data, across every scale, instantly.

Install

For the CLI:

pipx install adelic-signalforge
# or, if you have uv:
uv tool install adelic-signalforge

For library use in your own project:

python -m venv .venv && source .venv/bin/activate
pip install adelic-signalforge

Quick Start

# Download sample data (VIX volatility index, 2005-2012)
curl -o vix.csv "https://fred.stlouisfed.org/graph/fredgraph.csv?id=VIXCLS&cosd=2005-01-01&coed=2012-12-31"

# See the structure
sf surface vix.csv -hm --max-window 360

The 2008 financial crisis — visible across every scale at once.

Your data

sf schema mydata.csv                                 # see what it inferred
sf schema mydata.csv --save mydata.schema.json       # save it (correct overrides first if needed)
sf surface mydata.csv --schema mydata.schema.json -hm

Any CSV works. Multi-column, multi-channel, per-entity — sf schema figures it out.

Explore

sf surface data.csv -hm --baseline ewma --residual z    # what's anomalous?
sf surface data.csv -hm --start-date 2008-01 --end-date 2009-06  # zoom in
sf inspect ewma                                          # how does this work?
sf inspect                                               # what's available?

The CLI suggests what to try next. Every output leads somewhere.

Python API

import signalforge as sf

surfaces = (
    sf.load("data.csv")
    .measure(windows=[10, 60, 360])
    .baseline("ewma", alpha=0.1)
    .residual("z")
    .surfaces()
)

For branching and merging — multiple baselines, stacked features:

from signalforge.graph import Input, Measure, Baseline, Residual, Stack, Pipeline

x = Input()
m = Measure()(x)
bl = Baseline("ewma", alpha=0.1)(m)
r = Residual("z")(m, bl)
features = Stack()([m, r])
pipe = Pipeline(x, features)
result = pipe.run(records, windows=[10, 60, 360])

Custom aggregations

Each surface cell reduces a window to a number — by default a mean. SF ships with 20+ aggregations (mean, std, percentiles, spectral energy, dominant frequency, Shannon entropy, ...) and you can add your own:

from signalforge.pipeline.aggregation import register_aggregation

@register_aggregation("iqr")
def iqr(values):
    return float(np.percentile(values, 75) - np.percentile(values, 25))

Across domains

The same pipeline processes financial data, EEG brain recordings, satellite gravity measurements, and generic time series — unchanged.

EEG seizure detection: the top panels show amplitude, the bottom panels show phase relationships between brain hemispheres. The seizure disrupts both — but the phase change is only visible with complex-valued analysis.

Documentation

Quick Start	Zero to heatmap
Your Data	Bring your own data
CLI	All commands
Python API	Chaining and DAG
Examples	VIX, EEG, GRACE, INTERMAGNET
Concepts	How it works
Comparison	vs STFT, wavelets, EMD

License

Business Source License 1.1. See LICENSE.

Free for non-commercial use. Commercial use requires a license from Adelic — contact shun.honda@adelic.org. Converts to Apache 2.0 on 2029-03-22.