chrono-correlator 0.5.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

# Core (statistics only — no LLM required)
pip install chrono-correlator

# With specific LLM provider
pip install chrono-correlator[groq]
pip install chrono-correlator[anthropic]
pip install chrono-correlator[ollama]      # local, no API key

# Everything
pip install chrono-correlator[all]

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)

# FDR correction enabled by default — reduces false positives with multiple metrics
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)

From a pandas DataFrame

import pandas as pd
from chrono_correlator import Metric

df = pd.read_csv("hrv_data.csv")   # columns: timestamp, value
hrv = Metric.from_dataframe(df, name="hrv", timestamp_col="timestamp", value_col="value")

Lag analysis

# Test if the signal appears 24h before the event instead of immediately before
report = evaluate(events, metrics, lag_hours=24)

Continuous monitoring (no events needed)

from chrono_correlator import monitor, loop

# Single evaluation at now()
report = monitor(metrics, narrate=False)

# Infinite loop — calls on_alert when level is yellow or red
def alert_handler(report):
    print(f"ALERT {report.level.upper()}: {report.narrative}")

loop(metrics_fn=lambda: metrics, interval_seconds=3600, on_alert=alert_handler)

Custom LLM provider

from chrono_correlator import BaseNarrator

class OllamaNarrator(BaseNarrator):
    def generate(self, prompt: str) -> str:
        # call your local model
        ...

report = OllamaNarrator().narrate(report)

How it works

• Statistical core: For each metric, values in the pre-event window (default: 48 h before, configurable lag) are compared against a 28-day baseline using Mann-Whitney U. Effect size is computed as rank-biserial correlation.
• Multiple comparison correction: When analysing several metrics simultaneously, FDR (Benjamini-Hochberg) correction is applied by default to control false positives. Bonferroni is also available.
• Alert level: Corrected active signals (p < 0.05) are counted. 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

MIT — Raúl Gallardo (g3v3r)