feat(labs): show each marker's slope and where the line would leave the range

The biomarker detail read now carries a trend: the least-squares line
through every numeric reading of the marker (all stored in its unit), with
the slope's 95 % interval and p-value. It needs three readings over at
least a year. The line is placed against the marker's band, and an exit
date is given only when the interval excludes zero, the line is inside the
band today and reaches a bound within three years. The detail page words
it as a straight-line projection, not a forecast.
This commit is contained in:
Marc-André Bombeck committed 2026-10-21 21:51:36 +02:00
1 parent faa3ef867b
commit 2ba6214a65
20 files changed
+993 -11

No files matched your search

+54 -2
View File
@@ -77,6 +77,58 @@ const biomarkerRow = z
"A user-scoped catalog marker. `context` is the decrypted per-marker note (or null); `hasContext` flags its presence. `analyteKey` is the analyte the marker was recognised as: the catalog slug its name belongs to (e.g. `fasting-glucose`, `ldl`, `hdl`), or a key of the unit-conversion registry for an analyte with no catalog seed (e.g. `urea`, `uric-acid`), or null when its name matches none. It is derived from `name` and `unit`, never chosen: it is set on create and re-derived (or cleared) when an update changes either. A reading in another unit is converted only for a marker that has one. `hidden` drops the marker from the active catalog list and the lab-entry pickers without deleting it (its readings and unit/range survive). A `LabResult` linking this marker resolves its unit + reference bounds from here.",
});
const labTrend = z
.union([
z.object({
status: z.literal("ok"),
n: z.number().int(),
firstAt: z.string().describe("YYYY-MM-DD of the first reading."),
lastAt: z.string().describe("YYYY-MM-DD of the newest reading."),
spanDays: z.number().int(),
slopePerYear: z
.number()
.describe("Least-squares change per year, in the marker's unit."),
slopeCi95: z
.tuple([z.number(), z.number()])
.describe("95 % interval of the slope (Student t at n − 2 df)."),
pValue: z.number(),
fittedNow: z.number().describe("The line's value on `asOf`."),
asOf: z.string().describe("YYYY-MM-DD the line was evaluated on."),
projection: z.enum([
"exits",
"beyond_horizon",
"no_exit",
"already_outside",
"no_clear_trend",
"no_band",
]),
exitDate: z
.string()
.nullable()
.describe(
"Only for `exits`: the day the straight line meets `exitBound`. A projection, never a forecast.",
),
exitBound: z.enum(["low", "high"]).nullable(),
}),
z.object({
status: z.literal("insufficient"),
reason: z.enum(["too_few_values", "span_too_short"]),
n: z.number().int(),
spanDays: z.number().int(),
}),
])
.meta({
id: "BiomarkerTrend",
description:
"v1.44 — the least-squares line through every numeric reading of the marker (all stored in the marker's unit). Needs at least three readings spanning at least 365 days, else `insufficient`. `projection` places the line against the marker's band: `exits` (with `exitDate`) only when the slope's 95 % interval excludes zero, the line is inside the band today and reaches a bound within three years. Server-computed; clients render it as given.",
});
const biomarkerDetail = biomarkerRow
.extend({
trend: labTrend.optional().describe("v1.44 — absent on older servers."),
})
.meta({ id: "BiomarkerDetail" });
const listResponse = z
.object({ biomarkers: z.array(biomarkerRow) })
.meta({ id: "ListBiomarkersResponse" });
@@ -191,7 +243,7 @@ export const biomarkerPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Labs"],
summary: "Fetch a single biomarker",
description:
"Returns the biomarker including its decrypted `context` and, since v1.43, its `aliases`. Cross-user rows surface as 404. A marker merged into another answers 404 with `meta.mergedInto`.",
"Returns the biomarker including its decrypted `context`, since v1.43 its `aliases`, and since v1.44 its `trend` over every stored reading. Cross-user rows surface as 404. A marker merged into another answers 404 with `meta.mergedInto`.",
requestParams: { path: z.object({ id: z.string() }) },
responses: {
...recordRefusal(),
@@ -199,7 +251,7 @@ export const biomarkerPaths: NonNullable<ZodOpenApiObject["paths"]> = {
description: "Biomarker detail.",
content: {
"application/json": {
schema: dataEnvelope(biomarkerRow, "GetBiomarkerResponse"),
schema: dataEnvelope(biomarkerDetail, "GetBiomarkerResponse"),
},
},
},