EnVar microschema · class
Derived Heat Metric
DerivedHeatMetric
Methodology slots specific to derived heat metrics (WBGT, Heat Index, UTCI, apparent temperature, heat-wave flag, etc.). Captures the decisions that the heat-epidemiology literature flags as critical sources of cross-study disagreement: which equation variant, which indoor / outdoor regime, which solar-radiation input, and -- for percentile-based metrics -- the reference period, scope, and seasonal window. One per record where applicable.
Where it sits
Composed intoEnvironmentalExposureRecord
ReferencesEquationInput
Fields
There are many different "heat numbers" — plain air temperature, composite scores that also fold in humidity, wind and sunshine, or a simple yes/no heat-wave flag. This field says which kind of heat number the record is about.
The family of heat metric this variable represents.
Example
wbgt_outdoor — outdoor Wet Bulb Globe Temperature (Phoenix 2022 heat-wave record)
Allowed values
tmax Daily maximum air temperature
tmin Daily minimum air temperature
tmean Daily mean air temperature
heat_index Heat Index (NWS Rothfusz / Steadman)
wbgt_outdoor Wet Bulb Globe Temperature, outdoor variant
wbgt_indoor Wet Bulb Globe Temperature, indoor variant
utci Universal Thermal Climate Index
apparent_temperature Apparent temperature (Steadman family)
humidex Humidex (Masterton-Richardson)
heat_wave_flag Binary heat-wave flag
consecutive_extreme_heat_days Count of consecutive extreme-heat days
cooling_degree_days Cooling degree-days
Covered by — 5 standards
Why it matters & mappings
Tmax, Heat Index, WBGT, and a heat-wave flag are distinct exposures with distinct health associations; without the family, values from different metrics are indistinguishable and get pooled as if they measured the same thing.
Well-known heat metrics have several published formulas that share one name but differ mathematically — like recipes with the same title from different cookbooks. This records which exact recipe was used to cook the number.
For derived heat metrics, the equation variant used. Mandatory for WBGT, HI, and UTCI: a Liljegren WBGT and an ACSM WBGT for the same inputs can differ by 2-3 °C.
Example
liljegren_2008 — Liljegren et al. 2008 outdoor WBGT formulation
Allowed values
liljegren_2008 WBGT — Liljegren et al
acsm_simplified WBGT — American College of Sports Medicine simplified
bernard_simplified WBGT — Bernard simplified
rothfusz_1990_nws Heat Index — Rothfusz / NWS 1990 polynomial
steadman_1979 Heat Index / apparent temperature — Steadman 1979
brode_2012_polynomial UTCI — Bröde et al
Why it matters & mappings
WBGT approximations diverge materially from the reference model — well beyond 2-3 °C in hot-humid conditions — so two studies using "WBGT" with different variants are measuring systematically different quantities; pooling them without this field mixes those quantities silently.
Composite heat metrics are cooked from several ingredients — temperature, humidity, wind, sunshine. This is the ingredient list, where each entry points to that ingredient's own full paperwork instead of hiding it inside the final number.
Typed per-input references for a multi-input derived metric (Heat Index from T + RH; WBGT from T + RH + wind + radiation). Each entry names the input's role and points, by provenance_id, to the upstream sidecar carrying that input's full context — it is an index into the lineage, not an inline copy of it. Option-B decomposition (see the EquationInput class): when the inputs originate from different products and diverge in resolution, day-boundary convention, or temporal aggregation, each input is a full upstream sidecar referenced here and listed as a step in provenance_chain, so the divergence stays explicit and checkable. Conditionally-Core: optional for a single-input metric, mandatory the moment a metric has more than one input.
Examples
None — one entry of the list — the air-temperature input of a Liljegren WBGT; a wind-speed entry from a divergent product (e.g. ~31 km ERA5) would sit alongside it as a second element
None — a second list entry from a divergent product (~31 km ERA5 vs 1 km Daymet), pointing at its own full upstream sidecar
Why it matters & mappings
Multi-input metrics can silently absorb mismatched inputs — e.g. a Heat Index built from a 1 km local-midnight daily-max temperature and a ~31 km UTC daily-mean humidity. Without per-input references that divergence is invisible and no checker can surface it.
Every formula only works within a fence of weather conditions it was designed for. This field writes the fence down, so anyone can check whether a value was computed inside or outside it.
Validity-range conditions for the equation, serialised as a JSON string. For Heat Index: {"min_temperature_F": 80, "min_relative_humidity_pct": 40} — Rothfusz is undefined below 80 °F / 40 % RH.
Example
{"min_wind_speed_m_s": 0.13} — Liljegren 2008 clamps wind speed below 0.13 m/s
Why it matters & mappings
The Rothfusz Heat Index is undefined below ~80 °F / 40 % RH; applied outside its range an equation produces plausible-looking nonsense. Without the recorded range, no downstream consumer can flag values computed where the formula does not hold.
Heat stress works differently inside and outside — indoors there is no direct sun and little wind — so heat metrics come in indoor and outdoor versions, and you need to know which one you are looking at.
Indoor / outdoor regime. Mandatory for WBGT (the indoor vs outdoor distinction changes the equation and the health interpretation).
Example
outdoor
Allowed values
outdoor Outdoor (default for all reanalysis / satellite / interpolation products)
indoor_modeled Indoor regime, modelled
indoor_measured Indoor regime, measured by an indoor instrument
mixed_unspecified Mixed indoor / outdoor, regime unspecified
Why it matters & mappings
Indoor and outdoor WBGT use different equations and carry different health interpretations; an indoor formula applied to outdoor conditions (or a regime left unstated) makes the value invalid or uninterpretable for the exposure being claimed.
There is no universal definition of a heat wave. "Above 35 °C" and "hotter than 95 % of days usually are here" are both in use and flag different days — this field records which rulebook was applied.
For heat-wave flags, the definition of the threshold (absolute, percentile-local, percentile-climatological, NWS advisory, ETCCDI).
Example
percentile_local — 95th percentile of the local Tmax distribution
Allowed values
absolute Absolute threshold value (e
percentile_local Local-distribution percentile (e
percentile_climatological Climatological-baseline percentile
nws_heat_advisory_criteria National Weather Service Heat Advisory criteria
etccdi_warm_spell_duration_index ETCCDI Warm Spell Duration Index
Why it matters & mappings
At least seven heat-wave definitions are in active use and none are convertible after the fact; two definitions can disagree on most flagged days, which changes both the exposure series and the resulting mortality estimate.
See also: https://en.wikipedia.org/wiki/Heat_wave
A heat wave means it stays hot for several days in a row — but how many days count as "several" is a choice (usually 2 or 3), and the choice changes which days get flagged.
Minimum-consecutive-days rule for heat-wave flags (commonly 2 or 3). Changes which days are flagged.
Example
3
Why it matters & mappings
A 2-day rule and a 3-day rule flag different sets of days from the same temperature series, changing which person-days count as heat-wave-exposed and therefore the effect estimates built on them.
"Unusually hot" means hot compared to some stretch of past years. Which years you compare against changes what counts as unusual — this field records where that stretch begins.
Start of the reference distribution used for percentile-based thresholds. Mandatory for percentile metrics: "95th percentile" over 2000-2019 gives a different threshold than 1980-2010, and this delta is real.
Example
1991-01-01 — start of the 1991-2020 climate-normal baseline
Why it matters & mappings
In a warming climate a "95th percentile" computed over 1971-2000 is a materially different threshold than one over 2000-2019; leaving the baseline unstated makes percentile-based studies non-comparable and non-reproducible.
The other end of the stretch of past years used as the comparison — start and end together say exactly which years define "normal".
End of the reference distribution.
Example
2020-12-31
Why it matters & mappings
Together with the start date this pins down the reference distribution; an end date that includes or excludes the most recent warm years shifts the percentile threshold, so an open-ended baseline is not reproducible.
Wind blows faster the higher above the ground you measure it, so a "wind speed" is only meaningful together with the height it was taken at — this field records that height.
For WBGT and UTCI inputs, the wind-speed measurement height in metres. The ISO 7243 standard is 2 m, but reanalysis products often supply 10 m -- the height affects the WBGT value.
Example
10 — ERA5 10 m wind used without height adjustment
Covered by — 5 standards
Why it matters & mappings
ISO 7243 assumes wind measured at 2 m, but reanalysis products usually supply 10 m wind; wind is slower near the ground, so an uncorrected 10 m input systematically shifts the resulting WBGT.
See also: https://www.iso.org/standard/67188.html
How much sunshine hits a person is part of how hot they feel, and datasets represent "sunshine" in different ways — or not at all. This says which representation fed the calculation.
For WBGT / UTCI inputs, the basis used for solar radiation.
Example
surface_downwelling_shortwave_flux
Allowed values
surface_downwelling_shortwave_flux Surface downwelling shortwave flux density
mean_radiant_temperature_modeled Modelled mean radiant temperature
not_available Solar radiation input not available; metric falls back
Covered by — 5 standards
Why it matters & mappings
WBGT and UTCI respond strongly to solar load; whether the sun input was a measured shortwave flux, a modelled mean radiant temperature, or absent (triggering a fallback formula) changes the value and whether two records are comparable at all.
"Unusually hot" can mean hot compared to what is normal HERE, or compared to the whole country. This field says which area's history the comparison was made against.
Geographic scope over which the reference distribution was computed. One of local_tract, local_county, local_climate_region, national.
Example
local_county — reference distribution computed over Maricopa County
Covered by — 5 standards
Why it matters & mappings
A 95th percentile computed over one county and one computed over the whole nation are very different thresholds; the scope is what encodes "hot for here", and without it the threshold cannot be reproduced or compared across studies.
Whether "normal" includes the whole year or only the summer months changes what counts as unusually hot — a day that is extreme against summer-only history may be unremarkable against the full year.
Seasonal window over which the reference was computed. One of annual, warm_season_may_sep, calendar_month.
Example
warm_season_may_sep
Covered by — 5 standards
Why it matters & mappings
An annual reference distribution includes winter days and drags the 95th percentile far below a warm-season-only percentile; two thresholds that sound identical diverge substantially when the seasonal window is left unstated.
A heat wave spans several days but health records are kept day by day; this says which calendar days actually get the "heat wave" label — just the first day, every day, or the last.
For heat-wave flags, how multi-day exposures are stamped on individual days (e.g. first_day_of_event / each_day_of_event / last_day_of_event).
Example
each_day_of_event
Covered by — 5 standards
Why it matters & mappings
Stamping a five-day event only on its first day versus on every day changes which person-days count as exposed, directly altering effect estimates in daily time-series and case-crossover designs.
A blank field is ambiguous: it could mean the thing does not exist, or that nobody wrote it down. This companion field says which one it is.
Reason equation_variant is null.
Example
not_provided_by_source
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "no equation variant exists for this metric" from "the variant was used but never captured" — the first is fine, the second means the record is unusable for cross-study comparison and someone should go back to the producer.
A blank field is ambiguous: it could mean the thing does not exist, or that nobody wrote it down. This companion field says which one it is.
Reason equation_validity_range is null.
Example
not_provided_by_source
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "this equation has no published validity range" from "the range exists but was not captured" — the difference decides whether out-of-range screening is impossible or merely deferred.
A blank field is ambiguous: it could mean the thing does not exist, or that nobody wrote it down. This companion field says which one it is.
Reason wind_speed_measurement_height_m is null.
Example
available_but_not_extracted
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "the producer never recorded a measurement height" from "it exists upstream but was not extracted" — only the latter is recoverable, and only the former precludes a height correction.
A blank field is ambiguous: it could mean the thing does not exist, or that nobody wrote it down. This companion field says which one it is.
Reason solar_radiation_basis is null.
Example
not_provided_by_source
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "the source never stated its radiation basis" from "it was not extracted" — deciding whether the ambiguity can be resolved by going back to the source or is permanent.
A blank field is ambiguous: it could mean the thing does not exist, or that nobody wrote it down. This companion field says which one it is.
Reason heat_wave_threshold_definition is null.
Example
not_applicable
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "this record is not a heat-wave flag, so no threshold definition exists" from "a definition was used but not captured" — the first is benign, the second makes the flag unusable.
The threshold definition is the type of cutoff; this is the actual number plugged into it — like knowing a speed limit exists versus knowing it is 50.
Free-form specifier paired with heat_wave_threshold_definition to capture the concrete threshold values (e.g. "35_Cel" for an absolute threshold, "95" for the 95th percentile).
Examples
95 — percentile, paired with heat_wave_threshold_definition = percentile_local
35_Cel — absolute threshold, paired with heat_wave_threshold_definition = absolute
Why it matters & mappings
The definition names the rule but not the number: two records both marked "percentile_local" are still incomparable unless the concrete value (95th vs 90th percentile, 35 vs 40 °C) is recorded here.
A blank field is ambiguous: it could mean the thing does not exist, or that nobody wrote it down. This companion field says which one it is.
Reason heat_wave_min_consecutive_days is null.
Example
not_applicable
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "not a heat-wave flag, so no consecutive-days rule applies" from "a rule was applied but not recorded" — only the latter undermines reuse of the flag.
A blank field is ambiguous: it could mean the thing does not exist, or that nobody wrote it down. This companion field says which one it is.
Reason percentile_reference_period_start is null.
Example
not_applicable
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "not a percentile-based metric, so no baseline exists" from "a baseline was used but not captured" — without the reason, a consumer cannot tell a benign blank from a blocking one.
A blank field is ambiguous: it could mean the thing does not exist, or that nobody wrote it down. This companion field says which one it is.
Reason percentile_reference_period_end is null.
Example
not_applicable
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "no percentile baseline applies to this metric" from "the baseline end was used but never recorded" — deciding whether the threshold is merely undocumented or genuinely absent.
A blank field is ambiguous: it could mean the thing does not exist, or that nobody wrote it down. This companion field says which one it is.
Reason percentile_reference_geographic_scope is null.
Example
not_provided_by_source
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "the source never stated its baseline geography" from "it was not extracted" — telling consumers whether the ambiguity is recoverable from the source or permanent.
A blank field is ambiguous: it could mean the thing does not exist, or that nobody wrote it down. This companion field says which one it is.
Reason percentile_reference_seasonal_window is null.
Example
not_provided_by_source
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "the source never stated its seasonal window" from "it was not extracted" — so consumers know whether asking the producer could still recover it.
A blank field is ambiguous: it could mean the thing does not exist, or that nobody wrote it down. This companion field says which one it is.
Reason metric_temporal_aggregation_rule is null.
Example
available_but_not_extracted
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "no multi-day stamping rule applies to this metric" from "a rule was applied but never captured" — only the latter makes the daily exposure series ambiguous.
Full field reference — every slot, cardinality & inheritance
| Field | Name | Tier | Cardinality / Range | Description |
|---|---|---|---|---|
| Heat Metric Family | heat_metric_family |
core | 1 HeatMetricFamilyEnum |
The family of heat metric this variable represents |
| Equation Variant | equation_variant |
conditionally core | 1 EquationVariantEnum |
For derived heat metrics, the equation variant used |
| Reason Equation Variant Is Missing | equation_variant_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason equation_variant is null |
| Equation Inputs | equation_inputs |
conditionally core | 1..* EquationInput |
Typed per-input references for a multi-input derived metric (Heat Index from ... |
| Equation Validity Range | equation_validity_range |
conditionally core | 1 String |
Validity-range conditions for the equation, serialised as a JSON string |
| Reason Validity Range Is Missing | equation_validity_range_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason equation_validity_range is null |
| Indoor or Outdoor Regime | indoor_outdoor |
conditionally core | 1 IndoorOutdoorEnum |
Indoor / outdoor regime |
| Wind Speed Measurement Height (Metres) | wind_speed_measurement_height_m |
recommended | 0..1 Float |
For WBGT and UTCI inputs, the wind-speed measurement height in metres |
| Reason Measurement Height Is Missing | wind_speed_measurement_height_m_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason wind_speed_measurement_height_m is null |
| Solar Radiation Basis | solar_radiation_basis |
recommended | 0..1 SolarRadiationBasisEnum |
For WBGT / UTCI inputs, the basis used for solar radiation |
| Reason Radiation Basis Is Missing | solar_radiation_basis_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason solar_radiation_basis is null |
| Heat-Wave Threshold Definition | heat_wave_threshold_definition |
conditionally core | 0..1 HeatWaveThresholdDefinitionEnum |
For heat-wave flags, the definition of the threshold (absolute, percentile-lo... |
| Reason Threshold Definition Is Missing | heat_wave_threshold_definition_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason heat_wave_threshold_definition is null |
| Heat-Wave Threshold Specifier | heat_wave_threshold_specifier |
optional | 0..1 String |
Free-form specifier paired with heat_wave_threshold_definition to capture t... |
| Heat-Wave Minimum Consecutive Days | heat_wave_min_consecutive_days |
conditionally core | 0..1 Integer |
Minimum-consecutive-days rule for heat-wave flags (commonly 2 or 3) |
| Reason Consecutive Days Is Missing | heat_wave_min_consecutive_days_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason heat_wave_min_consecutive_days is null |
| Percentile Reference Period Start | percentile_reference_period_start |
conditionally core | 0..1 Date |
Start of the reference distribution used for percentile-based thresholds |
| Reason Period Start Is Missing | percentile_reference_period_start_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason percentile_reference_period_start is null |
| Percentile Reference Period End | percentile_reference_period_end |
conditionally core | 0..1 Date |
End of the reference distribution |
| Reason Period End Is Missing | percentile_reference_period_end_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason percentile_reference_period_end is null |
| Percentile Reference Geographic Scope | percentile_reference_geographic_scope |
recommended | 0..1 String |
Geographic scope over which the reference distribution was computed |
| Reason Geographic Scope Is Missing | percentile_reference_geographic_scope_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason percentile_reference_geographic_scope is null |
| Percentile Reference Seasonal Window | percentile_reference_seasonal_window |
recommended | 0..1 String |
Seasonal window over which the reference was computed |
| Reason Seasonal Window Is Missing | percentile_reference_seasonal_window_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason percentile_reference_seasonal_window is null |
| Metric Temporal Aggregation Rule | metric_temporal_aggregation_rule |
recommended | 0..1 String |
For heat-wave flags, how multi-day exposures are stamped on individual days (... |
| Reason Aggregation Rule Is Missing | metric_temporal_aggregation_rule_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason metric_temporal_aggregation_rule is null |
Conditional rules on this class
| Rule Applied | Preconditions | Postconditions |
|---|---|---|
| slot_conditions | {'heat_metric_family': {'equals_string': 'heat_wave_flag'}} |
{'heat_wave_threshold_definition': {'required': True}, 'heat_wave_min_consecutive_days': {'required': True}} |
| Rule Applied | Preconditions | Postconditions |
|---|---|---|
| slot_conditions | {'heat_wave_threshold_definition': {'equals_string_in': ['percentile_local', 'percentile_climatological']}} |
{'percentile_reference_period_start': {'required': True}, 'percentile_reference_period_end': {'required': True}} |
Diagram & LinkML source
classDiagram
class DerivedHeatMetric
click DerivedHeatMetric href "../../classes/DerivedHeatMetric/"
DerivedHeatMetric : equation_inputs
DerivedHeatMetric --> "1..*" EquationInput : equation_inputs
click EquationInput href "../../classes/EquationInput/"
DerivedHeatMetric : equation_validity_range
DerivedHeatMetric : equation_validity_range_missing_reason
DerivedHeatMetric --> "0..1" MissingReasonEnum : equation_validity_range_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
DerivedHeatMetric : equation_variant
DerivedHeatMetric --> "1" EquationVariantEnum : equation_variant
click EquationVariantEnum href "../../enums/EquationVariantEnum/"
DerivedHeatMetric : equation_variant_missing_reason
DerivedHeatMetric --> "0..1" MissingReasonEnum : equation_variant_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
DerivedHeatMetric : heat_metric_family
DerivedHeatMetric --> "1" HeatMetricFamilyEnum : heat_metric_family
click HeatMetricFamilyEnum href "../../enums/HeatMetricFamilyEnum/"
DerivedHeatMetric : heat_wave_min_consecutive_days
DerivedHeatMetric : heat_wave_min_consecutive_days_missing_reason
DerivedHeatMetric --> "0..1" MissingReasonEnum : heat_wave_min_consecutive_days_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
DerivedHeatMetric : heat_wave_threshold_definition
DerivedHeatMetric --> "0..1" HeatWaveThresholdDefinitionEnum : heat_wave_threshold_definition
click HeatWaveThresholdDefinitionEnum href "../../enums/HeatWaveThresholdDefinitionEnum/"
DerivedHeatMetric : heat_wave_threshold_definition_missing_reason
DerivedHeatMetric --> "0..1" MissingReasonEnum : heat_wave_threshold_definition_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
DerivedHeatMetric : heat_wave_threshold_specifier
DerivedHeatMetric : indoor_outdoor
DerivedHeatMetric --> "1" IndoorOutdoorEnum : indoor_outdoor
click IndoorOutdoorEnum href "../../enums/IndoorOutdoorEnum/"
DerivedHeatMetric : metric_temporal_aggregation_rule
DerivedHeatMetric : metric_temporal_aggregation_rule_missing_reason
DerivedHeatMetric --> "0..1" MissingReasonEnum : metric_temporal_aggregation_rule_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
DerivedHeatMetric : percentile_reference_geographic_scope
DerivedHeatMetric : percentile_reference_geographic_scope_missing_reason
DerivedHeatMetric --> "0..1" MissingReasonEnum : percentile_reference_geographic_scope_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
DerivedHeatMetric : percentile_reference_period_end
DerivedHeatMetric : percentile_reference_period_end_missing_reason
DerivedHeatMetric --> "0..1" MissingReasonEnum : percentile_reference_period_end_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
DerivedHeatMetric : percentile_reference_period_start
DerivedHeatMetric : percentile_reference_period_start_missing_reason
DerivedHeatMetric --> "0..1" MissingReasonEnum : percentile_reference_period_start_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
DerivedHeatMetric : percentile_reference_seasonal_window
DerivedHeatMetric : percentile_reference_seasonal_window_missing_reason
DerivedHeatMetric --> "0..1" MissingReasonEnum : percentile_reference_seasonal_window_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
DerivedHeatMetric : solar_radiation_basis
DerivedHeatMetric --> "0..1" SolarRadiationBasisEnum : solar_radiation_basis
click SolarRadiationBasisEnum href "../../enums/SolarRadiationBasisEnum/"
DerivedHeatMetric : solar_radiation_basis_missing_reason
DerivedHeatMetric --> "0..1" MissingReasonEnum : solar_radiation_basis_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
DerivedHeatMetric : wind_speed_measurement_height_m
DerivedHeatMetric : wind_speed_measurement_height_m_missing_reason
DerivedHeatMetric --> "0..1" MissingReasonEnum : wind_speed_measurement_height_m_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
name: DerivedHeatMetric
annotations:
domain_of_use:
tag: domain_of_use
value: environmental_exposure
description: 'Methodology slots specific to derived heat metrics (WBGT, Heat Index,
UTCI, apparent temperature, heat-wave flag, etc.). Captures the decisions that the
heat-epidemiology literature flags as critical sources of cross-study disagreement:
which equation variant, which indoor / outdoor regime, which solar-radiation input,
and -- for percentile-based metrics -- the reference period, scope, and seasonal
window. One per record where applicable.'
title: Derived Heat Metric
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://en.wikipedia.org/wiki/Wet-bulb_globe_temperature
- https://www.weather.gov/safety/heat-index
- http://www.utci.org/
rank: 1000
slot_usage:
heat_metric_family:
name: heat_metric_family
required: true
indoor_outdoor:
name: indoor_outdoor
required: true
equation_variant:
name: equation_variant
required: true
equation_inputs:
name: equation_inputs
required: true
equation_validity_range:
name: equation_validity_range
required: true
attributes:
heat_metric_family:
name: heat_metric_family
annotations:
tier:
tag: tier
value: core
justification:
tag: justification
value: Tmax, Heat Index, WBGT, and a heat-wave flag are distinct exposures
with distinct health associations; without the family, values from different
metrics are indistinguishable and get pooled as if they measured the same
thing.
explanation:
tag: explanation
value: There are many different "heat numbers" — plain air temperature, composite
scores that also fold in humidity, wind and sunshine, or a simple yes/no
heat-wave flag. This field says which kind of heat number the record is
about.
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: The scenario is a plain Tmax extraction, not a heat index;
the variable family is implicit in variable_name tmax, with no derived
heat-metric family slot.
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 emits plain tmax with no heat-metric family field.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: Amadeus emits plain tmmx with no heat-metric family field.
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 models no derived heat-metric family.
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: Heat-metric methodology is instance-layer; out of scope for
CODATA.
description: The family of heat metric this variable represents.
title: Heat Metric Family
examples:
- value: wbgt_outdoor
description: outdoor Wet Bulb Globe Temperature (Phoenix 2022 heat-wave record)
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: HeatMetricFamilyEnum
required: true
equation_variant:
name: equation_variant
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: WBGT approximations diverge materially from the reference model — well
beyond 2-3 °C in hot-humid conditions — so two studies using "WBGT" with
different variants are measuring systematically different quantities; pooling
them without this field mixes those quantities silently.
explanation:
tag: explanation
value: Well-known heat metrics have several published formulas that share
one name but differ mathematically — like recipes with the same title from
different cookbooks. This records which exact recipe was used to cook the
number.
description: 'For derived heat metrics, the equation variant used. Mandatory for
WBGT, HI, and UTCI: a Liljegren WBGT and an ACSM WBGT for the same inputs can
differ by 2-3 °C.'
title: Equation Variant
examples:
- value: liljegren_2008
description: Liljegren et al. 2008 outdoor WBGT formulation
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://en.wikipedia.org/wiki/Wet-bulb_globe_temperature
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: EquationVariantEnum
required: true
equation_variant_missing_reason:
name: equation_variant_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "no equation variant exists for this metric" from "the
variant was used but never captured" — the first is fine, the second means
the record is unusable for cross-study comparison and someone should go
back to the producer.
explanation:
tag: explanation
value: 'A blank field is ambiguous: it could mean the thing does not exist,
or that nobody wrote it down. This companion field says which one it is.'
description: Reason `equation_variant` is null.
title: Reason Equation Variant Is Missing
examples:
- value: not_provided_by_source
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: MissingReasonEnum
equation_inputs:
name: equation_inputs
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: Multi-input metrics can silently absorb mismatched inputs — e.g. a
Heat Index built from a 1 km local-midnight daily-max temperature and a
~31 km UTC daily-mean humidity. Without per-input references that divergence
is invisible and no checker can surface it.
explanation:
tag: explanation
value: Composite heat metrics are cooked from several ingredients — temperature,
humidity, wind, sunshine. This is the ingredient list, where each entry
points to that ingredient's own full paperwork instead of hiding it inside
the final number.
description: 'Typed per-input references for a multi-input derived metric (Heat
Index from T + RH; WBGT from T + RH + wind + radiation). Each entry names the
input''s role and points, by `provenance_id`, to the upstream sidecar carrying
that input''s full context — it is an index into the lineage, not an inline
copy of it.
Option-B decomposition (see the `EquationInput` class): when the inputs originate
from different products and diverge in resolution, day-boundary convention,
or temporal aggregation, each input is a full upstream sidecar referenced here
and listed as a step in `provenance_chain`, so the divergence stays explicit
and checkable.
Conditionally-Core: optional for a single-input metric, mandatory the moment
a metric has more than one input.'
title: Equation Inputs
comments:
- 'Cross-input consistency check (completeness checker, not structural LinkML
validation): when more than one entry is present, dereference each `input_provenance_id`
and WARN if the referenced inputs'' day-boundary conventions, temporal aggregation
windows, or native spatial resolutions differ. A divergence is allowed but must
be recorded via the decomposed sidecars rather than absorbed silently into the
output value.'
examples:
- description: one entry of the list — the air-temperature input of a Liljegren
WBGT; a wind-speed entry from a divergent product (e.g. ~31 km ERA5) would
sit alongside it as a second element
object:
input_role: air_temperature
input_provenance_id: 01HFA7K8R3M6XP-daymet-tmax
input_source_short_code: daymet_v4
- description: a second list entry from a divergent product (~31 km ERA5 vs 1
km Daymet), pointing at its own full upstream sidecar
object:
input_role: wind_speed
input_provenance_id: 01HFA7K8R3M6XP-era5-wind
input_source_short_code: era5
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: EquationInput
required: true
multivalued: true
inlined: true
inlined_as_list: true
equation_validity_range:
name: equation_validity_range
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: The Rothfusz Heat Index is undefined below ~80 °F / 40 % RH; applied
outside its range an equation produces plausible-looking nonsense. Without
the recorded range, no downstream consumer can flag values computed where
the formula does not hold.
explanation:
tag: explanation
value: Every formula only works within a fence of weather conditions it was
designed for. This field writes the fence down, so anyone can check whether
a value was computed inside or outside it.
description: 'Validity-range conditions for the equation, serialised as a JSON
string. For Heat Index: `{"min_temperature_F": 80, "min_relative_humidity_pct":
40}` — Rothfusz is undefined below 80 °F / 40 % RH.'
title: Equation Validity Range
examples:
- value: '{"min_wind_speed_m_s": 0.13}'
description: Liljegren 2008 clamps wind speed below 0.13 m/s
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://www.weather.gov/safety/heat-index
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: string
required: true
equation_validity_range_missing_reason:
name: equation_validity_range_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "this equation has no published validity range" from
"the range exists but was not captured" — the difference decides whether
out-of-range screening is impossible or merely deferred.
explanation:
tag: explanation
value: 'A blank field is ambiguous: it could mean the thing does not exist,
or that nobody wrote it down. This companion field says which one it is.'
description: Reason `equation_validity_range` is null.
title: Reason Validity Range Is Missing
examples:
- value: not_provided_by_source
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: MissingReasonEnum
indoor_outdoor:
name: indoor_outdoor
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: Indoor and outdoor WBGT use different equations and carry different
health interpretations; an indoor formula applied to outdoor conditions
(or a regime left unstated) makes the value invalid or uninterpretable for
the exposure being claimed.
explanation:
tag: explanation
value: Heat stress works differently inside and outside — indoors there is
no direct sun and little wind — so heat metrics come in indoor and outdoor
versions, and you need to know which one you are looking at.
description: Indoor / outdoor regime. Mandatory for WBGT (the indoor vs outdoor
distinction changes the equation and the health interpretation).
title: Indoor or Outdoor Regime
examples:
- value: outdoor
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://www.iso.org/standard/67188.html
- https://en.wikipedia.org/wiki/Wet-bulb_globe_temperature
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: IndoorOutdoorEnum
required: true
wind_speed_measurement_height_m:
name: wind_speed_measurement_height_m
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: ISO 7243 assumes wind measured at 2 m, but reanalysis products usually
supply 10 m wind; wind is slower near the ground, so an uncorrected 10 m
input systematically shifts the resulting WBGT.
explanation:
tag: explanation
value: Wind blows faster the higher above the ground you measure it, so a
"wind speed" is only meaningful together with the height it was taken at
— this field records that height.
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: Tmax scenario carries no WBGT/UTCI inputs, so no wind-measurement
height.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No WBGT/UTCI methodology, so no wind-measurement height.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No WBGT/UTCI methodology, so no wind-measurement height.
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 models no WBGT/UTCI heat metrics.
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: WBGT wind-height metadata is instance-layer; out of scope for
CODATA.
description: For WBGT and UTCI inputs, the wind-speed measurement height in metres.
The ISO 7243 standard is 2 m, but reanalysis products often supply 10 m -- the
height affects the WBGT value.
title: Wind Speed Measurement Height (Metres)
examples:
- value: '10'
description: ERA5 10 m wind used without height adjustment
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://www.iso.org/standard/67188.html
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: float
wind_speed_measurement_height_m_missing_reason:
name: wind_speed_measurement_height_m_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "the producer never recorded a measurement height" from
"it exists upstream but was not extracted" — only the latter is recoverable,
and only the former precludes a height correction.
explanation:
tag: explanation
value: 'A blank field is ambiguous: it could mean the thing does not exist,
or that nobody wrote it down. This companion field says which one it is.'
description: Reason `wind_speed_measurement_height_m` is null.
title: Reason Measurement Height Is Missing
examples:
- value: available_but_not_extracted
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: MissingReasonEnum
solar_radiation_basis:
name: solar_radiation_basis
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: WBGT and UTCI respond strongly to solar load; whether the sun input
was a measured shortwave flux, a modelled mean radiant temperature, or absent
(triggering a fallback formula) changes the value and whether two records
are comparable at all.
explanation:
tag: explanation
value: How much sunshine hits a person is part of how hot they feel, and datasets
represent "sunshine" in different ways — or not at all. This says which
representation fed the calculation.
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: Tmax scenario carries no WBGT/UTCI inputs, so no solar-radiation
basis.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No WBGT/UTCI methodology, so no solar-radiation basis.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No WBGT/UTCI methodology, so no solar-radiation basis.
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 models no WBGT/UTCI heat metrics.
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: Solar-radiation basis is instance-layer; out of scope for CODATA.
description: For WBGT / UTCI inputs, the basis used for solar radiation.
title: Solar Radiation Basis
examples:
- value: surface_downwelling_shortwave_flux
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: SolarRadiationBasisEnum
solar_radiation_basis_missing_reason:
name: solar_radiation_basis_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "the source never stated its radiation basis" from "it
was not extracted" — deciding whether the ambiguity can be resolved by going
back to the source or is permanent.
explanation:
tag: explanation
value: 'A blank field is ambiguous: it could mean the thing does not exist,
or that nobody wrote it down. This companion field says which one it is.'
description: Reason `solar_radiation_basis` is null.
title: Reason Radiation Basis Is Missing
examples:
- value: not_provided_by_source
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: MissingReasonEnum
heat_wave_threshold_definition:
name: heat_wave_threshold_definition
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: At least seven heat-wave definitions are in active use and none are
convertible after the fact; two definitions can disagree on most flagged
days, which changes both the exposure series and the resulting mortality
estimate.
explanation:
tag: explanation
value: There is no universal definition of a heat wave. "Above 35 °C" and
"hotter than 95 % of days usually are here" are both in use and flag different
days — this field records which rulebook was applied.
description: For heat-wave flags, the definition of the threshold (absolute, percentile-local,
percentile-climatological, NWS advisory, ETCCDI).
title: Heat-Wave Threshold Definition
examples:
- value: percentile_local
description: 95th percentile of the local Tmax distribution
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://en.wikipedia.org/wiki/Heat_wave
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: HeatWaveThresholdDefinitionEnum
heat_wave_threshold_definition_missing_reason:
name: heat_wave_threshold_definition_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "this record is not a heat-wave flag, so no threshold
definition exists" from "a definition was used but not captured" — the first
is benign, the second makes the flag unusable.
explanation:
tag: explanation
value: 'A blank field is ambiguous: it could mean the thing does not exist,
or that nobody wrote it down. This companion field says which one it is.'
description: Reason `heat_wave_threshold_definition` is null.
title: Reason Threshold Definition Is Missing
examples:
- value: not_applicable
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: MissingReasonEnum
heat_wave_threshold_specifier:
name: heat_wave_threshold_specifier
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: 'The definition names the rule but not the number: two records both
marked "percentile_local" are still incomparable unless the concrete value
(95th vs 90th percentile, 35 vs 40 °C) is recorded here.'
explanation:
tag: explanation
value: The threshold definition is the type of cutoff; this is the actual
number plugged into it — like knowing a speed limit exists versus knowing
it is 50.
description: Free-form specifier paired with `heat_wave_threshold_definition`
to capture the concrete threshold values (e.g. `"35_Cel"` for an absolute threshold,
`"95"` for the 95th percentile).
title: Heat-Wave Threshold Specifier
examples:
- value: '95'
description: percentile, paired with heat_wave_threshold_definition = percentile_local
- value: 35_Cel
description: absolute threshold, paired with heat_wave_threshold_definition
= absolute
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: string
heat_wave_min_consecutive_days:
name: heat_wave_min_consecutive_days
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: A 2-day rule and a 3-day rule flag different sets of days from the
same temperature series, changing which person-days count as heat-wave-exposed
and therefore the effect estimates built on them.
explanation:
tag: explanation
value: A heat wave means it stays hot for several days in a row — but how
many days count as "several" is a choice (usually 2 or 3), and the choice
changes which days get flagged.
description: Minimum-consecutive-days rule for heat-wave flags (commonly 2 or
3). Changes which days are flagged.
title: Heat-Wave Minimum Consecutive Days
examples:
- value: '3'
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: integer
heat_wave_min_consecutive_days_missing_reason:
name: heat_wave_min_consecutive_days_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "not a heat-wave flag, so no consecutive-days rule applies"
from "a rule was applied but not recorded" — only the latter undermines
reuse of the flag.
explanation:
tag: explanation
value: 'A blank field is ambiguous: it could mean the thing does not exist,
or that nobody wrote it down. This companion field says which one it is.'
description: Reason `heat_wave_min_consecutive_days` is null.
title: Reason Consecutive Days Is Missing
examples:
- value: not_applicable
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: MissingReasonEnum
percentile_reference_period_start:
name: percentile_reference_period_start
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: In a warming climate a "95th percentile" computed over 1971-2000 is
a materially different threshold than one over 2000-2019; leaving the baseline
unstated makes percentile-based studies non-comparable and non-reproducible.
explanation:
tag: explanation
value: '"Unusually hot" means hot compared to some stretch of past years.
Which years you compare against changes what counts as unusual — this field
records where that stretch begins.'
description: 'Start of the reference distribution used for percentile-based thresholds.
Mandatory for percentile metrics: "95th percentile" over 2000-2019 gives a different
threshold than 1980-2010, and this delta is real.'
title: Percentile Reference Period Start
examples:
- value: '1991-01-01'
description: start of the 1991-2020 climate-normal baseline
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://www.ncei.noaa.gov/products/land-based-station/us-climate-normals
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: date
percentile_reference_period_start_missing_reason:
name: percentile_reference_period_start_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "not a percentile-based metric, so no baseline exists"
from "a baseline was used but not captured" — without the reason, a consumer
cannot tell a benign blank from a blocking one.
explanation:
tag: explanation
value: 'A blank field is ambiguous: it could mean the thing does not exist,
or that nobody wrote it down. This companion field says which one it is.'
description: Reason `percentile_reference_period_start` is null.
title: Reason Period Start Is Missing
examples:
- value: not_applicable
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: MissingReasonEnum
percentile_reference_period_end:
name: percentile_reference_period_end
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: Together with the start date this pins down the reference distribution;
an end date that includes or excludes the most recent warm years shifts
the percentile threshold, so an open-ended baseline is not reproducible.
explanation:
tag: explanation
value: The other end of the stretch of past years used as the comparison —
start and end together say exactly which years define "normal".
description: End of the reference distribution.
title: Percentile Reference Period End
examples:
- value: '2020-12-31'
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: date
percentile_reference_period_end_missing_reason:
name: percentile_reference_period_end_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "no percentile baseline applies to this metric" from
"the baseline end was used but never recorded" — deciding whether the threshold
is merely undocumented or genuinely absent.
explanation:
tag: explanation
value: 'A blank field is ambiguous: it could mean the thing does not exist,
or that nobody wrote it down. This companion field says which one it is.'
description: Reason `percentile_reference_period_end` is null.
title: Reason Period End Is Missing
examples:
- value: not_applicable
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: MissingReasonEnum
percentile_reference_geographic_scope:
name: percentile_reference_geographic_scope
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: A 95th percentile computed over one county and one computed over the
whole nation are very different thresholds; the scope is what encodes "hot
for here", and without it the threshold cannot be reproduced or compared
across studies.
explanation:
tag: explanation
value: '"Unusually hot" can mean hot compared to what is normal HERE, or compared
to the whole country. This field says which area''s history the comparison
was made against.'
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: Tmax scenario computes no percentile-based threshold, so no
reference geographic scope.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No percentile-based metric, so no reference geographic scope.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No percentile-based metric, so no reference geographic scope.
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's percentile normalization is EJI vulnerability, not
a heat-metric percentile baseline scope.
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: Percentile-baseline scope is instance-layer; out of scope for
CODATA.
description: Geographic scope over which the reference distribution was computed.
One of `local_tract`, `local_county`, `local_climate_region`, `national`.
title: Percentile Reference Geographic Scope
examples:
- value: local_county
description: reference distribution computed over Maricopa County
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: string
percentile_reference_geographic_scope_missing_reason:
name: percentile_reference_geographic_scope_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "the source never stated its baseline geography" from
"it was not extracted" — telling consumers whether the ambiguity is recoverable
from the source or permanent.
explanation:
tag: explanation
value: 'A blank field is ambiguous: it could mean the thing does not exist,
or that nobody wrote it down. This companion field says which one it is.'
description: Reason `percentile_reference_geographic_scope` is null.
title: Reason Geographic Scope Is Missing
examples:
- value: not_provided_by_source
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: MissingReasonEnum
percentile_reference_seasonal_window:
name: percentile_reference_seasonal_window
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: An annual reference distribution includes winter days and drags the
95th percentile far below a warm-season-only percentile; two thresholds
that sound identical diverge substantially when the seasonal window is left
unstated.
explanation:
tag: explanation
value: Whether "normal" includes the whole year or only the summer months
changes what counts as unusually hot — a day that is extreme against summer-only
history may be unremarkable against the full year.
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: No percentile-based metric in the Tmax scenario, so no seasonal
reference window.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No percentile-based metric, so no seasonal reference window.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No percentile-based metric, so no seasonal reference window.
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 carries no heat-metric seasonal reference window.
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: Seasonal reference window is instance-layer; out of scope for
CODATA.
description: Seasonal window over which the reference was computed. One of `annual`,
`warm_season_may_sep`, `calendar_month`.
title: Percentile Reference Seasonal Window
examples:
- value: warm_season_may_sep
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: string
percentile_reference_seasonal_window_missing_reason:
name: percentile_reference_seasonal_window_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "the source never stated its seasonal window" from "it
was not extracted" — so consumers know whether asking the producer could
still recover it.
explanation:
tag: explanation
value: 'A blank field is ambiguous: it could mean the thing does not exist,
or that nobody wrote it down. This companion field says which one it is.'
description: Reason `percentile_reference_seasonal_window` is null.
title: Reason Seasonal Window Is Missing
examples:
- value: not_provided_by_source
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: MissingReasonEnum
metric_temporal_aggregation_rule:
name: metric_temporal_aggregation_rule
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: Stamping a five-day event only on its first day versus on every day
changes which person-days count as exposed, directly altering effect estimates
in daily time-series and case-crossover designs.
explanation:
tag: explanation
value: A heat wave spans several days but health records are kept day by day;
this says which calendar days actually get the "heat wave" label — just
the first day, every day, or the last.
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: Tmax scenario is per-day values, not a heat-wave flag; no multi-day
event-stamping rule.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No multi-day heat-event flag, so no event-stamping rule.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No multi-day heat-event flag, so no event-stamping rule.
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 stamps no multi-day heat events onto days.
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: Multi-day event stamping is instance-layer; out of scope for
CODATA.
description: For heat-wave flags, how multi-day exposures are stamped on individual
days (e.g. `first_day_of_event` / `each_day_of_event` / `last_day_of_event`).
title: Metric Temporal Aggregation Rule
examples:
- value: each_day_of_event
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: string
metric_temporal_aggregation_rule_missing_reason:
name: metric_temporal_aggregation_rule_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "no multi-day stamping rule applies to this metric" from
"a rule was applied but never captured" — only the latter makes the daily
exposure series ambiguous.
explanation:
tag: explanation
value: 'A blank field is ambiguous: it could mean the thing does not exist,
or that nobody wrote it down. This companion field says which one it is.'
description: Reason `metric_temporal_aggregation_rule` is null.
title: Reason Aggregation Rule Is Missing
examples:
- value: available_but_not_extracted
from_schema: https://w3id.org/linkml/microschemas/envar
owner: DerivedHeatMetric
domain_of:
- DerivedHeatMetric
range: MissingReasonEnum
rules:
- preconditions:
slot_conditions:
heat_metric_family:
name: heat_metric_family
equals_string: heat_wave_flag
postconditions:
slot_conditions:
heat_wave_threshold_definition:
name: heat_wave_threshold_definition
required: true
heat_wave_min_consecutive_days:
name: heat_wave_min_consecutive_days
required: true
description: Heat-wave-flag metrics must state which of the (at least seven, mutually
unconvertible) heat-wave definitions was used and the minimum consecutive-days
criterion (tier conditionally_core context "heat-wave flavoured metrics").
- preconditions:
slot_conditions:
heat_wave_threshold_definition:
name: heat_wave_threshold_definition
equals_string_in:
- percentile_local
- percentile_climatological
postconditions:
slot_conditions:
percentile_reference_period_start:
name: percentile_reference_period_start
required: true
percentile_reference_period_end:
name: percentile_reference_period_end
required: true
description: Percentile-based heat-wave thresholds are meaningless without their
reference period — the same percentile over different baselines flags different
days (tier conditionally_core context "percentile-based thresholds").
See Also
- https://en.wikipedia.org/wiki/Wet-bulb_globe_temperature
- https://www.weather.gov/safety/heat-index
- http://www.utci.org/
Identifier and Mapping Information
Annotations
| property | value |
|---|---|
| domain_of_use | environmental_exposure |
Schema Source
- from schema: https://w3id.org/linkml/microschemas/envar
Mappings
| Mapping Type | Mapped Value |
|---|---|
| self | envar:DerivedHeatMetric |
| native | envar:DerivedHeatMetric |