conservation-regime 0.1.0

Unified regime change detection via graph conservation ratio

conservation-regime

Unified regime change detection via graph conservation ratio.

One algorithm for any domain. The conservation ratio drops at regime transitions because the correlation/transition structure that was stable suddenly breaks.

Works on:

• Finance — market crises (conservation drops from ~0.44 to ~0.18)
• Climate — warming onset, heatwaves
• Social — bot injection, viral cascades
• Protein — folding transitions, mutations
• Sensors — failure detection in IoT networks

Install

pip install conservation-regime

Quick Start

import numpy as np
from regime_detection import ConservationRegimeDetector

detector = ConservationRegimeDetector(window=50, threshold_sigma=2.0)

# Any multivariate time series: (timesteps, variables)
data = np.random.randn(500, 10)
result = detector.detect(data)

# Regime changes
for rc in result.regime_changes:
    print(f"Change at t={rc.time}, confidence={rc.confidence:.1f}σ, {rc.direction}")

# Full conservation series
print(f"Conservation: {result.conservation_series}")

How It Works

1. Build graph: Sliding-window correlation matrix → adjacency graph
2. Compute Laplacian: Normalized graph Laplacian captures connectivity
3. Conservation ratio: 1 - (f^T L f) / 2 — how smooth the signal is on the graph
4. Detect: Flag deviations beyond threshold_sigma from baseline

During stable regimes, signals are smooth on the correlation graph → high conservation. At transitions, correlations break → conservation drops.

API

ConservationRegimeDetector

detector = ConservationRegimeDetector(
    window=50,              # baseline window
    threshold_sigma=2.0,    # detection sensitivity
    min_separation=10,      # min timesteps between detections
    graph_type='correlation',  # or 'transition'
    method='conservation',     # or 'spectral_gap'
)

detector.detect(data) → DetectionResult

• regime_changes: List of RegimeChange(time, confidence, direction, ...)
• conservation_series: Full conservation ratio time series
• anomaly_scores: Sigma deviations from baseline
• baseline_mean, baseline_std: Baseline statistics

detector.detect_segments(data) → [(start, end, label), ...]

Returns labeled segments: 'stable' or 'transition'.

Examples

python examples/finance_example.py
python examples/climate_example.py

Testing

pip install -e ".[test]"
pytest tests/

Tests cover all 4 domains: finance, climate, social, protein.

License

MIT