> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/lab-reports/biomarker-reference.md).

# Biomarker Reference

> ⚠️ **Pre-Release**
>
> This page is currently under active development and is provided in a pre-release state.
>
> Some content may evolve as we continue to iterate on the implementation based on your feedback, but the core concepts and functionality are expected to remain consistent.
>
> The page will be marked as general release in the near future

## What Is `biomarker.key`?

Every result extracted from a lab report is matched against Terra's reference dataset of **4,100+ known biomarkers**. When a match is found, the result's `biomarker.key` field is set to a canonical slug — a stable, machine-readable identifier you can use to aggregate and compare results across different labs, reports, and patients.

```json
{
  "source": { "name": "Haemoglobin (Hb)" },
  "biomarker": {
    "key": "hemoglobin_blood",
    "display_name": "Hemoglobin"
  }
}
```

### When Is `biomarker.key` null?

`biomarker.key` is always present, and is `null` when the system cannot confidently match the extracted name to a known biomarker. This happens with:

* Lab-specific proprietary test names
* Uncommon or newly introduced assays
* Ambiguous abbreviations
* Composite panels reported as a single line item

When `biomarker.key` is `null`, `source.name` and `biomarker.display_name` still contain the text extracted from the report. Use `source.name` as a fallback for display.

## How Matching Works

1. The `source.name` is extracted from the lab report file via OCR and AI parsing
2. The name is compared against the reference dataset using fuzzy string matching
3. If a high-confidence match is found, the canonical `biomarker.key` slug, `biomarker.display_name`, and related metadata are assigned
4. If no confident match is found, `biomarker.key` is set to `null`

The matching accounts for common variations:

| Report Might Say            | Matched To             |
| --------------------------- | ---------------------- |
| Haemoglobin (Hb)            | `hemoglobin_blood`     |
| HbA1c                       | `hemoglobin_a1c`       |
| 25-OH Vitamin D             | `vitamin_d_25_hydroxy` |
| Thyroid Stimulating Hormone | `tsh`                  |
| TSH                         | `tsh`                  |
| GFR (estimated)             | `egfr`                 |

## UCUM Unit Codes

