mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-18 16:12:11 +00:00
feat(cycle): symptom-by-phase patterns on the insights tab
Add the cycle-native counterpart to the phase×vitals crosstab: for each logged symptom, where in the cycle it clusters. A pure aggregator tallies each symptom's occurrences across the phase-labelled days (the same phase map the calendar uses), surfaces only symptoms logged on at least three phased days, and reports per-phase counts + the dominant phase + its share. The insights tab renders it as a proportional phase-hued bar with the dominant phase named in words (never colour-only), observational and never causal. Also correct the phase-crosstab OpenAPI row enum, which had drifted behind the runtime (mood + glucose channels were missing). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
d2da8d2657
commit
eec3557137
14 files changed
+447
-7
No files matched your search
@@ -0,0 +1,67 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
|
||||
import {
|
||||
computeSymptomPhasePatterns,
|
||||
SYMPTOM_PHASE_MIN_DAYS,
|
||||
type SymptomDay,
|
||||
} from "../symptom-phase";
|
||||
import type { CyclePhase } from "../types";
|
||||
|
||||
function phaseMap(entries: [string, CyclePhase][]): Map<string, CyclePhase> {
|
||||
return new Map(entries);
|
||||
}
|
||||
|
||||
describe("computeSymptomPhasePatterns", () => {
|
||||
it("clusters a symptom into its dominant phase", () => {
|
||||
const days: SymptomDay[] = [
|
||||
{ date: "2026-06-01", keys: ["cramps"] },
|
||||
{ date: "2026-06-02", keys: ["cramps"] },
|
||||
{ date: "2026-06-03", keys: ["cramps"] },
|
||||
{ date: "2026-06-20", keys: ["cramps"] },
|
||||
];
|
||||
const phases = phaseMap([
|
||||
["2026-06-01", "MENSTRUAL"],
|
||||
["2026-06-02", "MENSTRUAL"],
|
||||
["2026-06-03", "MENSTRUAL"],
|
||||
["2026-06-20", "LUTEAL"],
|
||||
]);
|
||||
const [row] = computeSymptomPhasePatterns(days, phases);
|
||||
expect(row.symptomKey).toBe("cramps");
|
||||
expect(row.total).toBe(4);
|
||||
expect(row.counts.MENSTRUAL).toBe(3);
|
||||
expect(row.counts.LUTEAL).toBe(1);
|
||||
expect(row.topPhase).toBe("MENSTRUAL");
|
||||
expect(row.topShare).toBeCloseTo(0.75, 5);
|
||||
});
|
||||
|
||||
it("drops symptoms below the min-day floor", () => {
|
||||
const days: SymptomDay[] = [
|
||||
{ date: "2026-06-01", keys: ["rare"] },
|
||||
{ date: "2026-06-02", keys: ["rare"] },
|
||||
];
|
||||
const phases = phaseMap([
|
||||
["2026-06-01", "MENSTRUAL"],
|
||||
["2026-06-02", "FOLLICULAR"],
|
||||
]);
|
||||
// 2 < SYMPTOM_PHASE_MIN_DAYS (3) → no row.
|
||||
expect(SYMPTOM_PHASE_MIN_DAYS).toBe(3);
|
||||
expect(computeSymptomPhasePatterns(days, phases)).toHaveLength(0);
|
||||
});
|
||||
|
||||
it("ignores symptom days that fall outside any phase window", () => {
|
||||
const days: SymptomDay[] = [
|
||||
{ date: "2026-06-01", keys: ["cramps"] },
|
||||
{ date: "2026-06-02", keys: ["cramps"] },
|
||||
{ date: "2026-06-03", keys: ["cramps"] },
|
||||
{ date: "2026-06-30", keys: ["cramps"] }, // unphased → ignored
|
||||
];
|
||||
const phases = phaseMap([
|
||||
["2026-06-01", "LUTEAL"],
|
||||
["2026-06-02", "LUTEAL"],
|
||||
["2026-06-03", "LUTEAL"],
|
||||
]);
|
||||
const [row] = computeSymptomPhasePatterns(days, phases);
|
||||
expect(row.total).toBe(3);
|
||||
expect(row.counts.LUTEAL).toBe(3);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,95 @@
|
||||
/**
|
||||
* v1.15.0 — symptom-by-phase pattern aggregation.
|
||||
*
|
||||
* The cycle-NATIVE counterpart to the phase×vitals crosstab: for each logged
|
||||
* symptom, where in the cycle does it cluster? Pure + DB-free — the gated
|
||||
* `/api/cycle/insights` route does the reads and the gender gate, then hands the
|
||||
* already-fetched per-day symptom keys + the phase-day map (built identically to
|
||||
* the calendar grid) to this function.
|
||||
*
|
||||
* Honest, never causal: a symptom is surfaced only once it has been logged on at
|
||||
* least `SYMPTOM_PHASE_MIN_DAYS` phase-labelled days, so a one-off entry never
|
||||
* produces a "pattern". The output reports the raw per-phase counts and the
|
||||
* dominant phase + its share, so the UI states "logged mostly in your luteal
|
||||
* phase (7 of 9 days)" — an observation, not a diagnosis.
|
||||
*/
|
||||
import type { CyclePhase } from "@/lib/cycle/types";
|
||||
|
||||
/** A symptom must appear on at least this many phased days to surface a pattern. */
|
||||
export const SYMPTOM_PHASE_MIN_DAYS = 3;
|
||||
|
||||
/** Cap the surfaced rows so the card stays scannable (most-logged first). */
|
||||
export const SYMPTOM_PHASE_MAX_ROWS = 10;
|
||||
|
||||
const PHASES: CyclePhase[] = ["MENSTRUAL", "FOLLICULAR", "OVULATORY", "LUTEAL"];
|
||||
|
||||
/** One day's logged symptom keys (presence only — severity is not needed here). */
|
||||
export interface SymptomDay {
|
||||
date: string;
|
||||
keys: readonly string[];
|
||||
}
|
||||
|
||||
export interface SymptomPhasePatternRow {
|
||||
symptomKey: string;
|
||||
/** Per-phase count of phase-labelled days this symptom was logged. */
|
||||
counts: Record<CyclePhase, number>;
|
||||
/** Total phase-labelled days the symptom was logged (sum of `counts`). */
|
||||
total: number;
|
||||
/** The phase the symptom clusters in most. */
|
||||
topPhase: CyclePhase;
|
||||
/** topPhase count / total, in [0,1] — how concentrated the pattern is. */
|
||||
topShare: number;
|
||||
}
|
||||
|
||||
function emptyCounts(): Record<CyclePhase, number> {
|
||||
return { MENSTRUAL: 0, FOLLICULAR: 0, OVULATORY: 0, LUTEAL: 0 };
|
||||
}
|
||||
|
||||
/**
|
||||
* Tally each symptom's occurrences by cycle phase across the window. Only days
|
||||
* that carry a phase label count (a symptom logged outside any cycle window is
|
||||
* ignored). Rows below the min-day floor are dropped; the rest sort by total
|
||||
* desc (ties broken by key for determinism) and cap at `SYMPTOM_PHASE_MAX_ROWS`.
|
||||
*/
|
||||
export function computeSymptomPhasePatterns(
|
||||
symptomDays: readonly SymptomDay[],
|
||||
phaseByDay: ReadonlyMap<string, CyclePhase>,
|
||||
): SymptomPhasePatternRow[] {
|
||||
const byKey = new Map<string, Record<CyclePhase, number>>();
|
||||
|
||||
for (const day of symptomDays) {
|
||||
const phase = phaseByDay.get(day.date);
|
||||
if (!phase) continue;
|
||||
for (const key of day.keys) {
|
||||
let counts = byKey.get(key);
|
||||
if (!counts) {
|
||||
counts = emptyCounts();
|
||||
byKey.set(key, counts);
|
||||
}
|
||||
counts[phase] += 1;
|
||||
}
|
||||
}
|
||||
|
||||
const rows: SymptomPhasePatternRow[] = [];
|
||||
for (const [symptomKey, counts] of byKey) {
|
||||
const total = PHASES.reduce((s, p) => s + counts[p], 0);
|
||||
if (total < SYMPTOM_PHASE_MIN_DAYS) continue;
|
||||
// Dominant phase — deterministic tie-break by the fixed phase order.
|
||||
let topPhase: CyclePhase = PHASES[0];
|
||||
for (const p of PHASES) {
|
||||
if (counts[p] > counts[topPhase]) topPhase = p;
|
||||
}
|
||||
rows.push({
|
||||
symptomKey,
|
||||
counts,
|
||||
total,
|
||||
topPhase,
|
||||
topShare: counts[topPhase] / total,
|
||||
});
|
||||
}
|
||||
|
||||
rows.sort(
|
||||
(a, b) => b.total - a.total || a.symptomKey.localeCompare(b.symptomKey),
|
||||
);
|
||||
return rows.slice(0, SYMPTOM_PHASE_MAX_ROWS);
|
||||
}
|
||||
@@ -2426,8 +2426,19 @@ const cyclePhaseCrosstabRow = z
|
||||
"basalBodyTemp",
|
||||
"wristTemperature",
|
||||
"skinTemperature",
|
||||
"bloodGlucose",
|
||||
"mood",
|
||||
]),
|
||||
display: z.enum([
|
||||
"hours",
|
||||
"steps",
|
||||
"bpm",
|
||||
"ms",
|
||||
"kg",
|
||||
"celsius",
|
||||
"glucose",
|
||||
"mood",
|
||||
]),
|
||||
display: z.enum(["hours", "steps", "bpm", "ms", "kg", "celsius"]),
|
||||
lutealDays: z.number().int(),
|
||||
follicularDays: z.number().int(),
|
||||
lutealAvg: z.number(),
|
||||
@@ -2460,6 +2471,32 @@ const cyclePhaseLaggedPair = z
|
||||
"One FDR-surviving lagged-Pearson pair from the continuous CYCLE_PHASE ordinal × outcome matrix (mechanism B). Descriptive, never causal.",
|
||||
});
|
||||
|
||||
const cyclePhaseEnumForCount = z.enum([
|
||||
"MENSTRUAL",
|
||||
"FOLLICULAR",
|
||||
"OVULATORY",
|
||||
"LUTEAL",
|
||||
]);
|
||||
|
||||
const cycleSymptomPhaseRow = z
|
||||
.object({
|
||||
symptomKey: z.string(),
|
||||
counts: z.object({
|
||||
MENSTRUAL: z.number().int(),
|
||||
FOLLICULAR: z.number().int(),
|
||||
OVULATORY: z.number().int(),
|
||||
LUTEAL: z.number().int(),
|
||||
}),
|
||||
total: z.number().int(),
|
||||
topPhase: cyclePhaseEnumForCount,
|
||||
topShare: z.number(),
|
||||
})
|
||||
.meta({
|
||||
id: "CycleSymptomPhaseRow",
|
||||
description:
|
||||
"Where a logged symptom clusters across the cycle phases. Surfaced only once logged on ≥3 phase-labelled days. Observational, never causal.",
|
||||
});
|
||||
|
||||
const cycleInsightsResponse = z.object({
|
||||
rows: z.array(cyclePhaseCrosstabRow),
|
||||
headline: cyclePhaseCrosstabRow.nullable(),
|
||||
@@ -2469,6 +2506,7 @@ const cycleInsightsResponse = z.object({
|
||||
fdrQ: z.number(),
|
||||
minPairs: z.number().int(),
|
||||
}),
|
||||
symptomPatterns: z.array(cycleSymptomPhaseRow),
|
||||
contrast: z.object({
|
||||
high: z.literal("LUTEAL"),
|
||||
low: z.literal("FOLLICULAR"),
|
||||
|
||||
Reference in new issue
Block a user