diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d340f976..7ae44875d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,7 +19,7 @@ stay under for any nutrient on the energy card; the chart draws your number instead of the reference. Targets travel in the full backup and are read and set through `GET` and `PATCH /api/nutrients/targets`. (#1402) -- Lab results from Apple Health's Health Records now land in Labs. An Apple Health export used to skip every clinical record; the lab results among them are now read, matched to your existing markers (by name, alias or LOINC code, with a reading in another unit converted and the printed value kept), and filed under their panel. A result like "<0.5 mg/L" is kept as printed, the report's own reference range comes along, and preliminary or withdrawn results are left out. Importing the same results again writes nothing, a result you delete stays deleted (also when you delete its whole marker, long after the deletion, and across a backup restore), and a reading you already typed or scanned is not doubled. If you imported an archive before, upload it once more to pick up its lab results. For the iOS app, `POST /api/labs/fhir-batch` takes the same results straight from HealthKit. Thanks to @camiracode for asking for this. (#1400) +- Lab results from Apple Health's Health Records now land in Labs. An Apple Health export used to skip every clinical record; the lab results among them are now read, matched to your existing markers (by name, alias or LOINC code, with a reading in another unit converted and the printed value kept), and filed under their panel. A result like "<0.5 mg/L" is kept as printed, a specific gravity, pH or INR sent without a unit is read as a plain number, the report's own reference range comes along, and preliminary or withdrawn results are left out. Importing the same results again writes nothing, a result you delete stays deleted (also when you delete its whole marker, long after the deletion, and across a backup restore), and a reading you already typed or scanned is not doubled. If you imported an archive before, upload it once more to pick up its lab results. For the iOS app, `POST /api/labs/fhir-batch` takes the same results straight from HealthKit. Thanks to @camiracode for asking for this. (#1400) ### Changed diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml index 54c83a460..6955b58d6 100644 --- a/docs/api/openapi.yaml +++ b/docs/api/openapi.yaml @@ -78305,13 +78305,15 @@ components: - status additionalProperties: false description: "One record's outcome, by its position in the request. `inserted`: written. `duplicate`: the record already - holds it, under the same identity (deleted readings included, so a deleted result stays deleted) or as the same - reading on the same day from another source. `skipped`: not a reading HealthLog keeps, with `reason` - `not_observation` | `not_lab` | `not_final` (preliminary; it is taken once final) | `withdrawn` | `panel_header` - | `no_value` | `unsupported_value` | `no_date` | `future_date` | `invalid_date` | `too_large` (a resource over - 256 KiB). `failed`: a reading that could not be stored, with `reason` `missing_unit` | `unit_mismatch` (the - account's marker is in a unit this one does not convert into) | `text_too_long` | `write_failed` (transient: - send it again)." + holds it, under the same identity (deleted readings included, also once the reading or its whole marker is gone, + so a deleted result stays deleted) or as the same reading on the same day from another source. `skipped`: not a + reading HealthLog keeps, with `reason` `not_observation` | `not_lab` (no category names a lab; a code, display + or text containing `lab` in any case counts) | `not_final` (preliminary; it is taken once final) | `withdrawn` | + `panel_header` | `no_value` | `unsupported_value` | `no_date` | `future_date` | `invalid_date` | `too_large` (a + resource over 256 KiB). `failed`: a reading that could not be stored, with `reason` `missing_unit` (a number + without a unit; a specific gravity, a pH or an INR, known by its LOINC code, is read as the unity `1` instead) | + `unit_mismatch` (the account's marker is in a unit this one does not convert into) | `text_too_long` | + `write_failed` (transient: send it again)." LabOverviewEnvelope: type: object properties: diff --git a/src/lib/labs/fhir-import/__tests__/map-observation.test.ts b/src/lib/labs/fhir-import/__tests__/map-observation.test.ts index d19094844..2bb033314 100644 --- a/src/lib/labs/fhir-import/__tests__/map-observation.test.ts +++ b/src/lib/labs/fhir-import/__tests__/map-observation.test.ts @@ -196,6 +196,63 @@ describe("mapFhirLabRecord — R4", () => { expect(map(resource)).toMatchObject({ kind: "fail", reason }); }); + describe("a number printed without a unit", () => { + const loinc = (code: string, text: string) => ({ + text, + coding: [{ system: "http://loinc.org", code }], + }); + + it.each([ + ["urine specific gravity", loinc("5811-5", "Specific Gravity"), 1.015], + ["urine pH", loinc("5803-2", "pH, Urine"), 6], + ["INR", loinc("6301-6", "INR"), 1.1], + ])("is the unity for %s", (_label, code, value) => { + const r = reading(map(base({ code, valueQuantity: { value } }))); + expect(r.value).toBe(value); + expect(r.unit).toBe("1"); + }); + + it("is the unity for a dimensionless integer", () => { + const r = reading( + map( + base({ + code: loinc("2756-5", "pH"), + valueQuantity: undefined, + valueInteger: 7, + }), + ), + ); + expect(r.value).toBe(7); + expect(r.unit).toBe("1"); + }); + + it("still fails for an analyte that has a unit", () => { + expect( + map( + base({ + code: loinc("2951-2", "Sodium"), + valueQuantity: { value: 140 }, + }), + ), + ).toMatchObject({ kind: "fail", reason: "missing_unit" }); + }); + }); + + it.each([ + [{ coding: [{ code: "LAB" }] }], + [{ coding: [{ code: "lab" }] }], + [{ coding: [{ code: "x", display: "Lab Results" }] }], + [{ text: "Laboratory results" }], + ])("reads a lab category however the source spells it: %j", (category) => { + expect(map(base({ category: [category] })).kind).toBe("reading"); + }); + + it("still skips a category that is not a lab", () => { + expect( + map(base({ category: [{ coding: [{ code: "vital-signs" }] }] })), + ).toMatchObject({ kind: "skip", reason: "not_lab" }); + }); + it("accepts a resource with no category", () => { expect(map(base({ category: undefined })).kind).toBe("reading"); }); diff --git a/src/lib/labs/fhir-import/map-observation.ts b/src/lib/labs/fhir-import/map-observation.ts index d873a1998..bee31a28d 100644 --- a/src/lib/labs/fhir-import/map-observation.ts +++ b/src/lib/labs/fhir-import/map-observation.ts @@ -30,6 +30,7 @@ import { parseReferenceRange, SOURCE_REFERENCE_TEXT_MAX, } from "@/lib/labs/parse-reference-range"; +import { DIMENSIONLESS_UNIT } from "@/lib/labs/dimensionless"; import { LAB_TEXT_LIMITS } from "@/lib/labs/reading-keys"; import { sameLabUnit } from "@/lib/labs/unit-normalise"; @@ -40,7 +41,7 @@ import type { FhirLabSkipReason, MappedFhirLab, } from "./types"; -import { labUnitFromFhirQuantity } from "./units"; +import { isDimensionlessLoinc, labUnitFromFhirQuantity } from "./units"; /** A reading dated more than a day ahead is a mistake, not a result. */ const FUTURE_SLACK_MS = 86_400_000; @@ -122,11 +123,20 @@ function memberRefs(resource: Json): string[] { return refs; } +/** + * Whether a category names lab results. FHIR's own code is "laboratory", but + * a record reaches the import only because Apple Health already filed it as + * a lab result (or the phone sends lab records alone), and systems spell the + * category their own way ("LAB", "Lab Results"). Any code, display or text + * naming a lab counts; a record whose categories are all something else (vital + * signs, say) is still left out. + */ function isLaboratory(concept: Json): boolean { - if (str(concept.text)?.toLowerCase() === "laboratory") return true; - return codings(concept).some( - (c) => str(c.code)?.toLowerCase() === "laboratory", - ); + const names = [ + str(concept.text), + ...codings(concept).flatMap((c) => [str(c.code), str(c.display)]), + ]; + return names.some((name) => name !== null && /lab/i.test(name)); } function analyteName(code: Json | null): string | null { @@ -229,12 +239,18 @@ type ValueRead = | { ok: false; skip?: FhirLabSkipReason; fail?: FhirLabFailureReason } | null; -function readValue(resource: Json): ValueRead { +/** + * `dimensionless` says the analyte's value has no unit (its LOINC code is a + * specific gravity, a pH or an INR): a bare number is then the unity "1" + * rather than a number whose unit was dropped. + */ +function readValue(resource: Json, dimensionless: boolean): ValueRead { + const bare = dimensionless ? DIMENSIONLESS_UNIT : null; const quantity = obj(resource.valueQuantity); if (quantity) { const value = num(quantity.value); if (value === null) return { ok: false, skip: "no_value" }; - const unit = labUnitFromFhirQuantity(quantity); + const unit = labUnitFromFhirQuantity(quantity) ?? bare; const comparator = str(quantity.comparator); if (comparator) { const printed = @@ -247,7 +263,9 @@ function readValue(resource: Json): ValueRead { return { ok: true, value, valueText: null, unit }; } if (Number.isSafeInteger(resource.valueInteger)) { - return { ok: false, fail: "missing_unit" }; + if (!bare) return { ok: false, fail: "missing_unit" }; + const value = resource.valueInteger as number; + return { ok: true, value, valueText: null, unit: bare }; } const text = str(resource.valueString); if (text) return { ok: true, value: null, valueText: text, unit: null }; @@ -362,7 +380,8 @@ export function mapFhirLabRecord( return fail("text_too_long"); } - let read = readValue(resource); + const loinc = loincCode(code); + let read = readValue(resource, isDimensionlessLoinc(loinc)); if (read === null && resource.dataAbsentReason !== undefined) { read = { ok: false, skip: "no_value" }; } @@ -403,7 +422,6 @@ export function mapFhirLabRecord( } if (takenAt.getTime() < EARLIEST) return skip("invalid_date", members); - const loinc = loincCode(code); const range = referenceRangeOf(resource, read.unit); return { diff --git a/src/lib/labs/fhir-import/units.ts b/src/lib/labs/fhir-import/units.ts index 0ad2e474f..2b87b68fc 100644 --- a/src/lib/labs/fhir-import/units.ts +++ b/src/lib/labs/fhir-import/units.ts @@ -54,3 +54,31 @@ export function labUnitFromFhirQuantity(quantity: { } return unit ?? code; } + +/** + * LOINC codes of lab results that are numbers without a unit: specific + * gravity, pH and the INR. A system often sends them as a bare number with + * no unit at all, and for these analytes that is the value, the UCUM unity + * ("1"), not a unit that was dropped. Kept to codes whose meaning is settled; + * an analyte that is not listed keeps the refusal of a number without a unit. + */ +const DIMENSIONLESS_LOINC: ReadonlySet = new Set([ + // Specific gravity of urine (test strip, unspecified, refractometry). + "5811-5", + "2965-2", + "53326-5", + // pH of urine (test strip, unspecified), of blood and of arterial blood. + "5803-2", + "2756-5", + "11558-4", + "2744-1", + // INR (platelet-poor plasma, blood, capillary blood). + "6301-6", + "34714-6", + "46418-0", +]); + +/** Whether a LOINC code names an analyte whose value has no unit. */ +export function isDimensionlessLoinc(code: string | null): boolean { + return code !== null && DIMENSIONLESS_LOINC.has(code.trim()); +} diff --git a/src/lib/openapi/routes/labs.ts b/src/lib/openapi/routes/labs.ts index 6dd124e3b..8fcf053f3 100644 --- a/src/lib/openapi/routes/labs.ts +++ b/src/lib/openapi/routes/labs.ts @@ -205,7 +205,7 @@ const fhirLabRecordResult = z .meta({ id: "FhirLabRecordResult", description: - "One record's outcome, by its position in the request. `inserted`: written. `duplicate`: the record already holds it, under the same identity (deleted readings included, so a deleted result stays deleted) or as the same reading on the same day from another source. `skipped`: not a reading HealthLog keeps, with `reason` `not_observation` | `not_lab` | `not_final` (preliminary; it is taken once final) | `withdrawn` | `panel_header` | `no_value` | `unsupported_value` | `no_date` | `future_date` | `invalid_date` | `too_large` (a resource over 256 KiB). `failed`: a reading that could not be stored, with `reason` `missing_unit` | `unit_mismatch` (the account's marker is in a unit this one does not convert into) | `text_too_long` | `write_failed` (transient: send it again).", + "One record's outcome, by its position in the request. `inserted`: written. `duplicate`: the record already holds it, under the same identity (deleted readings included, also once the reading or its whole marker is gone, so a deleted result stays deleted) or as the same reading on the same day from another source. `skipped`: not a reading HealthLog keeps, with `reason` `not_observation` | `not_lab` (no category names a lab; a code, display or text containing `lab` in any case counts) | `not_final` (preliminary; it is taken once final) | `withdrawn` | `panel_header` | `no_value` | `unsupported_value` | `no_date` | `future_date` | `invalid_date` | `too_large` (a resource over 256 KiB). `failed`: a reading that could not be stored, with `reason` `missing_unit` (a number without a unit; a specific gravity, a pH or an INR, known by its LOINC code, is read as the unity `1` instead) | `unit_mismatch` (the account's marker is in a unit this one does not convert into) | `text_too_long` | `write_failed` (transient: send it again).", }); const fhirLabBatchResponse = z