Terra maps lab units to [UCUM (Unified Code for Units of Measure)](https://ucum.org/) codes wherever possible. UCUM is the international standard for machine-readable unit representation in healthcare.

### Common UCUM Mappings

| Report Units | `ucum_code` | Description                     |
| ------------ | ----------- | ------------------------------- |
| g/dL         | `g/dL`      | Grams per deciliter             |
| mg/dL        | `mg/dL`     | Milligrams per deciliter        |
| mmol/L       | `mmol/L`    | Millimoles per liter            |
| µmol/L       | `umol/L`    | Micromoles per liter            |
| ng/mL        | `ng/mL`     | Nanograms per milliliter        |
| pg/mL        | `pg/mL`     | Picograms per milliliter        |
| mIU/L        | `m[IU]/L`   | Milli-international units/liter |
| IU/L         | `[IU]/L`    | International units per liter   |
| 10^9/L       | `10*9/L`    | Billions per liter              |
| 10^12/L      | `10*12/L`   | Trillions per liter             |
| %            | `%`         | Percent                         |
| fL           | `fL`        | Femtoliters                     |
| mm/hr        | `mm/h`      | Millimeters per hour            |
| seconds      | `s`         | Seconds                         |

{% hint style="info" %}
When a UCUM mapping is not possible (e.g., proprietary or ambiguous units), `measurement.ucum_code` is omitted. The `source.units` field still shows exactly what the report printed.
{% endhint %}

## LOINC Codes

When a matched biomarker has a corresponding [LOINC](https://loinc.org/) code, the result includes a `biomarker.loinc_code` field. LOINC (Logical Observation Identifiers Names and Codes) is the international standard for identifying laboratory observations — useful for interoperability with EHRs and other health systems.

```json
{
  "biomarker": {
    "key": "hemoglobin_blood",
    "display_name": "Hemoglobin",
    "loinc_code": "718-7"
  }
}
```

`biomarker.loinc_code` is **omitted** when the matched biomarker has no LOINC mapping. Coverage is partial — roughly 1,900 of the 4,100+ reference biomarkers currently carry a LOINC code, concentrated on common blood, serum, and urine analytes. Biomarkers without a mapping (many derived ratios, qualitative microbiology results, and specialised assays for which LOINC has no specific term) have no `loinc_code`.

The `loinc_code` for each mapped biomarker is also included in the downloadable reference file linked at the bottom of this page.

## Measurement Types

Every result carries a single `measurement` object. Read `measurement.type`, then read the matching field:

| `measurement.type` | Populated field                               | Example                       |
| ------------------ | --------------------------------------------- | ----------------------------- |
| `numeric`          | `measurement.numeric` (number)                | Hemoglobin: 14.2 g/dL         |
| `bounded`          | `measurement.bounded` (`{ operator, value }`) | PSA: `<0.04`                  |
| `qualitative`      | `measurement.qualitative` (`{ text }`)        | HIV screen: Non-Reactive      |
| `text`             | `measurement.text` (string)                   | Morphology: Normal appearance |
| `absent`           | `measurement.absent_reason` (string)          | Value not reported            |

When the lab reports a bound rather than an exact value, `measurement.type` is `"bounded"` and `measurement.bounded` carries the operator and magnitude:

| Report Shows | `measurement.type` | Populated value                       |
| ------------ | ------------------ | ------------------------------------- |
| `14.2`       | `numeric`          | `measurement.numeric` is `14.2`       |
| `>5.0`       | `bounded`          | `{ "operator": "gt", "value": 5.0 }`  |
| `<0.01`      | `bounded`          | `{ "operator": "lt", "value": 0.01 }` |

## Common Biomarkers

The table below lists frequently encountered biomarkers. For the complete dataset, download the reference file linked at the bottom of this page.

### Complete Blood Count (CBC)

| `biomarker`        | Display Name           | Typical Units | `ucum_code` |
| ------------------ | ---------------------- | ------------- | ----------- |
| `hemoglobin_blood` | Hemoglobin             | g/dL          | `g/dL`      |
| `hematocrit`       | Hematocrit             | %             | `%`         |
| `rbc`              | Red Blood Cell Count   | 10^12/L       | `10*12/L`   |
| `wbc_blood`        | White Blood Cell Count | 10^9/L        | `10*9/L`    |
| `platelet_count`   | Platelet Count         | 10^9/L        | `10*9/L`    |
| `mcv`              | MCV                    | fL            | `fL`        |
| `mch`              | MCH                    | pg            | `pg`        |
| `neutrophils`      | Neutrophils            | 10^9/L        | `10*9/L`    |
| `lymphocytes`      | Lymphocytes            | 10^9/L        | `10*9/L`    |
| `monocytes`        | Monocytes              | 10^9/L        | `10*9/L`    |

### Metabolic Panel

| `biomarker`               | Display Name    | Typical Units | `ucum_code`        |
| ------------------------- | --------------- | ------------- | ------------------ |
| `glucose_fasting`         | Fasting Glucose | mg/dL         | `mg/dL`            |
| `hemoglobin_a1c`          | HbA1c           | %             | `%`                |
| `creatinine_serum`        | Creatinine      | mg/dL         | `mg/dL`            |
| `blood_urea_nitrogen_bun` | BUN             | mg/dL         | `mg/dL`            |
| `egfr`                    | eGFR            | mL/min/1.73m2 | `mL/min/{1.73_m2}` |
| `sodium_serum`            | Sodium          | mmol/L        | `mmol/L`           |
| `potassium_serum`         | Potassium       | mmol/L        | `mmol/L`           |
| `calcium_serum`           | Calcium         | mg/dL         | `mg/dL`            |
| `uric_acid_serum`         | Uric Acid       | mg/dL         | `mg/dL`            |

### Lipid Panel

| `biomarker`       | Display Name      | Typical Units | `ucum_code` |
| ----------------- | ----------------- | ------------- | ----------- |
| `cholesterol`     | Total Cholesterol | mg/dL         | `mg/dL`     |
| `hdl_cholesterol` | HDL Cholesterol   | mg/dL         | `mg/dL`     |
| `ldl_cholesterol` | LDL Cholesterol   | mg/dL         | `mg/dL`     |
| `triglycerides`   | Triglycerides     | mg/dL         | `mg/dL`     |

### Thyroid

| `biomarker`                | Display Name | Typical Units | `ucum_code` |
| -------------------------- | ------------ | ------------- | ----------- |
| `tsh`                      | TSH          | mIU/L         | `m[IU]/L`   |
| `thyroxine_t4_free`        | Free T4      | ng/dL         | `ng/dL`     |
| `triiodothyronine_t3_free` | Free T3      | pg/mL         | `pg/mL`     |

### Hormones

| `biomarker`          | Display Name       | Typical Units | `ucum_code` |
| -------------------- | ------------------ | ------------- | ----------- |
| `testosterone_total` | Total Testosterone | ng/dL         | `ng/dL`     |
| `testosterone_free`  | Free Testosterone  | pg/mL         | `pg/mL`     |
| `estradiol_blood`    | Estradiol          | pg/mL         | `pg/mL`     |
| `cortisol`           | Cortisol           | µg/dL         | `ug/dL`     |
| `insulin_fasting`    | Insulin            | µIU/mL        | `u[IU]/mL`  |

### Vitamins and Minerals

| `biomarker`            | Display Name | Typical Units | `ucum_code` |
| ---------------------- | ------------ | ------------- | ----------- |
| `vitamin_d_25_hydroxy` | Vitamin D    | ng/mL         | `ng/mL`     |
| `vitamin_b12`          | Vitamin B12  | pg/mL         | `pg/mL`     |
| `folate`               | Folate       | ng/mL         | `ng/mL`     |
| `ferritin`             | Ferritin     | ng/mL         | `ng/mL`     |
| `iron_serum`           | Iron         | µg/dL         | `ug/dL`     |

### Liver

| `biomarker`             | Display Name    | Typical Units | `ucum_code` |
| ----------------------- | --------------- | ------------- | ----------- |
| `alt`                   | ALT             | IU/L          | `[IU]/L`    |
| `ast`                   | AST             | IU/L          | `[IU]/L`    |
| `ggt`                   | GGT             | IU/L          | `[IU]/L`    |
| `alp`                   | ALP             | IU/L          | `[IU]/L`    |
| `bilirubin_total_blood` | Total Bilirubin | mg/dL         | `mg/dL`     |
| `albumin_serum`         | Albumin         | g/dL          | `g/dL`      |

### Inflammation

| `biomarker`                           | Display Name | Typical Units | `ucum_code` |
| ------------------------------------- | ------------ | ------------- | ----------- |
| `crp`                                 | CRP          | mg/L          | `mg/L`      |
| `c_reactive_protein_high_sensitivity` | hs-CRP       | mg/L          | `mg/L`      |
| `esr`                                 | ESR          | mm/hr         | `mm/h`      |

## Full Biomarker Reference File

The complete list of all 4,100+ supported biomarkers is available as a downloadable JSON file:

{% file src="/files/g57Q7tPfjsr8pywrLmcI" %}

The file contains each biomarker's canonical key, display name, and associated metadata.