vectrix 0.0.17

Time Series Forecasting Engine — Built-in Rust Acceleration

Documentation · Quick Start · Models · Installation · Usage · Benchmarks · API Reference · Notebooks

◈ What is Vectrix?

Vectrix is a time series forecasting library with a built-in Rust engine. Python syntax, Rust speed — 3 dependencies (NumPy, SciPy, Pandas), no compiler needed. pip install vectrix and the Rust-accelerated engine is included in the wheel.

Forecasting

Pass a list, DataFrame, or CSV path to forecast(). Vectrix runs multiple models (ETS, ARIMA, Theta, TBATS, CES, MSTL), evaluates each with cross-validation, and returns the best prediction with confidence intervals. You don't choose a model — it does.

from vectrix import forecast
result = forecast("sales.csv", steps=12)

Flat-Line Defense

A common failure mode in automated forecasting is flat predictions — the model outputs a constant line. Vectrix includes a detection and correction system that identifies flat outputs and falls back to a model that captures the signal. This is a heuristic defense layer — it reduces flat predictions significantly but is not a guarantee.

Forecast DNA

Before fitting any model, Vectrix profiles your data with 65+ statistical features (trend strength, seasonality strength, entropy, spectral density, etc.) and uses them to recommend which models are likely to work best.

Regression

R-style formula interface with full diagnostics. OLS, Ridge, Lasso, Huber, and Quantile regression are included.

from vectrix import regress
model = regress(data=df, formula="sales ~ temperature + promotion")
print(model.summary())

Diagnostics include Durbin-Watson, Breusch-Pagan, VIF, normality tests, and time series adjustments (Newey-West, Cochrane-Orcutt).

Analysis

analyze() profiles the data and reports changepoints, anomalies, and data characteristics.

from vectrix import analyze
report = analyze(df, date="date", value="sales")
print(report.summary())

Regime Detection & Self-Healing

A pure-numpy HMM (Baum-Welch + Viterbi) detects regime shifts. When a regime change occurs, the self-healing system uses CUSUM + EWMA to detect drift and applies conformal prediction to recalibrate the forecast.

Business Constraints

8 constraint types can be applied to any forecast: non-negative, range, capacity, year-over-year change limit, sum constraint, monotonicity, ratio, and custom functions.

Hierarchical Reconciliation

Bottom-up, top-down, and MinTrace reconciliation for hierarchical time series.

Built-in Rust Engine

Every pip install vectrix includes a pre-built Rust extension — like Polars, no compiler needed. 29 core hot loops are Rust-accelerated across all forecasting engines.

Pre-built wheels for Linux (x86_64), macOS (ARM + x86), and Windows. The Rust engine is included in the default installation — no extras, no flags, no [turbo].

Built-in Sample Datasets

7 ready-to-use datasets for quick testing:

from vectrix import loadSample, forecast

df = loadSample("airline")       # 144 monthly observations
result = forecast(df, date="date", value="passengers", steps=12)

Available: airline, retail, stock, temperature, energy, web, intermittent

Interactive Visualization

Publication-quality dark-themed Plotly charts, built into the library as an optional dependency.

pip install vectrix[viz]

from vectrix import forecast, analyze, loadSample
from vectrix.viz import forecastChart, dnaRadar, forecastReport, analysisReport

df = loadSample("airline")
result = forecast(df, steps=12)
forecastChart(result, historical=df).show()

report = analyze(df)
analysisReport(report).show()

8 chart functions — forecastChart, dnaRadar, modelHeatmap, scenarioChart, backtestChart, metricsCard, forecastReport, analysisReport — all return standard go.Figure objects with a consistent brand theme (dark background, indigo primary).

Minimal Dependencies, Maximum Performance

All of the above — forecasting models, regime detection, regression diagnostics, constraint enforcement, hierarchical reconciliation — runs on just NumPy, SciPy, and Pandas. The Rust engine is compiled into the wheel and loaded automatically. No system dependencies, no compiler, no extra install steps.

◈ Quick Start

pip install vectrix

from vectrix import forecast, loadSample

df = loadSample("airline")
result = forecast(df, date="date", value="passengers", steps=12)
print(result)
result.plot()

◈ Why Vectrix?

Comparison notes: Dependencies counted as direct pip install requirements (not transitive). Vectrix's Rust engine is compiled into the wheel (like Polars) — no separate install needed. statsforecast requires Numba JIT compilation; Prophet requires CmdStan (C++ compiler); Darts requires PyTorch. Feature comparison based on statsforecast 2.0+, Prophet 1.1+, Darts 0.31+.

