/** * Trend calculation utilities for health data. * All functions are pure and work on sorted arrays of {date, value} pairs. */ export interface DataPoint { date: Date; value: number; } // ── Moving Average ─────────────────────────────────────── export function movingAverage( data: DataPoint[], windowDays: number, ): DataPoint[] { if (data.length === 0) return []; const sorted = [...data].sort((a, b) => a.date.getTime() - b.date.getTime()); const result: DataPoint[] = []; const windowMs = windowDays * 24 * 60 * 60 * 1000; for (const point of sorted) { const windowStart = point.date.getTime() - windowMs; const windowPoints = sorted.filter( (p) => p.date.getTime() > windowStart && p.date.getTime() <= point.date.getTime(), ); const avg = windowPoints.reduce((sum, p) => sum + p.value, 0) / windowPoints.length; result.push({ date: point.date, value: Math.round(avg * 100) / 100 }); } return result; } // ── Trend Slope ────────────────────────────────────────── export interface TrendSlope { slope: number; // units per day direction: "up" | "down" | "stable"; confidence: number; // R² value 0-1 } /** * Linear regression slope over the last N days. * Uses least squares fit. * * Window is anchored on `Date.now()`, NOT on the most recent point — so a * stale series (no readings for weeks) returns `null` from this function the * same way `summarize().avg7/avg30` returns `null`. The v3 audit caught the * mismatch where `trendSlope` reported a "trend" from old data while the * dashboard tile correctly hid the average. */ export function trendSlope( data: DataPoint[], windowDays: number, ): TrendSlope | null { if (data.length < 2) return null; const sorted = [...data].sort((a, b) => a.date.getTime() - b.date.getTime()); const cutoff = Date.now() - windowDays * 24 * 60 * 60 * 1000; const window = sorted.filter((p) => p.date.getTime() >= cutoff); if (window.length < 2) return null; // Convert dates to days from start const startTime = window[0].date.getTime(); const points = window.map((p) => ({ x: (p.date.getTime() - startTime) / (24 * 60 * 60 * 1000), y: p.value, })); const n = points.length; const sumX = points.reduce((s, p) => s + p.x, 0); const sumY = points.reduce((s, p) => s + p.y, 0); const sumXY = points.reduce((s, p) => s + p.x * p.y, 0); const sumXX = points.reduce((s, p) => s + p.x * p.x, 0); const denominator = n * sumXX - sumX * sumX; if (denominator === 0) return null; const slope = (n * sumXY - sumX * sumY) / denominator; const intercept = (sumY - slope * sumX) / n; // R² calculation const meanY = sumY / n; const ssTotal = points.reduce((s, p) => s + (p.y - meanY) ** 2, 0); const ssResidual = points.reduce( (s, p) => s + (p.y - (intercept + slope * p.x)) ** 2, 0, ); const rSquared = ssTotal === 0 ? 0 : 1 - ssResidual / ssTotal; const threshold = 0.01; // units per day threshold for "stable" const direction: "up" | "down" | "stable" = Math.abs(slope) < threshold ? "stable" : slope > 0 ? "up" : "down"; return { slope: Math.round(slope * 1000) / 1000, direction, confidence: Math.round(rSquared * 100) / 100, }; } // ── Trend Line Points ──────────────────────────────────── /** * Generate two data points representing the linear trend line endpoints. * Used by chart components to overlay a regression line. */ export function trendLinePoints( data: DataPoint[], windowDays: number, ): { start: DataPoint; end: DataPoint } | null { if (data.length < 2) return null; const sorted = [...data].sort((a, b) => a.date.getTime() - b.date.getTime()); const cutoff = sorted[sorted.length - 1].date.getTime() - windowDays * 24 * 60 * 60 * 1000; const window = sorted.filter((p) => p.date.getTime() >= cutoff); if (window.length < 2) return null; const startTime = window[0].date.getTime(); const points = window.map((p) => ({ x: (p.date.getTime() - startTime) / (24 * 60 * 60 * 1000), y: p.value, })); const n = points.length; const sumX = points.reduce((s, p) => s + p.x, 0); const sumY = points.reduce((s, p) => s + p.y, 0); const sumXY = points.reduce((s, p) => s + p.x * p.y, 0); const sumXX = points.reduce((s, p) => s + p.x * p.x, 0); const denominator = n * sumXX - sumX * sumX; if (denominator === 0) return null; const slope = (n * sumXY - sumX * sumY) / denominator; const intercept = (sumY - slope * sumX) / n; const endDays = points[points.length - 1].x; return { start: { date: window[0].date, value: Math.round(intercept * 100) / 100, }, end: { date: window[window.length - 1].date, value: Math.round((intercept + slope * endDays) * 100) / 100, }, }; } // ── Anomaly Detection ──────────────────────────────────── export interface Anomaly { date: Date; value: number; zScore: number; } /** * Simple z-score anomaly detection. * Returns points with |z-score| > threshold. */ export function detectAnomalies(data: DataPoint[], threshold = 2.0): Anomaly[] { if (data.length < 3) return []; const values = data.map((p) => p.value); const mean = values.reduce((s, v) => s + v, 0) / values.length; const variance = values.reduce((s, v) => s + (v - mean) ** 2, 0) / values.length; const stdDev = Math.sqrt(variance); if (stdDev === 0) return []; return data .map((p) => ({ date: p.date, value: p.value, zScore: Math.round(((p.value - mean) / stdDev) * 100) / 100, })) .filter((a) => Math.abs(a.zScore) > threshold); } // ── Summary Statistics ─────────────────────────────────── export interface DataSummary { count: number; latest: number | null; /** Null when the series is empty (vs the previous 0 sentinel). */ min: number | null; /** Null when the series is empty (vs the previous 0 sentinel). */ max: number | null; /** Null when the series is empty (vs the previous 0 sentinel). */ mean: number | null; avg7: number | null; avg30: number | null; slope7: TrendSlope | null; slope30: TrendSlope | null; slope90: TrendSlope | null; anomalyCount: number; /** * v1.4.16 phase B8 — average value over the 30-day window starting * 30 days before today, i.e. the "last month" prior period the * dashboard tile delta callout compares against. Null when the * window has no data. */ avg30LastMonth?: number | null; /** * v1.4.16 phase B8 — average value over the 30-day window starting * 365 days before today (one calendar year ago). Null when the * window has no data. */ avg30LastYear?: number | null; } export function summarize(data: DataPoint[]): DataSummary { if (data.length === 0) { // Empty series — return null for stats so callers can render an explicit // "no data" state instead of treating 0/0/0 as a real reading. v3 audit // caught the previous {min:0,max:0,mean:0} producing nonsense chart axes. return { count: 0, latest: null, min: null, max: null, mean: null, avg7: null, avg30: null, slope7: null, slope30: null, slope90: null, anomalyCount: 0, avg30LastMonth: null, avg30LastYear: null, }; } const sorted = [...data].sort((a, b) => a.date.getTime() - b.date.getTime()); const values = sorted.map((p) => p.value); const mean = values.reduce((s, v) => s + v, 0) / values.length; const now = Date.now(); const DAY = 24 * 60 * 60 * 1000; const last7 = sorted.filter((p) => now - p.date.getTime() < 7 * DAY); const last30 = sorted.filter((p) => now - p.date.getTime() < 30 * DAY); // v1.4.16 phase B8 — prior-period 30-day means powering the tile // delta callout. The lastMonth window is days [30, 60) ago; the // lastYear window is days [365, 395) ago. Both align to the 30-day // shift the chart overlay uses so the tile delta and the chart // overlay narrate the same comparison. const meanOfWindow = ( minDaysAgo: number, maxDaysAgo: number, ): number | null => { const slice = sorted.filter((p) => { const ageMs = now - p.date.getTime(); return ageMs >= minDaysAgo * DAY && ageMs < maxDaysAgo * DAY; }); if (slice.length === 0) return null; const sum = slice.reduce((s, p) => s + p.value, 0); return Math.round((sum / slice.length) * 100) / 100; }; const avg30LastMonth = meanOfWindow(30, 60); const avg30LastYear = meanOfWindow(365, 395); return { count: data.length, latest: sorted[sorted.length - 1].value, min: Math.min(...values), max: Math.max(...values), mean: Math.round(mean * 100) / 100, avg7: last7.length > 0 ? Math.round( (last7.reduce((s, p) => s + p.value, 0) / last7.length) * 100, ) / 100 : null, avg30: last30.length > 0 ? Math.round( (last30.reduce((s, p) => s + p.value, 0) / last30.length) * 100, ) / 100 : null, slope7: trendSlope(data, 7), slope30: trendSlope(data, 30), slope90: trendSlope(data, 90), anomalyCount: detectAnomalies(data).length, avg30LastMonth, avg30LastYear, }; }