chrono-correlator 0.3.0

Statistical correlation between time-series and discrete events with optional LLM narration

chrono-correlator

A generic statistical engine that correlates time-series data with discrete events using Mann-Whitney U, and narrates results with an LLM only when p < 0.05.

Install

pip install chrono-correlator

Quick start

from datetime import datetime, timedelta
from chrono_correlator import Event, Metric, evaluate, narrate

base = datetime(2024, 1, 1)

events = [
    Event(timestamp=base + timedelta(days=d), label="migraine")
    for d in [10, 20, 30]
]

timestamps = [base + timedelta(hours=h) for h in range(800)]
values = [55.0] * 800
for day in [10, 20, 30]:
    for h in range(48):
        idx = day * 24 - 48 + h
        if 0 <= idx < 800:
            values[idx] = 28.0

hrv = Metric(name="hrv", timestamps=timestamps, values=values)

report = evaluate(events, [hrv])
print(f"Level: {report.level} — {report.active_signals}/{report.total_signals} signals")

if report.level != "green":
    report = narrate(report, provider="groq")
    print(report.narrative)

How it works

• Statistical core: For each metric, values in the 48 h before each event are compared against a 28-day baseline using Mann-Whitney U. Effect size is computed as rank-biserial correlation.
• Alert level: Active signals (p < 0.05) are counted across all metrics. 1–2 → green, 3–4 → yellow, 5–7 → red.
• LLM narration: Only triggered on yellow or red. The model receives pre-calculated statistics and is constrained to one factual sentence per signal — no diagnosis, no causal inference.

Use cases

• Health monitoring — correlate HRV, deep sleep, or skin temperature drops with migraine or crisis events.
• Infrastructure — detect latency or error-rate anomalies preceding service outages.
• IPTV / streaming — link buffering load spikes to subscriber disconnection events.
• Energy consumption — associate power demand patterns with grid stress or equipment failures.

License

GPL-3.0 — Raúl Gallardo (g3v3r)