Metadata-Version: 2.4
Name: conservation-regime
Version: 0.1.0
Summary: Unified regime change detection via graph conservation ratio
Home-page: https://github.com/SuperInstance/regime-detection
Author: SuperInstance
Author-email: noreply@superinstance.com
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.19.0
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

```bash
pip install conservation-regime
```

## Quick Start

```python
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`

```python
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

```bash
python examples/finance_example.py
python examples/climate_example.py
```

## Testing

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

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

## License

MIT
