Slot: Native Units (UCUM) (native_units_ucum)

UCUM unit of the values as the source product stores them, when that differs from units_ucum (the unit of the values in the companion data file). Omit when the source already stores values in units_ucum — absence means "no conversion happened". Declaring it makes unit_conversion_formula required.

Tier: recommended

Why this slot matters

A value of 308 and a value of 35 can be the same temperature. When the source stores different units (or packed integers) than the companion file carries, the native unit is the anchor that lets a consumer check the conversion and re-read the source bytes; without it the sidecar's values cannot be traced back to the product.

In plain terms

Data producers often store numbers in different units than the ones shown to users — Kelvin instead of Celsius, or compressed integers that need unpacking. This field records the unit the source actually uses, so anyone going back to the original files knows what the raw numbers mean.

URI: envar:slot/native_units_ucum

Applicable Classes

Name	Description	Modifies Slot
VariableIdentity	The identity and semantics of an environmental exposure variable — what physi...	no

Properties

Type and Range

Property	Value
Range	String
Domain Of	VariableIdentity

Cardinality and Requirements

Property	Value

Examples

Value
K

Comments

Added after the reverse gap survey (docs/reverse-gap-survey.md, 2026-07): all three worked pipelines surfaced the same gap independently — Amadeus ships value_kelvin/value_celsius twin columns, GAIA stores °C with no record of the K→°C math, and DeGAUSS converts inside the container so the native unit never appears in any output. The Amadeus translation had to park the native unit in a YAML comment because the schema had no slot for it; the GAIA scenario prototyped exactly this key as a hand-added envar:* PropertyValue in its JSON-LD catalog entry before it existed here.

Identifier and Mapping Information

Annotations

property	value
tier	recommended
justification	A value of 308 and a value of 35 can be the same temperature. When the source stores different units (or packed integers) than the companion file carries, the native unit is the anchor that lets a consumer check the conversion and re-read the source bytes; without it the sidecar's values cannot be traced back to the product.
explanation	Data producers often store numbers in different units than the ones shown to users — Kelvin instead of Celsius, or compressed integers that need unpacking. This field records the unit the source actually uses, so anyone going back to the original files knows what the raw numbers mean.
covered_by	None

Schema Source

from schema: https://w3id.org/linkml/microschemas/envar

Mappings

Mapping Type	Mapped Value
self	envar:native_units_ucum
native	envar:native_units_ucum

LinkML Source

name: native_units_ucum
annotations:
  tier:
    tag: tier
    value: recommended
  justification:
    tag: justification
    value: A value of 308 and a value of 35 can be the same temperature. When the
      source stores different units (or packed integers) than the companion file carries,
      the native unit is the anchor that lets a consumer check the conversion and
      re-read the source bytes; without it the sidecar's values cannot be traced back
      to the product.
  explanation:
    tag: explanation
    value: Data producers often store numbers in different units than the ones shown
      to users — Kelvin instead of Celsius, or compressed integers that need unpacking.
      This field records the unit the source actually uses, so anyone going back to
      the original files knows what the raw numbers mean.
  covered_by:
    tag: covered_by
    annotations:
      omop_gaia:
        tag: omop_gaia
        annotations:
          extent:
            tag: extent
            value: absent
          status:
            tag: status
            value: asserted
          where:
            tag: where
            value: no column
          note:
            tag: note
            value: GAIA stores °C as if it were always °C; only the OMOP-side unit
              lands in value_as_number and the upstream native unit is not on the
              row.
      amadeus:
        tag: amadeus
        annotations:
          extent:
            tag: extent
            value: full
          status:
            tag: status
            value: verified
          where:
            tag: where
            value: thredds_dataset.xml units = "K" (native) alongside the derived
              value_celsius; gridmet_tmmx.csv value_kelvin column
          evidence:
            tag: evidence
            value: EnVar/examples/heat/COMPARISON.md §D/§E (Value in native source
              units — ✅ for Amadeus)
          note:
            tag: note
            value: Amadeus ships the native Kelvin value and its unit declaration
              side by side with the converted Celsius.
      degauss:
        tag: degauss
        annotations:
          extent:
            tag: extent
            value: absent
          status:
            tag: status
            value: asserted
          where:
            tag: where
            value: no column
          note:
            tag: note
            value: DeGAUSS does the K→°C conversion inside the container, so the native
              unit never appears in any output.
      cher:
        tag: cher
        annotations:
          extent:
            tag: extent
            value: absent
          status:
            tag: status
            value: asserted
          where:
            tag: where
            value: no column
          note:
            tag: note
            value: C-HER records one column_unit per column; it has no notion of a
              distinct source-native unit and conversion.
      codata:
        tag: codata
        annotations:
          extent:
            tag: extent
            value: out_of_layer
          status:
            tag: status
            value: asserted
          where:
            tag: where
            value: no column
          note:
            tag: note
            value: A source-native unit and its packing are instance-layer decode
              details; CODATA's conceptual/represented layers do not carry per-run
              storage conventions.
description: UCUM unit of the values as the *source product stores them*, when that
  differs from `units_ucum` (the unit of the values in the companion data file). Omit
  when the source already stores values in `units_ucum` — absence means "no conversion
  happened". Declaring it makes `unit_conversion_formula` required.
title: Native Units (UCUM)
comments:
- 'Added after the reverse gap survey (docs/reverse-gap-survey.md, 2026-07): all three
  worked pipelines surfaced the same gap independently — Amadeus ships `value_kelvin`/`value_celsius`
  twin columns, GAIA stores °C with no record of the K→°C math, and DeGAUSS converts
  inside the container so the native unit never appears in any output. The Amadeus
  translation had to park the native unit in a YAML comment because the schema had
  no slot for it; the GAIA scenario prototyped exactly this key as a hand-added `envar:*`
  PropertyValue in its JSON-LD catalog entry before it existed here.'
examples:
- value: K
  description: gridMET tmmx stores Kelvin; the Amadeus scenario emits Celsius
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://ucum.org/
rank: 1000
domain_of:
- VariableIdentity
range: string