Metadata-Version: 2.4
Name: refstat
Version: 0.1.0
Summary: Distance-based deviation scoring, reference standardisation, and temporal pattern decomposition for small reference sets (n as low as 3).
Author: Cindy Steward
License: MIT
Project-URL: Repository, https://github.com/cindysteward/refstat
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.7
Requires-Dist: scikit-learn>=1.0
Dynamic: license-file

# refstat

Distance-based deviation scoring, reference standardisation, and temporal pattern decomposition, built for the common case where you only have a small trusted reference set (3-10 observations), not the ~100s or ~1000s most tooling assumes.

## Install
```bash
pip install refstat
```

## What's here

- `refstat.scorers` : Mahalanobis distance (Ledoit-Wolf shrinkage, stable down to n=3), nearest-centroid distance, a composite scoring helper, and leave-one-out calibration (`reference_composite_range`, `classify_against_reference`) so a score is interpreted against your specific reference set, not a fixed threshold
- `refstat.baseline` : build reference statistics from a small set of observations and standardise new observations against them
- `refstat.dtw_patterns` : separates "started late," "took longer once started but moved correctly," and "moved differently" in repeated signal comparisons, using Sakoe-Chiba banded DTW

## Example
```python
import numpy as np
from refstat.scorers import MahalanobisScorer, reference_composite_range, classify_against_reference

reference = np.array([[1.0, 2.1], [1.1, 1.9], [0.9, 2.0]])
scorer = MahalanobisScorer()
scorer.fit(reference)

score = scorer.score(np.array([5.0, 5.0]))
ref_low, ref_high = reference_composite_range(reference)
print(classify_against_reference(score, ref_low, ref_high))  # within_range / borderline / above_range
```

See `examples/reference_screening_example.py` for a full workflow combining reference standardisation, composite scoring, and calibrated interpretation.

## Motivation

Most anomaly detection tooling needs enough data to estimate density or covariance reliably. When you only have a handful of trusted reference points, those methods either fail outright or give unstable results. This targets that regime specifically:

- **Per-unit quality control** : score a newly calibrated machine or unit against its own 3-5 test runs, not a factory-wide spec
- **Personal baseline monitoring** : score a new reading against one person's own recent history, not a population norm that may not fit them
- **New-deployment anomaly detection** : a new sensor or site needs to start flagging problems from day one, before weeks of data exist to build a standard model
- **Small-cohort research** : compare a new case against a small reference cohort when a large population dataset doesn't exist for the condition being studied

## License
MIT
