Files
faceclaw/app/apps/nightscout/missed-bolus-detector.ts
T

337 lines
13 KiB
TypeScript

/**
* Missed-bolus detector: given a recent window of CGM readings and
* treatments, decide whether glucose is rising the way an unannounced meal
* does, with no meal bolus, manual bolus or carb entry to account for it.
*
* Deliberately self-contained (no imports; plain data in, plain data out) so
* it can move to the server side of Nightscout unchanged, and so it can be
* iterated on against recorded history with
* scripts/nightscout-missed-bolus-replay.cjs. The Faceclaw side (when to run
* it, cooldown, the glasses notification) is in missed-bolus-monitor.ts.
*
* Glucose is mg/dL throughout: Nightscout stores sgv in mg/dL whatever the
* site's display units.
*/
export type GlucoseReading = { timeMs: number; mgdl: number };
/**
* - meal: a meal/snack/wizard bolus, or any bolus entered together with carbs.
* - manual: a bolus explicitly marked user-initiated (e.g. Loop's `automatic: false`).
* - automatic: a bolus the loop issued (SMB, automatic bolus).
* - ambiguous: not marked either way. OpenAPS on a Medtronic pump uploads its
* SMBs as plain "Correction Bolus" records, indistinguishable from a manual
* correction except by size; `ambiguousBolusMinUnits` decides.
*/
export type BolusKind = "meal" | "manual" | "automatic" | "ambiguous";
export type BolusEvent = { timeMs: number; units: number; kind: BolusKind };
export type CarbEntry = { timeMs: number; grams: number };
export type MissedBolusInput = {
/** The time to classify as of. Readings and treatments after it are ignored. */
nowMs: number;
glucose: readonly GlucoseReading[];
boluses: readonly BolusEvent[];
carbs: readonly CarbEntry[];
};
export type MissedBolusOptions = {
/** The latest reading must be at most this old, or there is nothing current to judge. */
maxReadingAgeMs: number;
/** How far back from the latest reading to look for where the rise started. */
lookbackMs: number;
/** A gap between readings longer than this ends the window (the CGM dropped out). */
maxGapMs: number;
/** Recent span the rate of rise is fitted over (least squares). */
slopeWindowMs: number;
/** Fewest readings the rate fit needs. */
minSlopeReadings: number;
/** Rise from the window's lowest reading to the latest. */
minRiseMgdl: number;
/** The latest reading must be at least this high. */
minGlucoseMgdl: number;
/** Rises from below this are taken as recovering from a low (rescue carbs go unbolused). */
hypoNadirMgdl: number;
/** The rise must have lasted at least this long, to rule out sensor noise. */
minRiseDurationMs: number;
/** Rate of rise over the slope window, mg/dL per minute. */
minRateMgdlPerMin: number;
/** A bolus or carb entry this long before the rise began still accounts for it (pre-bolusing). */
preBolusWindowMs: number;
/** Smallest meal or manual bolus that accounts for a rise. */
minManualBolusUnits: number;
/** Smallest unmarked bolus taken as manual rather than an SMB. */
ambiguousBolusMinUnits: number;
/** Whether a carb entry with no bolus accounts for a rise (the user evidently knows they ate). */
carbsCountAsAnnouncement: boolean;
};
export const DEFAULT_MISSED_BOLUS_OPTIONS: Readonly<MissedBolusOptions> = {
maxReadingAgeMs: 12 * 60_000,
lookbackMs: 90 * 60_000,
maxGapMs: 16 * 60_000,
slopeWindowMs: 20 * 60_000,
minSlopeReadings: 3,
minRiseMgdl: 40,
minGlucoseMgdl: 140,
hypoNadirMgdl: 70,
minRiseDurationMs: 20 * 60_000,
minRateMgdlPerMin: 1.5,
preBolusWindowMs: 60 * 60_000,
minManualBolusUnits: 0.5,
ambiguousBolusMinUnits: 1.5,
carbsCountAsAnnouncement: true,
};
export type GlucoseRise = {
/** When the rise started: the lowest reading in the window (the latest, if tied). */
onsetMs: number;
nadirMgdl: number;
latestMs: number;
latestMgdl: number;
riseMgdl: number;
/** Least-squares rate over the slope window, mg/dL per minute. */
rateMgdlPerMin: number;
};
export type MissedBolusClassification = "missed-bolus" | "no-alert" | "insufficient-data";
export type MissedBolusResult = {
classification: MissedBolusClassification;
/** One-line explanation, for logs and the replay tool. */
reason: string;
/** The rise that was judged, when there was enough data to measure one. */
rise: GlucoseRise | null;
};
export function detectMissedBolus(
input: MissedBolusInput,
overrides: Partial<MissedBolusOptions> = {},
): MissedBolusResult {
const options: MissedBolusOptions = { ...DEFAULT_MISSED_BOLUS_OPTIONS, ...overrides };
const { nowMs } = input;
const readings = usableReadings(input.glucose, nowMs);
const latest = readings[readings.length - 1];
if (!latest) return insufficient("no glucose readings");
if (nowMs - latest.timeMs > options.maxReadingAgeMs) {
return insufficient(`latest reading is ${formatMinutes(nowMs - latest.timeMs)} old`);
}
// The contiguous run of readings ending at the latest, within the lookback.
const windowStartMs = latest.timeMs - options.lookbackMs;
let first = readings.length - 1;
while (first > 0) {
const previous = readings[first - 1]!;
if (previous.timeMs < windowStartMs || readings[first]!.timeMs - previous.timeMs > options.maxGapMs) break;
first--;
}
const window = readings.slice(first);
let nadir = window[0]!;
for (const reading of window) {
if (reading.mgdl <= nadir.mgdl) nadir = reading;
}
const slopeStartMs = Math.max(nadir.timeMs, latest.timeMs - options.slopeWindowMs);
const slopeReadings = window.filter((reading) => reading.timeMs >= slopeStartMs);
const rise: GlucoseRise = {
onsetMs: nadir.timeMs,
nadirMgdl: nadir.mgdl,
latestMs: latest.timeMs,
latestMgdl: latest.mgdl,
riseMgdl: latest.mgdl - nadir.mgdl,
rateMgdlPerMin: slopeReadings.length >= 2 ? slopePerMinute(slopeReadings) : 0,
};
const noAlert = (reason: string): MissedBolusResult => ({ classification: "no-alert", reason, rise });
if (rise.riseMgdl < options.minRiseMgdl) {
return noAlert(`rise of ${rise.riseMgdl} mg/dL is under ${options.minRiseMgdl}`);
}
if (latest.mgdl < options.minGlucoseMgdl) {
return noAlert(`glucose ${latest.mgdl} mg/dL is under ${options.minGlucoseMgdl}`);
}
if (nadir.mgdl < options.hypoNadirMgdl) {
return noAlert(`rising from a low of ${nadir.mgdl} mg/dL`);
}
if (latest.timeMs - nadir.timeMs < options.minRiseDurationMs) {
return noAlert(`rise has lasted only ${formatMinutes(latest.timeMs - nadir.timeMs)}`);
}
if (slopeReadings.length < options.minSlopeReadings) {
return { classification: "insufficient-data", reason: `only ${slopeReadings.length} readings to fit a rate`, rise };
}
if (rise.rateMgdlPerMin < options.minRateMgdlPerMin) {
return noAlert(`rising ${formatRate(rise.rateMgdlPerMin)}, under ${formatRate(options.minRateMgdlPerMin)}`);
}
const coverStartMs = nadir.timeMs - options.preBolusWindowMs;
const inCoverWindow = (timeMs: number) => timeMs >= coverStartMs && timeMs <= nowMs;
const bolus = latestMatching(input.boluses, (event) => inCoverWindow(event.timeMs) && accountsForRise(event, options));
if (bolus) {
return noAlert(`${formatUnits(bolus.units)} U ${bolus.kind} bolus ${formatMinutes(nowMs - bolus.timeMs)} ago`);
}
if (options.carbsCountAsAnnouncement) {
const carbs = latestMatching(input.carbs, (entry) => inCoverWindow(entry.timeMs) && entry.grams > 0);
if (carbs) return noAlert(`${carbs.grams} g carbs entered ${formatMinutes(nowMs - carbs.timeMs)} ago`);
}
return {
classification: "missed-bolus",
reason: `up ${rise.riseMgdl} mg/dL in ${formatMinutes(latest.timeMs - nadir.timeMs)}, rising ${formatRate(rise.rateMgdlPerMin)}, no bolus`,
rise,
};
}
function insufficient(reason: string): MissedBolusResult {
return { classification: "insufficient-data", reason, rise: null };
}
function accountsForRise(bolus: BolusEvent, options: MissedBolusOptions): boolean {
switch (bolus.kind) {
case "meal":
case "manual":
return bolus.units >= options.minManualBolusUnits;
case "ambiguous":
return bolus.units >= Math.max(options.minManualBolusUnits, options.ambiguousBolusMinUnits);
case "automatic":
return false;
}
}
/**
* Finite, in-range readings at or before now, oldest first, one per
* timestamp. Dexcom reports 39 for "LOW" and smaller values as error codes.
*/
function usableReadings(glucose: readonly GlucoseReading[], nowMs: number): GlucoseReading[] {
const sorted = glucose
.filter((reading) => Number.isFinite(reading.timeMs) && Number.isFinite(reading.mgdl)
&& reading.mgdl >= 39 && reading.mgdl <= 600 && reading.timeMs <= nowMs)
.slice()
.sort((a, b) => a.timeMs - b.timeMs);
return sorted.filter((reading, index) => index === 0 || reading.timeMs !== sorted[index - 1]!.timeMs);
}
/** Least-squares slope through the readings, in mg/dL per minute. */
function slopePerMinute(readings: readonly GlucoseReading[]): number {
const t0 = readings[0]!.timeMs;
const n = readings.length;
let sumX = 0, sumY = 0, sumXY = 0, sumXX = 0;
for (const reading of readings) {
const x = (reading.timeMs - t0) / 60_000;
sumX += x;
sumY += reading.mgdl;
sumXY += x * reading.mgdl;
sumXX += x * x;
}
const denominator = n * sumXX - sumX * sumX;
return denominator > 0 ? (n * sumXY - sumX * sumY) / denominator : 0;
}
function latestMatching<T extends { timeMs: number }>(events: readonly T[], predicate: (event: T) => boolean): T | null {
let found: T | null = null;
for (const event of events) {
if (predicate(event) && (!found || event.timeMs > found.timeMs)) found = event;
}
return found;
}
function formatMinutes(ms: number): string {
return `${Math.round(ms / 60_000)} min`;
}
function formatRate(mgdlPerMin: number): string {
return `${mgdlPerMin.toFixed(1)} mg/dL/min`;
}
function formatUnits(units: number): string {
return `${Math.round(units * 100) / 100}`;
}
// ---------------------------------------------------------------------------
// Nightscout record normalization, shared by the Faceclaw bridge and a
// server-side port.
/** The fields of a Nightscout treatment record the detector reads. */
export type NightscoutTreatmentRecord = {
eventType?: unknown;
created_at?: unknown;
timestamp?: unknown;
insulin?: unknown;
carbs?: unknown;
automatic?: unknown;
isSMB?: unknown;
type?: unknown;
wizard?: unknown;
};
/** The fields of a Nightscout entry record the detector reads. */
export type NightscoutEntryRecord = { date?: unknown; sgv?: unknown };
const MEAL_BOLUS_EVENT_TYPES = new Set(["Meal Bolus", "Snack Bolus", "Bolus Wizard", "Combo Bolus"]);
/**
* How a treatment's insulin was given. Uploaders mark automatic boluses
* differently: Loop sets `automatic`, AndroidAPS `isSMB`, Trio/OpenAPS
* `type: "SMB"` or eventType "SMB". Meal boluses carry carbs or a wizard
* record, or a meal-type eventType.
*/
export function bolusKindFromTreatment(treatment: NightscoutTreatmentRecord): BolusKind {
const eventType = typeof treatment.eventType === "string" ? treatment.eventType : "";
if (treatment.automatic === true || treatment.isSMB === true || treatment.type === "SMB" || eventType === "SMB") {
return "automatic";
}
if (MEAL_BOLUS_EVENT_TYPES.has(eventType) || positiveNumber(treatment.carbs) !== null
|| (typeof treatment.wizard === "object" && treatment.wizard !== null)) {
return "meal";
}
if (treatment.automatic === false || treatment.isSMB === false) return "manual";
return "ambiguous";
}
/** Boluses and carb entries from raw Nightscout treatment records, oldest first. */
export function normalizeNightscoutTreatments(treatments: readonly NightscoutTreatmentRecord[]): {
boluses: BolusEvent[];
carbs: CarbEntry[];
} {
const boluses: BolusEvent[] = [];
const carbs: CarbEntry[] = [];
for (const treatment of treatments) {
const timeMs = treatmentTimeMs(treatment);
if (timeMs === null) continue;
const units = positiveNumber(treatment.insulin);
if (units !== null) boluses.push({ timeMs, units, kind: bolusKindFromTreatment(treatment) });
const grams = positiveNumber(treatment.carbs);
if (grams !== null) carbs.push({ timeMs, grams });
}
boluses.sort((a, b) => a.timeMs - b.timeMs);
carbs.sort((a, b) => a.timeMs - b.timeMs);
return { boluses, carbs };
}
/** Glucose readings from raw Nightscout sgv entries, oldest first. */
export function normalizeNightscoutEntries(entries: readonly NightscoutEntryRecord[]): GlucoseReading[] {
const readings: GlucoseReading[] = [];
for (const entry of entries) {
const timeMs = Number(entry.date);
const mgdl = Number(entry.sgv);
if (Number.isFinite(timeMs) && timeMs > 0 && Number.isFinite(mgdl)) readings.push({ timeMs, mgdl });
}
return readings.sort((a, b) => a.timeMs - b.timeMs);
}
function treatmentTimeMs(treatment: NightscoutTreatmentRecord): number | null {
for (const value of [treatment.created_at, treatment.timestamp]) {
if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
if (typeof value === "string" && value.trim()) {
const numeric = Number(value);
const parsed = Number.isFinite(numeric) ? numeric : Date.parse(value);
if (Number.isFinite(parsed) && parsed > 0) return parsed;
}
}
return null;
}
function positiveNumber(value: unknown): number | null {
if (typeof value !== "number" && typeof value !== "string") return null;
if (typeof value === "string" && !value.trim()) return null;
const numeric = Number(value);
return Number.isFinite(numeric) && numeric > 0 ? numeric : null;
}