Measurement Units

Laboratory biomarkers can be reported in different measurement units depending on the type of measurement used by the laboratory.

For example, glucose units can be presented in:

• Mass concentration - weight of a substance per volume
  Examples: mg/dL, g/L, µg/mL

• Molar concentration - measures the amount of substance (moles) per unit of volume
  Examples: mmol/L, µmol/L

One of Ornament’s core capabilities is handling families of compatible measurement units for the same biomarker.

In practice, laboratories may report the same biomarker in different units. Ornament solves this by treating those units as part of one unit family (internally also referred to as a bush). This allows the platform to recognize, normalize, store, and display values consistently across different lab sources.

System Unit vs. Display Unit

Each biomarker has a single system unit that acts as the internal anchor for storage and calculations.

• System Unit (anchor): the biomarker’s primary internal unit, defined by default_unit_id
• Original Unit: the unit in which the value was received from the lab report
• Display Unit: any compatible unit from the same family that can be used for presentation or export

In Ornament responses:

• value is the biomarker value stored in the default/system unit
• originalValue is the value as received from the source
• originalUnitId identifies the source unit used in the original lab record

What is a Unit Family?

A biomarker does not effectively have only one usable unit.

Instead, it has:

• one default unit (default_unit_id) used as the anchor
• a family of compatible units that can be converted to and from that anchor

This family is represented through the biomarker’s available unit mappings, exposed in the API as unitsFactors. Ornament uses these mappings to support different lab formats while preserving a normalized internal representation.

How normalization works

When Ornament receives a biomarker value in a non-default unit, the system automatically converts it into the biomarker’s system unit.

Conceptually, this works as follows:

• The incoming value is identified together with its original unit
• Ornament finds the matching unit within the biomarker’s unit family
• The value is normalized into the system unit
• The normalized value is stored internally and can later be converted into any other compatible unit from the same family

This makes it possible to:

• ingest laboratory data reported in different units
• store values in one consistent internal format
• display or export values in other supported units when needed

Conversion model

For each biomarker, Ornament provides a list of supported units and their conversion factors through unitsFactors. The normalized value stored in value can then be converted into another target unit using the corresponding factor.

Current conversion approach:

Text

Converted Value = Default Value / UnitFactor

Database concept

Internally, the family / bush concept is centered around the measurement unit model and biomarker configuration.

From a data-model perspective:

• the biomarker has a default_unit_id that defines its system unit
• the biomarker is associated with a compatible set of units
• those units are mathematically convertible relative to the default unit

So while the API exposes this through unitsFactors, the core idea is:

a biomarker belongs to a family of interchangeable units, with one default unit serving as the anchor for storage and conversion

Why this matters

This approach allows Ornament to:

• accept data from labs that use different unit systems
• standardize biomarker values for scoring and calculations
• keep original lab semantics visible to the client
• convert values and reference ranges consistently across supported units

API conversion workflow

To convert a biomarker value into another supported unit, Ornament uses the normalized default value stored in the profile entry together with the conversion factors returned for that biomarker.

The workflow is:

1. Get the biomarker entry from the Profile Biomarkers endpoint

   • value is the biomarker value in the default unit
   • originalValue is the value as received from the lab report
   • originalUnitId is the unit ID from the original lab record

2. Get the supported units for that biomarker from the Biomarkers endpoint

   • unitsFactors contains pairs in the format [unitId, unitFactor]

3. Resolve the target unit through the Measurement Units endpoint

   • this lets you get the human-readable unit title for a unit ID

4. Apply the conversion formula

   • Converted Value = Default Value / UnitFactor

Here is an example of measurement unit conversion using the Ornament API.