◈ Models

◈ Installation

pip install vectrix                # Rust engine included — no extras needed
pip install "vectrix[ml]"          # + LightGBM, XGBoost, scikit-learn
pip install "vectrix[all]"         # Everything

◈ Usage

Easy API

from vectrix import forecast, analyze, regress, compare

# Level 1 — Zero Config
result = forecast([100, 120, 115, 130, 125, 140], steps=5)

# Level 2 — Guided Control
result = forecast(df, date="date", value="sales", steps=12,
                  models=["dot", "auto_ets", "auto_ces"],
                  ensemble="mean",
                  confidence=0.90)

print(result.compare())          # All model rankings
print(result.all_forecasts())    # Every model's predictions

report = analyze(df, date="date", value="sales")
print(f"Difficulty: {report.dna.difficulty}")

comparison = compare(df, date="date", value="sales", steps=12)

model = regress(data=df, formula="sales ~ temperature + promotion")
print(model.summary())

DataFrame Workflow

from vectrix import forecast, analyze
import pandas as pd

df = pd.read_csv("data.csv")

report = analyze(df, date="date", value="sales")
print(report.summary())

result = forecast(df, date="date", value="sales", steps=30)
result.plot()
result.to_csv("forecast.csv")

Direct Engine Access

from vectrix.engine import AutoETS, AutoARIMA
from vectrix.adaptive import ForecastDNA

ets = AutoETS(period=7)
ets.fit(data)
pred, lower, upper = ets.predict(30)

dna = ForecastDNA()
profile = dna.analyze(data, period=7)
print(f"Difficulty: {profile.difficulty}")
print(f"Recommended: {profile.recommendedModels}")

Business Constraints

from vectrix.adaptive import ConstraintAwareForecaster, Constraint

caf = ConstraintAwareForecaster()
result = caf.apply(predictions, lower95, upper95, constraints=[
    Constraint('non_negative', {}),
    Constraint('range', {'min': 100, 'max': 5000}),
    Constraint('capacity', {'capacity': 10000}),
    Constraint('yoy_change', {'maxPct': 30, 'historicalData': past_year}),
])

◈ Benchmarks

Evaluated on M4 Competition 100,000 time series (2,000 sample per frequency, seed=42). OWA < 1.0 means better than Naive2.

