/mapping-loinc

name: mapping-loinc
description: "Maps laboratory and clinical observation names extracted by OpenMed to LOINC codes using the public Regenstrief LOINC and FHIR terminology APIs. Use when the user wants to code lab tests, vital signs, or observations to LOINC, resolve a test name plus specimen and method to the correct LOINC part-model code, attach UCUM units, or build a US Core Laboratory Result Observation. Trigger keywords: LOINC, lab coding, observation code, UCUM units, specimen, method, US Core lab, FHIR Observation, lab result mapping, panel vs analyte. Pairs after OpenMed NER: consume Disease/Chemical/lab-name entities from openmed.analyze_text and map each measurement to a LOINC code. LOINC is free to use under the Regenstrief license (registration/terms-of-use, no fee); UMLS/SNOMED stay user-supplied and out-of-process."
license: Apache-2.0
metadata:
  project: OpenMed
  category: terminology-coding
  pairs: after
  version: "1.0"

Mapping lab/observation names to LOINC

Ground free-text lab and observation names that OpenMed surfaces to **LOINC** (Logical Observation Identifiers Names and Codes), the universal standard for identifying *what was measured*. A LOINC code is a fully specified observation — not just an analyte but the full six-axis model: **Component, Property, Time, System (specimen), Scale, Method**.

LOINC is **free** to use. It is published by the Regenstrief Institute under the LOINC license: you accept terms-of-use (and register to download the table), but there is no fee and no per-use restriction. The standard, public path for license-clean mapping is a **FHIR terminology server** exposing LOINC via `$lookup` / `$validate-code`, or Regenstrief's hosted **fhir.loinc.org**.

When to use

• A note or report contains lab/observation names ("serum potassium",

"hemoglobin A1c", "blood pressure") and you need a stable LOINC code each.

• You must disambiguate by **specimen/system** ("glucose in serum" vs

"glucose in urine") or **method** ("HbA1c by HPLC").

• You need **UCUM** units to pair with the result value, or a US Core

`Observation` (Laboratory Result) coded with LOINC.

• You are mapping a **panel** (e.g. CBC, BMP) vs its individual **analytes**.

For diagnoses/procedures use `coding-icd10`; for drugs use `normalizing-rxnorm`; LOINC is for *observations and measurements*.

Quick start (real LOINC / FHIR terminology calls)

Regenstrief hosts a public FHIR terminology endpoint at `https://fhir.loinc.org` (HTTP Basic auth with your free LOINC account). Many sites instead point at their own server (HAPI, Ontoserver, Snowstorm-with-LOINC). The operations are the same.

import requests
from requests.auth import HTTPBasicAuth

FHIR = "https://fhir.loinc.org"
AUTH = HTTPBasicAuth("YOUR_LOINC_USER", "YOUR_LOINC_PASSWORD")  # free account
LOINC_SYSTEM = "http://loinc.org"

def lookup(code: str) -> dict:
    """$lookup: return the fully specified name + axes for a LOINC code."""
    r = requests.get(
        f"{FHIR}/CodeSystem/$lookup",
        params={"system": LOINC_SYSTEM, "code": code},
        auth=AUTH, headers={"Accept": "application/fhir+json"}, timeout=15,
    )
    r.raise_for_status()
    return r.json()

def validate(code: str, display: str) -> bool:
    r = requests.get(
        f"{FHIR}/CodeSystem/$validate-code",
        params={"url": LOINC_SYSTEM, "code": code, "display": display},
        auth=AUTH, headers={"Accept": "application/fhir+json"}, timeout=15,
    )
    r.raise_for_status()
    params = {p["name"]: p.get("valueBoolean") for p in r.json().get("parameter", [])}
    return bool(params.get("result"))

print(lookup("2823-3"))     # Potassium [Moles/volume] in Serum or Plasma

Search candidate LOINC codes from a text name with the Regenstrief search API (`https://loinc.org/search/`) or a `ValueSet/$expand` filter on your server:

def expand_filter(text: str, count: int = 10) -> list[dict]:
    """Text-filter the LOINC code system to candidate concepts."""
    r = requests.get(
        f"{FHIR}/ValueSet/$expand",
        params={"url": "http://loinc.org/vs", "filter": text, "count": count},
        auth=AUTH, headers={"Accept": "application/fhir+json"}, timeout=20,
    )
    r.raise_for_status()
    return r.json().get("expansion", {}).get("contains", [])

Workflow

1. **Extract** observation/analyte mentions with OpenMed. 2. **Assemble the axes you have** from surrounding text: component (what), specimen/system (serum, urine, blood), method (HPLC, immunoassay), and scale (quantitative vs ordinal). More axes → a more specific, correct LOINC. 3. **Search** candidates via `$expand?filter=` (or Regenstrief search). 4. **Disambiguate** by matching specimen and property. "Glucose" alone is ambiguous; "glucose, serum, mass/volume" resolves to one code. 5. **Validate** the chosen code with `$validate-code`, then `$lookup` to pull the long common name and the canonical **UCUM** example unit. 6. **Emit** `{system: "http://loinc.org", code, display}` plus the UCUM unit for the result value, into a US Core Observation.

Hand-off from OpenMed

`openmed.analyze_text(..., output_format="dict")` returns `entities`, each a dict with `text`, `label`, `confidence`, `start`, `end`. Lab analytes often surface under Chemical/Disease models; run the relevant model and feed the spans in:

import openmed

note = "Labs: serum potassium 5.1 mmol/L, hemoglobin A1c 7.8 %."
result = openmed.analyze_text(
    note,
    model_name="chemical_detection_pubmed",   # Chemical category (analytes)
    output_format="dict",
)

for ent in result["entities"]:
    name = ent["text"]                         # e.g. "potassium"
    candidates = expand_filter(name, count=5)  # LOINC candidates
    # carry OpenMed offsets so the code is traceable to the source span
    print(name, ent["start"], ent["end"], "->",
          [(c["code"], c["display"]) for c in candidates[:3]])

Pair the matched LOINC with the *