DOT-Hybrid (single model, OWA 0.848 — beats M4 #2 FFORMA 0.838):

M4 Competition Leaderboard Context:

Full results with sMAPE/MASE breakdown: benchmarks

◈ Interactive Notebooks

Try Vectrix instantly — no setup needed. Click to open in Google Colab.

Tutorials

Notebook	What you'll learn
01 Quickstart	Forecast from list, DataFrame, CSV
02 Analysis & DNA	DNA profiling, changepoints, anomalies
03 Regression	R-style formulas, diagnostics, 5 methods
04 Models	Model comparison, direct engine, flat defense
05 Adaptive	Regime detection, DNA, healing, constraints
06 Business	Anomalies, scenarios, backtest, metrics

Showcase (Plotly)

Notebook	What you'll build
Sales Dashboard	Interactive forecast + DNA radar + scenarios
Demand Planning	Full workflow: quality check → forecast → budget

◈ API Reference

Easy API (Recommended)

All parameters beyond data are optional with sensible defaults. See Progressive Disclosure for the Level 1 → 2 → 3 design.

Classic API

Return Objects

◈ Architecture

vectrix/
├── easy.py               forecast(), analyze(), regress()
├── vectrix.py             Vectrix class — full pipeline
├── types.py               ForecastResult, DataCharacteristics
├── engine/                Forecasting models
│   ├── ets.py               AutoETS (30 combinations)
│   ├── arima.py             AutoARIMA (AICc stepwise)
│   ├── theta.py             Theta method
│   ├── dot.py               Dynamic Optimized Theta
│   ├── ces.py               Complex Exponential Smoothing
│   ├── tbats.py             TBATS / AutoTBATS
│   ├── mstl.py              Multi-Seasonal Decomposition
│   ├── garch.py             GARCH / EGARCH / GJR-GARCH
│   ├── croston.py           Croston Classic / SBA / TSB
│   ├── fourTheta.py         4Theta (M4 Competition method)
│   ├── dtsf.py              Dynamic Time Scan Forecaster
│   ├── esn.py               Echo State Network
│   ├── logistic.py          Logistic Growth
│   ├── hawkes.py            Hawkes Intermittent Demand
│   ├── lotkaVolterra.py     Lotka-Volterra Ensemble
│   ├── phaseTransition.py   Phase Transition Forecaster
│   ├── adversarial.py       Adversarial Stress Tester
│   ├── entropic.py          Entropic Confidence Scorer
│   └── turbo.py             Numba JIT acceleration
├── adaptive/              Regime, self-healing, constraints, DNA
├── regression/            OLS, Ridge, Lasso, Huber, Quantile
├── business/              Anomaly, backtest, what-if, metrics
├── flat_defense/          4-level flat prediction prevention
├── hierarchy/             Bottom-up, top-down, MinTrace
├── intervals/             Conformal + bootstrap intervals
├── ml/                    LightGBM, XGBoost wrappers
├── global_model/          Cross-series forecasting
└── datasets.py            7 built-in sample datasets

rust/                         Built-in Rust engine (29 accelerated functions)
└── src/lib.rs             ETS, ARIMA, DOT, CES, GARCH, DTSF, ESN, 4Theta (PyO3)

◈ AI Integration

Vectrix is designed to be fully accessible to AI assistants. Whether you're using Claude, GPT, Copilot, or any other AI tool, Vectrix provides structured context files that allow any AI to understand the complete API in a single read.

llms.txt — AI-Readable Documentation

The llms.txt standard provides AI assistants with a structured overview of the project, and llms-full.txt contains the complete API reference with every function signature, parameter, return type, and common usage pattern.

Point your AI assistant to llms-full.txt for instant, session-independent understanding of the entire library. No context loss between sessions.

MCP Server — Tool Use for AI Assistants

The Model Context Protocol server exposes Vectrix as callable tools for Claude Desktop, Claude Code, and other MCP-compatible AI assistants.

10 tools: forecast_timeseries, forecast_csv, analyze_timeseries, compare_models, run_regression, detect_anomalies, backtest_model, list_sample_datasets, load_sample_dataset

# Setup with Claude Code
pip install "vectrix[mcp]"
claude mcp add --transport stdio vectrix -- uv run python mcp/server.py

# Setup with Claude Desktop (add to claude_desktop_config.json)
{
    "mcpServers": {
        "vectrix": {
            "command": "uv",
            "args": ["run", "python", "/path/to/mcp/server.py"]
        }
    }
}

Once connected, ask your AI: "Forecast the next 12 months of this sales data" — the AI calls Vectrix directly.

Claude Code Skills

Three specialized skills for Claude Code users:

Skills are auto-loaded when working in the Vectrix project directory.

◈ Philosophy & Roadmap

Identity

Vectrix is a zero-config forecasting engine with built-in Rust acceleration. The design philosophy:

• Python syntax, Rust speed — Like Polars, the Rust engine is invisible. Users write Python; hot loops run in Rust automatically.
• Progressive disclosure — Beginners call forecast(data, steps=12) with zero configuration. Experts pass models=, ensemble=, confidence= to control every aspect. Engine-level access (AutoETS, AutoARIMA) is always available for full control.
• 3 dependencies, no compiler — NumPy, SciPy, Pandas. No system packages, no Numba JIT warmup, no CmdStan. pip install vectrix and you're done.
• Correctness over features — We'd rather have 15 models that beat Naive2 on every frequency than 50 models that fail on Daily and Hourly.

API Layers

Every parameter at Level 2 has a sensible default that reproduces Level 1 behavior. No parameter is ever required.

Roadmap

Expansion Principles

1. Accuracy first, speed second — A wrong answer delivered fast is still wrong. Improve M4 OWA before optimizing latency.
2. Never break zero-config — Every new parameter must have a default. forecast(data, steps=12) must always work.
3. One identity — "Python syntax, Rust speed, zero config." Every feature, doc, and marketing message aligns with this.
4. Benchmark-driven — Every engine change is validated against M4 100K series. No "it seems better" — show the OWA.
5. Minimal dependencies — Adding a dependency requires strong justification. If it can be implemented in numpy/scipy, it should be.

◈ Contributing

git clone https://github.com/eddmpython/vectrix.git
cd vectrix
uv sync --extra dev
uv run pytest

◈ Support

If Vectrix is useful to you, consider supporting the project:

◈ License

MIT — Use freely in personal and commercial projects.