Example datasets

Module	State	Present	Missing slots
(record root)	partial	14/16	uncertainty, deposit_metadata
data_layout	partial	5/10	variable_column, variable_key, native_value_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	4/7	exposure_model_cross_validation_r2, exposure_model_ensemble_member_count, bias_correction_applied
health_layer_linkage	partial	2/3	cohort_size_anchored
linkage_method	partial	7/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	partial	2/3	chain_compatibility_assertions
source_dataset	partial	9/14	source_dataset_temporal_coverage, source_dataset_spatial_extent, source_citation_bibtex, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	6/10	spatial_extent_bbox, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	full	9/9	—
tool_run	partial	10/14	tool_description, run_duration_seconds, run_environment, run_log_excerpt
uncertainty	absent	0/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_data_handling_method, missing_value_sentinel, data_completeness_pct
variable_identity	partial	13/17	native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula

Recommended missing (16): bias_correction_applied, data_completeness_pct, exposure_model_cross_validation_r2, missing_data_handling_method, model_aggregate_uncertainty, native_units_ucum, null_semantics_column, per_value_uncertainty_type, per_value_uncertainty_units_ucum, privacy_transformation, privacy_transformation_note, source_dataset_spatial_extent, source_dataset_temporal_coverage, spatial_aggregation_preserves, spatial_extent_bbox, uncertainty

Optional missing (33): chain_compatibility_assertions, cohort_size_anchored, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, exposure_model_ensemble_member_count, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, variable_column, variable_key

Explained nulls (absent, but documented with a *_missing_reason — counted as present): target_concept_id, value_uncertainty_column

Source: examples/daymet_tmax_phoenix_2022_07_19.yaml

# Worked example: Daymet V4 Tmax sidecar for Phoenix on 2022-07-19.
# Replicates the JSON block in ../../../pipeline/heat-omop-slice/envar-heat-scenario.md §4,
# restructured to use the readable top-level names (subject / variable_identity /
# spatial_reference / temporal_reference / exposure_model), each mapped to its
# LinkML Microschema Profile slot. See src/linkml_microschemas_envar/schema/README.md
# "Design decisions" for the rationale and known drawbacks.
---
schema_version: "0.1.0"
provenance_id: "01HFA7K8R3M6XP-daymet"
phi_status: no_phi

subject: "cohort:phoenix_aki_2022"

variable_identity:
  variable_name: tmax
  variable_label: "daily maximum air temperature at 2 m"
  standard_name: CF:air_temperature
  cf_cell_methods: "time: maximum"
  units_ucum: Cel
  units_display: "°C"
  target_concept_vocabulary: omop
  target_concept_id: null
  target_concept_id_missing_reason: not_provided_by_source
  concept_status: gap
  concept_mappings:
    - ECTO:0000012
  value_data_type: continuous_numeric
  value_range_plausible_min: -50
  value_range_plausible_max: 60

data_layout:
  table_orientation: wide
  value_column: tmax
  subject_column: subject_id
  time_column: date
  value_uncertainty_column:
  value_uncertainty_column_missing_reason: available_but_not_extracted

spatial_reference:
  native_spatial_resolution_m: 1000
  native_spatial_resolution_descriptor: "1 km regular grid"
  crs: "EPSG:4326"
  spatial_extent_descriptor: "CONUS + Hawaii + Puerto Rico"
  extraction_method: inverse_distance_weighted_4_nearest_cells
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: maximum
  temporal_aggregation_window_seconds: 86400
  day_boundary_convention: local_midnight
  temporal_coverage_start: "1980-01-01"
  temporal_coverage_end: "2024-12-31"
  extraction_window_start: "2018-05-01"
  extraction_window_end: "2022-09-30"
  calendar: daymet_365    # Daymet keeps Feb 29 but drops Dec 31 in leap years — not gregorian

exposure_model:
  exposure_model_type: spatial_interpolation
  exposure_model_inputs:
    - "GHCN-Daily station observations"
  exposure_model_paper_doi: "10.3334/ORNLDAAC/2129"
  exposure_model_known_biases:
    - "warm-season warm bias documented in some western US regions"
    - "interpolation degrades in sparse-station areas"

source_dataset:
  source_dataset_name: "Daymet V4 Daily Surface Weather Data"
  source_dataset_short_code: daymet_v4
  source_dataset_doi: "10.3334/ORNLDAAC/2129"
  source_dataset_version: "V4 R1"
  source_producer_institution: "NASA ORNL DAAC"
  source_citation_apa: >-
    Thornton, M.M. et al. (2022). Daymet: Daily Surface Weather Data on a
    1-km Grid for North America, Version 4 R1. ORNL DAAC.
  source_license_spdx: public-domain-us-gov
  source_native_format: netcdf4_cf
  source_access_url: "https://daymet.ornl.gov/"

linkage_method:
  linkage_strategy: point_extraction_at_residence
  geocoding_precision_propagated: range
  geocoding_score_propagated: 0.95
  address_period_alignment: address_history_from_emr
  clinical_date_assignment_convention: local_midnight    # matches exposure-side day_boundary_convention
  partial_day_attribution_rule: not_applicable
  lag_alignment_applied: none

tool_run:
  tool_name: daymet
  tool_version: "1.0.0"
  container_image_repository: "ghcr.io/degauss-org/daymet"
  container_image_digest: "sha256:a8b3c2..."
  run_arguments: '{"variables": "tmax"}'
  run_timestamp_utc: "2026-05-23T14:18:42Z"
  input_file_sha256: "9f8e7d..."
  input_row_count: 3
  output_file_sha256: "1c2d3e..."
  output_row_count: 459

provenance_chain:
  provenance_chain_terminus_type: raw_source_download
  provenance_chain_steps:
    - tool_name: geocoder
      tool_version: "3.3.0"
      run_timestamp_utc: "2026-05-23T14:02:11Z"

health_layer_linkage:
  health_layer_target: omop_external_exposure
  health_layer_link_field: exposure_source_value

Module	State	Present	Missing slots
(record root)	partial	12/16	uncertainty, provenance_chain, health_layer_linkage, deposit_metadata
data_layout	partial	2/10	variable_column, variable_key, subject_column, time_column, native_value_column, value_uncertainty_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	1/7	exposure_model_inputs, exposure_model_paper_doi, exposure_model_cross_validation_r2, exposure_model_known_biases, exposure_model_ensemble_member_count, bias_correction_applied
health_layer_linkage	absent	0/3	health_layer_target, health_layer_link_field, cohort_size_anchored
linkage_method	partial	1/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, geocoding_precision_propagated, geocoding_score_propagated, address_period_alignment, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	absent	0/3	provenance_chain_steps, provenance_chain_terminus_type, chain_compatibility_assertions
source_dataset	partial	2/14	source_dataset_short_code, source_dataset_doi, source_dataset_temporal_coverage, source_dataset_spatial_extent, source_producer_institution, source_citation_apa, source_citation_bibtex, source_license_spdx, source_access_url, source_native_format, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	4/10	native_spatial_resolution_descriptor, spatial_extent_bbox, spatial_extent_descriptor, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	partial	3/9	temporal_aggregation_window_seconds, temporal_coverage_start, temporal_coverage_end, extraction_window_start, extraction_window_end, calendar
tool_run	partial	2/14	tool_description, container_image_repository, container_image_digest, run_arguments, run_timestamp_utc, run_duration_seconds, run_environment, input_file_sha256, input_row_count, output_file_sha256, output_row_count, run_log_excerpt
uncertainty	absent	0/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_data_handling_method, missing_value_sentinel, data_completeness_pct
variable_identity	partial	6/17	variable_label, units_display, native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula, target_concept_vocabulary, target_concept_id, concept_mappings, value_range_plausible_min, value_range_plausible_max

Recommended missing (61): address_period_alignment, bias_correction_applied, calendar, container_image_digest, container_image_repository, data_completeness_pct, exposure_model_cross_validation_r2, exposure_model_inputs, exposure_model_known_biases, exposure_model_paper_doi, extraction_window_end, extraction_window_start, geocoding_precision_propagated, geocoding_score_propagated, health_layer_link_field, health_layer_linkage, health_layer_target, input_file_sha256, input_row_count, lag_alignment_applied, missing_data_handling_method, model_aggregate_uncertainty, native_spatial_resolution_descriptor, native_units_ucum, null_semantics_column, output_file_sha256, output_row_count, partial_day_attribution_rule, per_value_uncertainty_type, per_value_uncertainty_units_ucum, privacy_transformation, privacy_transformation_note, provenance_chain, provenance_chain_steps, provenance_chain_terminus_type, run_arguments, run_timestamp_utc, source_access_url, source_citation_apa, source_dataset_doi, source_dataset_short_code, source_dataset_spatial_extent, source_dataset_temporal_coverage, source_license_spdx, source_native_format, source_producer_institution, spatial_aggregation_preserves, spatial_extent_bbox, spatial_extent_descriptor, subject_column, target_concept_id, target_concept_vocabulary, temporal_aggregation_window_seconds, temporal_coverage_end, temporal_coverage_start, time_column, uncertainty, value_range_plausible_max, value_range_plausible_min, value_uncertainty_column, variable_label

Optional missing (36): chain_compatibility_assertions, clinical_date_assignment_convention, cohort_size_anchored, concept_mappings, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, exposure_model_ensemble_member_count, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, units_display, variable_column, variable_key

Source: tests/data/valid/EnvironmentalExposureRecord-tmax_core.yaml

# TMAX — CORE tier (the minimum that still validates).
# Exactly the required Core fields, nothing more. Contrast with the
# `core_missing` counter-example under tests/data/invalid/, which drops some of
# these required fields and therefore fails validation.
schema_version: "0.1"
provenance_id: "01HFA7K8R3M6XP-daymet-core"
phi_status: no_phi
subject: "cohort:phoenix_aki_2022"

variable_identity:
  variable_name: tmax
  standard_name: CF:air_temperature
  cf_cell_methods: "time: maximum"
  units_ucum: Cel
  concept_status: gap
  value_data_type: continuous_numeric

data_layout:
  table_orientation: wide
  value_column: tmax

spatial_reference:
  native_spatial_resolution_m: 1000
  crs: "EPSG:4326"
  extraction_method: inverse_distance_weighted_4_nearest_cells
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: maximum
  day_boundary_convention: local_midnight

exposure_model:
  exposure_model_type: spatial_interpolation

source_dataset:
  source_dataset_name: "Daymet V4 Daily Surface Weather Data"
  source_dataset_version: "V4 R1"

linkage_method:
  linkage_strategy: point_extraction_at_residence

tool_run:
  tool_name: daymet
  tool_version: "1.0.0"

Module	State	Present	Missing slots
(record root)	partial	15/16	deposit_metadata
data_layout	partial	5/10	variable_column, variable_key, native_value_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	4/7	exposure_model_cross_validation_r2, exposure_model_ensemble_member_count, bias_correction_applied
health_layer_linkage	partial	2/3	cohort_size_anchored
linkage_method	partial	4/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	partial	2/3	chain_compatibility_assertions
source_dataset	partial	9/14	source_dataset_temporal_coverage, source_dataset_spatial_extent, source_citation_bibtex, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	6/10	spatial_extent_bbox, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	full	9/9	—
tool_run	partial	10/14	tool_description, run_duration_seconds, run_environment, run_log_excerpt
uncertainty	partial	2/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_value_sentinel
variable_identity	partial	12/17	native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula, concept_mappings

Recommended missing (15): bias_correction_applied, exposure_model_cross_validation_r2, lag_alignment_applied, model_aggregate_uncertainty, native_units_ucum, null_semantics_column, partial_day_attribution_rule, per_value_uncertainty_type, per_value_uncertainty_units_ucum, privacy_transformation, privacy_transformation_note, source_dataset_spatial_extent, source_dataset_temporal_coverage, spatial_aggregation_preserves, spatial_extent_bbox

Optional missing (35): chain_compatibility_assertions, clinical_date_assignment_convention, cohort_size_anchored, concept_mappings, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, exposure_model_ensemble_member_count, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, variable_column, variable_key

Explained nulls (absent, but documented with a *_missing_reason — counted as present): target_concept_id, value_uncertainty_column

Source: tests/data/valid/EnvironmentalExposureRecord-tmax_recommended.yaml

schema_version: "0.1"
provenance_id: "01HFA7K8R3M6XP-daymet"

variable_identity:
  variable_name: tmax
  variable_label: "daily maximum air temperature at 2 m"
  standard_name: CF:air_temperature
  cf_cell_methods: "time: maximum"
  units_ucum: Cel
  units_display: "°C"
  value_data_type: continuous_numeric
  value_range_plausible_min: -50
  value_range_plausible_max: 60
  target_concept_vocabulary: omop
  target_concept_id:
  target_concept_id_missing_reason: not_provided_by_source
  concept_status: gap
  # concept_mappings omitted — available but not extracted

data_layout:
  table_orientation: wide
  value_column: tmax
  subject_column: subject_id
  time_column: date
  value_uncertainty_column:
  value_uncertainty_column_missing_reason: available_but_not_extracted

spatial_reference:
  native_spatial_resolution_m: 1000
  native_spatial_resolution_descriptor: "1 km regular grid"
  crs: "EPSG:4326"
  spatial_extent_descriptor: "CONUS + Hawaii + Puerto Rico"
  extraction_method: inverse_distance_weighted_4_nearest_cells
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: maximum
  temporal_aggregation_window_seconds: 86400
  day_boundary_convention: local_midnight        # the field the opening story turns on
  temporal_coverage_start: "1980-01-01"
  temporal_coverage_end: "2024-12-31"
  extraction_window_start: "2022-07-18"
  extraction_window_end: "2022-07-20"
  calendar: daymet_365

source_dataset:
  source_dataset_name: "Daymet V4 Daily Surface Weather Data"
  source_dataset_short_code: daymet_v4
  source_dataset_doi: "10.3334/ORNLDAAC/2129"
  source_dataset_version: "V4 R1"
  source_producer_institution: "NASA ORNL DAAC"
  source_citation_apa: >-
    Thornton, M.M., Shrestha, R., Wei, Y., Thornton, P.E., Kao, S.-C., &
    Wilson, B.E. (2022). Daymet: Daily Surface Weather Data on a 1-km Grid
    for North America, Version 4 R1. ORNL DAAC, Oak Ridge, Tennessee, USA.
  source_license_spdx: public-domain-us-gov
  source_native_format: netcdf4_cf
  source_access_url: "https://daymet.ornl.gov/"

exposure_model:
  exposure_model_type: spatial_interpolation
  exposure_model_inputs:
  - "GHCN-Daily station observations"
  exposure_model_paper_doi: "10.3334/ORNLDAAC/2129"
  exposure_model_known_biases:
  - "warm-season warm bias documented in some western US regions"
  - "interpolation degrades in sparse-station areas"

uncertainty:
  missing_data_handling_method: spatiotemporal_interpolation
  data_completeness_pct: 100

linkage_method:
  linkage_strategy: point_extraction_at_residence
  geocoding_precision_propagated: range
  geocoding_score_propagated: 0.95
  address_period_alignment: address_history_from_emr

tool_run:
  tool_name: daymet
  tool_version: "1.0.0"
  container_image_repository: "ghcr.io/degauss-org/daymet"
  container_image_digest: "sha256:a8b3c2d1e0f9..."
  run_arguments: '{"variables": "tmax"}'
  run_timestamp_utc: "2026-05-23T14:18:42Z"
  input_file_sha256: "9f8e7d6c5b4a..."
  input_row_count: 3
  output_file_sha256: "1c2d3e4f5a6b..."
  output_row_count: 459

provenance_chain:
  provenance_chain_terminus_type: raw_source_download
  provenance_chain_steps:
  - tool_name: geocoder
    tool_version: "3.3.0"
    run_timestamp_utc: "2026-05-23T14:02:11Z"

health_layer_linkage:
  health_layer_target: omop_external_exposure
  health_layer_link_field: exposure_source_value
subject: "cohort:phoenix_aki_2022"
# Companion data row (in the accompanying CSV/parquet, not the sidecar):
#   subject_id: "cohort:phoenix_aki_2022"  date: "2022-07-19"  tmax: 46.7
phi_status: no_phi

Module	State	Present	Missing slots
(record root)	full	16/16	—
data_layout	partial	6/10	variable_column, variable_key, native_value_column, null_semantics_column
deposit_metadata	partial	5/6	deposit_redistribution_constraints_inherited
exposure_model	full	7/7	—
health_layer_linkage	full	3/3	—
linkage_method	partial	7/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	partial	2/3	chain_compatibility_assertions
source_dataset	partial	13/14	source_homogenisation_status
spatial_reference	partial	8/10	population_weighting_source, spatial_aggregation_preserves
temporal_reference	full	9/9	—
tool_run	partial	13/14	run_log_excerpt
uncertainty	partial	4/7	model_aggregate_uncertainty, quality_flag_vocabulary, missing_value_sentinel
variable_identity	partial	13/17	native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula

Recommended missing (6): model_aggregate_uncertainty, native_units_ucum, null_semantics_column, privacy_transformation, privacy_transformation_note, spatial_aggregation_preserves

Optional missing (18): chain_compatibility_assertions, deposit_redistribution_constraints_inherited, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_vocabulary, run_log_excerpt, source_homogenisation_status, unit_conversion_formula, variable_column, variable_key

Explained nulls (absent, but documented with a *_missing_reason — counted as present): exposure_model_cross_validation_r2, exposure_model_ensemble_member_count, extraction_buffer_m, quality_flag_column, target_concept_id

Source: tests/data/valid/EnvironmentalExposureRecord-tmax_ideal.yaml

schema_version: "0.1"
provenance_id: "01HFA7K8R3M6XP-daymet-deposit"

variable_identity:
  variable_name: tmax
  variable_label: "daily maximum air temperature at 2 m"
  standard_name: CF:air_temperature
  cf_cell_methods: "time: maximum"
  units_ucum: Cel
  units_display: "°C"
  value_data_type: continuous_numeric
  value_range_plausible_min: -50
  value_range_plausible_max: 60
  target_concept_vocabulary: omop
  target_concept_id:
  target_concept_id_missing_reason: not_provided_by_source
  concept_status: gap
  concept_mappings:
    - ECTO:0000012   # exposure to temperature
    - ENVO:03000049  # temperature of air (illustrative)
    # no LOINC / SNOMED — not applicable to an ambient environmental variable

data_layout:
  table_orientation: wide
  value_column: tmax
  subject_column: subject_id
  time_column: date
  value_uncertainty_column: tmax_stderr
  quality_flag_column:
  quality_flag_column_missing_reason: not_provided_by_source

spatial_reference:
  native_spatial_resolution_m: 1000
  native_spatial_resolution_descriptor: "1 km regular grid"
  crs: "EPSG:4326"
  spatial_extent_bbox: [-131.104, 14.075, -52.95, 53.038]
  spatial_extent_descriptor: "CONUS + Hawaii + Puerto Rico"
  extraction_method: inverse_distance_weighted_4_nearest_cells
  extraction_buffer_m:
  extraction_buffer_m_missing_reason: not_applicable
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: maximum
  temporal_aggregation_window_seconds: 86400
  day_boundary_convention: local_midnight
  temporal_coverage_start: "1980-01-01"
  temporal_coverage_end: "2024-12-31"
  extraction_window_start: "2022-07-18"
  extraction_window_end: "2022-07-20"
  calendar: daymet_365

source_dataset:
  source_dataset_name: "Daymet V4 Daily Surface Weather Data"
  source_dataset_short_code: daymet_v4
  source_dataset_doi: "10.3334/ORNLDAAC/2129"
  source_dataset_version: "V4 R1"
  source_dataset_temporal_coverage: "1980-01-01/2024-12-31"
  source_dataset_spatial_extent: "CONUS, Hawaii, Puerto Rico"
  source_producer_institution: "NASA ORNL DAAC"
  source_citation_apa: >-
    Thornton, M.M., Shrestha, R., Wei, Y., Thornton, P.E., Kao, S.-C., &
    Wilson, B.E. (2022). Daymet: Daily Surface Weather Data on a 1-km Grid
    for North America, Version 4 R1. ORNL DAAC, Oak Ridge, Tennessee, USA.
  source_citation_bibtex: >-
    @misc{daymet_v4_r1, title={Daymet: Daily Surface Weather Data on a 1-km
    Grid for North America, Version 4 R1}, author={Thornton, M.M. and others},
    year={2022}, publisher={ORNL DAAC}, doi={10.3334/ORNLDAAC/2129}}
  source_license_spdx: public-domain-us-gov
  source_access_url: "https://daymet.ornl.gov/"
  source_native_format: netcdf4_cf
  source_acdd_attributes:
    title: "Daymet Daily Surface Weather Data"
    institution: "ORNL DAAC"
    Conventions: "CF-1.6, ACDD-1.3"
    source: "GHCN-Daily station observations"

exposure_model:
  exposure_model_type: spatial_interpolation
  exposure_model_inputs:
  - "GHCN-Daily station observations"
  exposure_model_paper_doi: "10.3334/ORNLDAAC/2129"
  exposure_model_cross_validation_r2:
  exposure_model_cross_validation_r2_missing_reason: not_provided_by_source
  exposure_model_known_biases:
  - "warm-season warm bias documented in some western US regions"
  - "interpolation degrades in sparse-station areas"
  exposure_model_ensemble_member_count:
  exposure_model_ensemble_member_count_missing_reason: not_applicable
  bias_correction_applied: none

uncertainty:
  per_value_uncertainty_type: standard_error
  per_value_uncertainty_units_ucum: Cel
  missing_data_handling_method: spatiotemporal_interpolation
  data_completeness_pct: 100

linkage_method:
  linkage_strategy: point_extraction_at_residence
  geocoding_precision_propagated: range
  geocoding_score_propagated: 0.95
  address_period_alignment: address_history_from_emr
  clinical_date_assignment_convention: local_midnight    # matches exposure-side day_boundary_convention
  partial_day_attribution_rule: not_applicable
  lag_alignment_applied: none

tool_run:
  tool_name: daymet
  tool_version: "1.0.0"
  tool_description: "DeGAUSS Daymet extraction container"
  container_image_repository: "ghcr.io/degauss-org/daymet"
  container_image_digest: "sha256:a8b3c2d1e0f9..."
  run_arguments: '{"variables": "tmax"}'
  run_timestamp_utc: "2026-05-23T14:18:42Z"
  run_duration_seconds: 37
  run_environment:
    os: "Ubuntu 22.04"
    container_runtime: "docker 24.0.7"
    r_version: "4.3.1"
  input_file_sha256: "9f8e7d6c5b4a..."
  input_row_count: 3
  output_file_sha256: "1c2d3e4f5a6b..."
  output_row_count: 459

provenance_chain:
  provenance_chain_terminus_type: raw_source_download
  provenance_chain_steps:
  - tool_name: geocoder
    tool_version: "3.3.0"
    run_timestamp_utc: "2026-05-23T14:02:11Z"
    output_file_sha256: "5b6c7d8e9f0a..."

health_layer_linkage:
  health_layer_target: omop_external_exposure
  health_layer_link_field: exposure_source_value
  cohort_size_anchored: 3
deposit_metadata:
  deposit_doi: "10.5281/zenodo.9999999"
  deposit_repository: zenodo
  deposit_license_spdx: CC-BY-4.0
  deposit_redistribution_constraints_inherited: []
  recommended_citation: >-
    EnVar exposure record for cohort:phoenix_aki_2022 daily Tmax (Daymet V4),
    2026. Deposited at Zenodo, doi:10.5281/zenodo.9999999.
  dcat_distribution_url: "https://zenodo.org/record/9999999/files/tmax_phoenix.parquet"

subject: "cohort:phoenix_aki_2022"
# Companion data row (in the accompanying CSV/parquet, not the sidecar):
#   date: "2022-07-19"  value: 46.7  unit: Cel  tmax_stderr: 0.8
phi_status: no_phi

Module	State	Present	Missing slots
(record root)	partial	12/16	uncertainty, provenance_chain, health_layer_linkage, deposit_metadata
data_layout	partial	2/10	variable_column, variable_key, subject_column, time_column, native_value_column, value_uncertainty_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	2/7	exposure_model_inputs, exposure_model_paper_doi, exposure_model_cross_validation_r2, exposure_model_known_biases, bias_correction_applied
health_layer_linkage	absent	0/3	health_layer_target, health_layer_link_field, cohort_size_anchored
linkage_method	partial	1/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, geocoding_precision_propagated, geocoding_score_propagated, address_period_alignment, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	absent	0/3	provenance_chain_steps, provenance_chain_terminus_type, chain_compatibility_assertions
source_dataset	partial	2/14	source_dataset_short_code, source_dataset_doi, source_dataset_temporal_coverage, source_dataset_spatial_extent, source_producer_institution, source_citation_apa, source_citation_bibtex, source_license_spdx, source_access_url, source_native_format, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	4/10	native_spatial_resolution_descriptor, spatial_extent_bbox, spatial_extent_descriptor, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	partial	3/9	temporal_aggregation_window_seconds, temporal_coverage_start, temporal_coverage_end, extraction_window_start, extraction_window_end, calendar
tool_run	partial	2/14	tool_description, container_image_repository, container_image_digest, run_arguments, run_timestamp_utc, run_duration_seconds, run_environment, input_file_sha256, input_row_count, output_file_sha256, output_row_count, run_log_excerpt
uncertainty	absent	0/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_data_handling_method, missing_value_sentinel, data_completeness_pct
variable_identity	partial	6/17	variable_label, units_display, native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula, target_concept_vocabulary, target_concept_id, concept_mappings, value_range_plausible_min, value_range_plausible_max

Recommended missing (61): address_period_alignment, bias_correction_applied, calendar, container_image_digest, container_image_repository, data_completeness_pct, exposure_model_cross_validation_r2, exposure_model_inputs, exposure_model_known_biases, exposure_model_paper_doi, extraction_window_end, extraction_window_start, geocoding_precision_propagated, geocoding_score_propagated, health_layer_link_field, health_layer_linkage, health_layer_target, input_file_sha256, input_row_count, lag_alignment_applied, missing_data_handling_method, model_aggregate_uncertainty, native_spatial_resolution_descriptor, native_units_ucum, null_semantics_column, output_file_sha256, output_row_count, partial_day_attribution_rule, per_value_uncertainty_type, per_value_uncertainty_units_ucum, privacy_transformation, privacy_transformation_note, provenance_chain, provenance_chain_steps, provenance_chain_terminus_type, run_arguments, run_timestamp_utc, source_access_url, source_citation_apa, source_dataset_doi, source_dataset_short_code, source_dataset_spatial_extent, source_dataset_temporal_coverage, source_license_spdx, source_native_format, source_producer_institution, spatial_aggregation_preserves, spatial_extent_bbox, spatial_extent_descriptor, subject_column, target_concept_id, target_concept_vocabulary, temporal_aggregation_window_seconds, temporal_coverage_end, temporal_coverage_start, time_column, uncertainty, value_range_plausible_max, value_range_plausible_min, value_uncertainty_column, variable_label

Optional missing (35): chain_compatibility_assertions, clinical_date_assignment_convention, cohort_size_anchored, concept_mappings, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, units_display, variable_column, variable_key

Source: tests/data/valid/EnvironmentalExposureRecord-pm25_core.yaml

# PM2.5 — CORE tier (the minimum that still validates).
# Exactly the required Core fields, nothing more. Contrast with the
# `core_missing` counter-example under tests/data/invalid/.
schema_version: "0.1"
provenance_id: "01HXDIENSEMBLEML00000PM25-core"
phi_status: no_phi
subject: "cohort:phoenix_aki_2022"

variable_identity:
  variable_name: pm25
  standard_name: CF:mass_concentration_of_pm2p5_ambient_aerosol_particles_in_air
  cf_cell_methods: "time: mean"
  units_ucum: ug/m3
  concept_status: proposed
  value_data_type: continuous_numeric

data_layout:
  table_orientation: wide
  value_column: pm25

spatial_reference:
  native_spatial_resolution_m: 1000
  crs: "EPSG:4326"
  extraction_method: nearest_cell
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: mean
  day_boundary_convention: utc_midnight

exposure_model:
  exposure_model_type: ensemble_machine_learning
  exposure_model_ensemble_member_count: 3

source_dataset:
  source_dataset_name: "Di et al. ensemble PM2.5 (contiguous US)"
  source_dataset_version: "v1.0"

linkage_method:
  linkage_strategy: point_extraction_at_residence

tool_run:
  tool_name: pm25_extract
  tool_version: "1.0.0"

Module	State	Present	Missing slots
(record root)	partial	15/16	deposit_metadata
data_layout	partial	5/10	variable_column, variable_key, native_value_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	6/7	bias_correction_applied
health_layer_linkage	full	3/3	—
linkage_method	partial	4/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	partial	2/3	chain_compatibility_assertions
source_dataset	partial	9/14	source_dataset_temporal_coverage, source_dataset_spatial_extent, source_citation_bibtex, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	6/10	spatial_extent_bbox, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	full	9/9	—
tool_run	partial	10/14	tool_description, run_duration_seconds, run_environment, run_log_excerpt
uncertainty	partial	5/7	quality_flag_vocabulary, missing_value_sentinel
variable_identity	partial	12/17	native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula, concept_mappings

Recommended missing (11): bias_correction_applied, lag_alignment_applied, native_units_ucum, null_semantics_column, partial_day_attribution_rule, privacy_transformation, privacy_transformation_note, source_dataset_spatial_extent, source_dataset_temporal_coverage, spatial_aggregation_preserves, spatial_extent_bbox

Optional missing (33): chain_compatibility_assertions, clinical_date_assignment_convention, concept_mappings, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, variable_column, variable_key

Explained nulls (absent, but documented with a *_missing_reason — counted as present): target_concept_id

Source: tests/data/valid/EnvironmentalExposureRecord-pm25_recommended.yaml

schema_version: "0.1"
provenance_id: "01HXDIENSEMBLEML00000PM25SURF"

variable_identity:
  variable_name: pm25_daily
  variable_label: "daily mean fine particulate matter (PM2.5) mass concentration, modeled"
  standard_name: CF:mass_concentration_of_pm2p5_ambient_aerosol_particles_in_air
  cf_cell_methods: "time: mean"
  units_ucum: ug/m3
  units_display: "µg/m³"
  value_data_type: continuous_numeric
  value_range_plausible_min: 0
  value_range_plausible_max: 1000
  target_concept_vocabulary: omop
  target_concept_id:
  target_concept_id_missing_reason: not_provided_by_source
  concept_status: proposed   # PM2.5 within OHDSI GIS/Exposome vocabulary effort
  # concept_mappings omitted — available but not extracted

data_layout:
  table_orientation: wide
  value_column: pm25_daily
  subject_column: subject_id
  time_column: date
  value_uncertainty_column: pm25_monthly_se

spatial_reference:
  native_spatial_resolution_m: 1000
  native_spatial_resolution_descriptor: "1 km modeled grid"
  crs: "EPSG:4326"
  spatial_extent_descriptor: "contiguous United States"
  extraction_method: nearest_cell
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: mean
  temporal_aggregation_window_seconds: 86400
  day_boundary_convention: utc_midnight
  temporal_coverage_start: "2000-01-01"
  temporal_coverage_end: "2016-12-31"
  extraction_window_start: "2016-07-01"
  extraction_window_end: "2016-07-31"
  calendar: gregorian

source_dataset:
  source_dataset_name: "Di et al. ensemble PM2.5 daily predictions, contiguous US, 1 km"
  source_dataset_short_code: di_pm25_ensemble
  source_dataset_doi: "10.1016/j.envint.2019.104909"
  source_dataset_version: "v1 (2000-2016)"
  source_producer_institution: "Harvard T.H. Chan School of Public Health / NASA SEDAC"
  source_citation_apa: >-
    Di, Q., Amini, H., Shi, L., et al. (2019). An ensemble-based model of
    PM2.5 concentration across the contiguous United States with high
    spatiotemporal resolution. Environment International, 130, 104909.
  source_license_spdx: CC-BY-4.0
  source_access_url: "https://www.epa.gov/aqs"
  source_native_format: netcdf4_cf

exposure_model:
  exposure_model_type: ensemble_machine_learning
  exposure_model_inputs:
  - "EPA AQS monitor observations"
  - "MAIAC satellite AOD"
  - "GEOS-Chem chemical transport model output"
  - "meteorology, land-use, and elevation covariates"
  exposure_model_paper_doi: "10.1016/j.envint.2019.104909"
  exposure_model_cross_validation_r2: 0.86
  exposure_model_known_biases:
  - "underprediction of high-concentration peaks (smoothing toward the mean)"
  - "larger error in sparsely-monitored rural and western regions"
  exposure_model_ensemble_member_count: 3

uncertainty:
  per_value_uncertainty_type: ensemble_std_dev
  per_value_uncertainty_units_ucum: ug/m3
  model_aggregate_uncertainty:
    cv_r2: 0.86
    reported_in: "10.1016/j.envint.2019.104909"
  missing_data_handling_method: none
  data_completeness_pct: 100

linkage_method:
  linkage_strategy: point_extraction_at_residence
  geocoding_precision_propagated: street
  geocoding_score_propagated: 0.91
  address_period_alignment: address_history_from_emr

tool_run:
  tool_name: aqdh_pm25_extract
  tool_version: "2.1.0"
  container_image_repository: "ghcr.io/example/aqdh-pm25"
  container_image_digest: "sha256:dd4477aa1199..."
  run_arguments: '{"variable": "pm25", "window": "2016-07"}'
  run_timestamp_utc: "2026-05-24T09:11:03Z"
  input_file_sha256: "ab12cd34..."
  input_row_count: 3
  output_file_sha256: "ef56ab78..."
  output_row_count: 93

provenance_chain:
  provenance_chain_terminus_type: pre_existing_curated_dataset
  provenance_chain_steps:
  - tool_name: geocoder
    tool_version: "3.3.0"
    run_timestamp_utc: "2026-05-24T09:01:55Z"

health_layer_linkage:
  health_layer_target: omop_external_exposure
  health_layer_link_field: exposure_source_value
  cohort_size_anchored: 3
subject: "cohort:phoenix_aki_2022"
# Companion data row (in the accompanying CSV/parquet, not the sidecar):
#   subject_id: "cohort:phoenix_aki_2022"  date: "2016-07-19"  pm25_daily: 9.7  pm25_monthly_se: 1.3
phi_status: no_phi

Module	State	Present	Missing slots
(record root)	full	16/16	—
data_layout	partial	8/10	native_value_column, null_semantics_column
deposit_metadata	partial	5/6	deposit_redistribution_constraints_inherited
exposure_model	full	7/7	—
health_layer_linkage	full	3/3	—
linkage_method	partial	8/14	linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	partial	2/3	chain_compatibility_assertions
source_dataset	partial	13/14	source_homogenisation_status
spatial_reference	partial	8/10	extraction_buffer_m, spatial_aggregation_preserves
temporal_reference	full	9/9	—
tool_run	partial	13/14	run_log_excerpt
uncertainty	partial	5/7	quality_flag_vocabulary, missing_value_sentinel
variable_identity	partial	13/17	native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula

Recommended missing (5): native_units_ucum, null_semantics_column, privacy_transformation, privacy_transformation_note, spatial_aggregation_preserves

Optional missing (15): chain_compatibility_assertions, deposit_redistribution_constraints_inherited, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, quality_flag_vocabulary, run_log_excerpt, source_homogenisation_status, unit_conversion_formula

Explained nulls (absent, but documented with a *_missing_reason — counted as present): exposure_model_ensemble_member_count, quality_flag_column, target_concept_id

Source: tests/data/valid/EnvironmentalExposureRecord-pm25_ideal.yaml

schema_version: "0.1"
provenance_id: "01HXACAGSATELLITE0000PM25ANN"

variable_identity:
  variable_name: pm25_annual
  variable_label: "annual mean fine particulate matter (PM2.5) mass concentration, satellite-derived"
  standard_name: CF:mass_concentration_of_pm2p5_ambient_aerosol_particles_in_air
  cf_cell_methods: "time: mean"
  units_ucum: ug/m3
  units_display: "µg/m³"
  value_data_type: continuous_numeric
  value_range_plausible_min: 0
  value_range_plausible_max: 500
  target_concept_vocabulary: omop
  target_concept_id:
  target_concept_id_missing_reason: not_provided_by_source
  concept_status: proposed
  concept_mappings:
    - ECTO:7000117   # exposure to fine respirable suspended particulate matter
    - ENVO:01000415  # fine respirable suspended particulate matter
    # no LOINC / SNOMED — not applicable to an ambient environmental variable

# Long-format companion file: one shared `value` column, variables
# discriminated by the `variable` column.
data_layout:
  table_orientation: long
  value_column: value
  variable_column: variable
  variable_key: pm25_annual
  subject_column: tract_id
  time_column: year
  value_uncertainty_column: pm25_uncertainty
  quality_flag_column:
  quality_flag_column_missing_reason: not_provided_by_source

spatial_reference:
  native_spatial_resolution_m: 1000
  native_spatial_resolution_descriptor: "~0.01° (~1 km) geophysical+GWR grid"
  crs: "EPSG:4326"
  spatial_extent_bbox: [-180.0, -55.0, 180.0, 70.0]
  spatial_extent_descriptor: "global land surface"
  extraction_method: area_weighted_polygon_mean
  population_weighting_source: "GPW v4 (2020)"
  target_geography_type: census_tract

temporal_reference:
  temporal_resolution: annual
  temporal_aggregation_method: mean
  temporal_aggregation_window_seconds: 31536000
  day_boundary_convention: not_applicable    # annual aggregate; no day boundary
  temporal_coverage_start: "1998-01-01"
  temporal_coverage_end: "2022-12-31"
  extraction_window_start: "2019-01-01"
  extraction_window_end: "2019-12-31"
  calendar: gregorian

source_dataset:
  source_dataset_name: "ACAG Surface PM2.5 (V5.GL), satellite-derived global estimates"
  source_dataset_short_code: acag_pm25_v5gl
  source_dataset_doi: "10.1021/acs.est.1c05309"
  source_dataset_version: "V5.GL.04"
  source_dataset_temporal_coverage: "1998-01-01/2022-12-31"
  source_dataset_spatial_extent: "global land surface"
  source_producer_institution: "Atmospheric Composition Analysis Group (Washington University in St. Louis)"
  source_citation_apa: >-
    van Donkelaar, A., Hammer, M.S., Bindle, L., et al. (2021). Monthly
    Global Estimates of Fine Particulate Matter and Their Uncertainty.
    Environmental Science & Technology, 55(22), 15287-15300.
  source_citation_bibtex: >-
    @article{vandonkelaar2021, title={Monthly Global Estimates of Fine
    Particulate Matter and Their Uncertainty}, author={van Donkelaar, A. and
    others}, journal={Environ. Sci. Technol.}, volume={55}, number={22},
    pages={15287--15300}, year={2021}, doi={10.1021/acs.est.1c05309}}
  source_license_spdx: CC-BY-4.0
  source_access_url: "https://sites.wustl.edu/acag/datasets/surface-pm2-5/"
  source_native_format: netcdf4_cf
  source_acdd_attributes:
    title: "ACAG Surface PM2.5 V5.GL"
    institution: "Atmospheric Composition Analysis Group, Washington University in St. Louis"
    Conventions: "CF-1.8, ACDD-1.3"
    source: "MODIS/MISR/SeaWiFS AOD + GEOS-Chem + GWR calibration to monitors"

exposure_model:
  exposure_model_type: satellite_retrieval
  exposure_model_inputs:
  - "satellite aerosol optical depth (MODIS, MISR, SeaWiFS)"
  - "GEOS-Chem chemical transport model"
  - "geographically weighted regression calibration to ground monitors"
  exposure_model_paper_doi: "10.1021/acs.est.1c05309"
  exposure_model_cross_validation_r2: 0.90
  exposure_model_known_biases:
  - "AOD-to-surface conversion uncertainty highest in arid and high-altitude regions"
  - "sparse-monitor regions rely more heavily on the geophysical prior"
  exposure_model_ensemble_member_count:
  exposure_model_ensemble_member_count_missing_reason: not_applicable
  bias_correction_applied: other

uncertainty:
  per_value_uncertainty_type: prediction_interval
  per_value_uncertainty_units_ucum: ug/m3
  model_aggregate_uncertainty:
    cv_r2: 0.90
    reported_in: "10.1021/acs.est.1c05309"
  missing_data_handling_method: none
  data_completeness_pct: 100

linkage_method:
  linkage_strategy: population_weighted_area_to_residence
  linkage_buffer_aggregation_method: area_weighted_mean
  geocoding_precision_propagated: street
  geocoding_score_propagated: 0.93
  address_period_alignment: address_history_from_emr
  clinical_date_assignment_convention: date_only_no_time    # annual aggregate; date-only clinical join
  partial_day_attribution_rule: not_applicable
  lag_alignment_applied: none

tool_run:
  tool_name: acag_pm25_extract
  tool_version: "1.4.2"
  tool_description: "ACAG V5.GL annual PM2.5 tract aggregation"
  container_image_repository: "ghcr.io/example/acag-pm25"
  container_image_digest: "sha256:99aabb22ccdd..."
  run_arguments: '{"variable": "pm25", "year": 2019, "aggregation": "tract_pop_weighted"}'
  run_timestamp_utc: "2026-05-24T10:42:18Z"
  run_duration_seconds: 51
  run_environment:
    os: "Ubuntu 22.04"
    container_runtime: "docker 24.0.7"
    python_version: "3.11.6"
  input_file_sha256: "1122334455..."
  input_row_count: 3
  output_file_sha256: "6677889900..."
  output_row_count: 3

provenance_chain:
  provenance_chain_terminus_type: raw_source_download
  provenance_chain_steps:
  - tool_name: geocoder
    tool_version: "3.3.0"
    run_timestamp_utc: "2026-05-24T10:30:02Z"
    output_file_sha256: "aa11bb22cc33..."

health_layer_linkage:
  health_layer_target: omop_external_exposure
  health_layer_link_field: exposure_source_value
  cohort_size_anchored: 3
deposit_metadata:
  deposit_doi: "10.5281/zenodo.8888888"
  deposit_repository: zenodo
  deposit_license_spdx: CC-BY-4.0
  deposit_redistribution_constraints_inherited: []
  recommended_citation: >-
    EnVar exposure record for cohort:phoenix_aki_2022 annual-mean PM2.5
    (ACAG V5.GL), 2019. Deposited at Zenodo, doi:10.5281/zenodo.8888888.
  dcat_distribution_url: "https://zenodo.org/record/8888888/files/pm25_annual_tract.parquet"

subject: "cohort:phoenix_aki_2022"
# Companion data row (in the accompanying CSV/parquet, not the sidecar; long
# format — this record's rows are those with variable == pm25_annual):
#   tract_id: "04013-1125"  year: 2019  variable: pm25_annual  value: 8.2  pm25_uncertainty: 1.1
phi_status: no_phi

Module	State	Present	Missing slots
(record root)	partial	13/16	uncertainty, health_layer_linkage, deposit_metadata
data_layout	partial	2/10	variable_column, variable_key, subject_column, time_column, native_value_column, value_uncertainty_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	4/7	exposure_model_cross_validation_r2, exposure_model_ensemble_member_count, bias_correction_applied
health_layer_linkage	absent	0/3	health_layer_target, health_layer_link_field, cohort_size_anchored
linkage_method	partial	4/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	partial	2/3	chain_compatibility_assertions
source_dataset	partial	8/14	source_dataset_temporal_coverage, source_dataset_spatial_extent, source_citation_apa, source_citation_bibtex, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	6/10	spatial_extent_bbox, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	full	9/9	—
tool_run	partial	8/14	tool_description, run_duration_seconds, run_environment, input_file_sha256, input_row_count, run_log_excerpt
uncertainty	absent	0/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_data_handling_method, missing_value_sentinel, data_completeness_pct
variable_identity	partial	10/17	native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula, target_concept_vocabulary, target_concept_id, concept_mappings

Recommended missing (29): bias_correction_applied, data_completeness_pct, exposure_model_cross_validation_r2, health_layer_link_field, health_layer_linkage, health_layer_target, input_file_sha256, input_row_count, lag_alignment_applied, missing_data_handling_method, model_aggregate_uncertainty, native_units_ucum, null_semantics_column, partial_day_attribution_rule, per_value_uncertainty_type, per_value_uncertainty_units_ucum, privacy_transformation, privacy_transformation_note, source_citation_apa, source_dataset_spatial_extent, source_dataset_temporal_coverage, spatial_aggregation_preserves, spatial_extent_bbox, subject_column, target_concept_id, target_concept_vocabulary, time_column, uncertainty, value_uncertainty_column

Optional missing (35): chain_compatibility_assertions, clinical_date_assignment_convention, cohort_size_anchored, concept_mappings, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, exposure_model_ensemble_member_count, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, variable_column, variable_key

Source: examples/scenarios/heat_index/heat_index_input_a_tmax_daymet.yaml

# Heat Index demo — input A: the dry-bulb air-temperature parent sidecar.
# Daymet V4, 1 km grid, local-midnight day boundary, daily MAXIMUM.
# Referenced by heat_index_derived.yaml via equation_inputs[input_role=air_temperature].
# This is the FINER, local-midnight, max-aggregated input.
---
schema_version: "0.1"
provenance_id: "01HFA7K8R3M6XP-daymet-tmax"

variable_identity:
  variable_name: tmax
  variable_label: "daily maximum air temperature at 2 m"
  standard_name: CF:air_temperature
  concept_status: proposed
  cf_cell_methods: "time: maximum"
  units_ucum: Cel
  units_display: "°C"
  value_data_type: continuous_numeric
  value_range_plausible_min: -50
  value_range_plausible_max: 60

data_layout:
  table_orientation: wide
  value_column: tmax

spatial_reference:
  native_spatial_resolution_m: 1000
  native_spatial_resolution_descriptor: "1 km regular grid"
  crs: "EPSG:4326"
  spatial_extent_descriptor: "CONUS + Hawaii + Puerto Rico"
  extraction_method: inverse_distance_weighted_4_nearest_cells
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: maximum
  temporal_aggregation_window_seconds: 86400
  day_boundary_convention: local_midnight        # <-- diverges from input B (era5 = utc)
  temporal_coverage_start: "1980-01-01"
  temporal_coverage_end: "2024-12-31"
  extraction_window_start: "2022-07-18"
  extraction_window_end: "2022-07-20"
  calendar: daymet_365    # Daymet keeps Feb 29 but drops Dec 31 in leap years — not gregorian

source_dataset:
  source_dataset_name: "Daymet V4 Daily Surface Weather Data"
  source_dataset_short_code: daymet_v4
  source_dataset_doi: "10.3334/ORNLDAAC/2129"
  source_dataset_version: "V4 R1"
  source_producer_institution: "NASA ORNL DAAC"
  source_license_spdx: public-domain-us-gov
  source_native_format: netcdf4_cf
  source_access_url: "https://daymet.ornl.gov/"

exposure_model:
  exposure_model_type: spatial_interpolation
  exposure_model_inputs:
  - "GHCN-Daily station observations"
  exposure_model_paper_doi: "10.3334/ORNLDAAC/2129"
  exposure_model_known_biases:
  - "warm-season warm bias documented in some western US regions"

linkage_method:
  linkage_strategy: point_extraction_at_residence
  geocoding_precision_propagated: range
  geocoding_score_propagated: 0.95
  address_period_alignment: address_history_from_emr

tool_run:
  tool_name: daymet
  tool_version: "1.0.0"
  container_image_repository: "ghcr.io/degauss-org/daymet"
  container_image_digest: "sha256:a8b3c2d1e0f9..."
  run_arguments: '{"variables": "tmax"}'
  run_timestamp_utc: "2026-05-23T14:18:42Z"
  output_file_sha256: "1c2d3e4f5a6b..."
  output_row_count: 459

provenance_chain:
  provenance_chain_terminus_type: raw_source_download
  provenance_chain_steps:
  - tool_name: geocoder
    tool_version: "3.3.0"
    run_timestamp_utc: "2026-05-23T14:02:11Z"

subject: "cohort:phoenix_aki_2022"
phi_status: no_phi
# Illustrative companion data-file row (values live in the batch sidecar, not
# inline — see schema/README.md): date=2022-07-19  value=46.7  unit=Cel

Module	State	Present	Missing slots
(record root)	partial	13/16	uncertainty, health_layer_linkage, deposit_metadata
data_layout	partial	2/10	variable_column, variable_key, subject_column, time_column, native_value_column, value_uncertainty_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	3/7	exposure_model_paper_doi, exposure_model_cross_validation_r2, exposure_model_ensemble_member_count, bias_correction_applied
health_layer_linkage	absent	0/3	health_layer_target, health_layer_link_field, cohort_size_anchored
linkage_method	partial	4/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	partial	2/3	chain_compatibility_assertions
source_dataset	partial	8/14	source_dataset_temporal_coverage, source_dataset_spatial_extent, source_citation_apa, source_citation_bibtex, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	6/10	spatial_extent_bbox, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	full	9/9	—
tool_run	partial	8/14	tool_description, run_duration_seconds, run_environment, input_file_sha256, input_row_count, run_log_excerpt
uncertainty	absent	0/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_data_handling_method, missing_value_sentinel, data_completeness_pct
variable_identity	partial	10/17	native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula, target_concept_vocabulary, target_concept_id, concept_mappings

Recommended missing (30): bias_correction_applied, data_completeness_pct, exposure_model_cross_validation_r2, exposure_model_paper_doi, health_layer_link_field, health_layer_linkage, health_layer_target, input_file_sha256, input_row_count, lag_alignment_applied, missing_data_handling_method, model_aggregate_uncertainty, native_units_ucum, null_semantics_column, partial_day_attribution_rule, per_value_uncertainty_type, per_value_uncertainty_units_ucum, privacy_transformation, privacy_transformation_note, source_citation_apa, source_dataset_spatial_extent, source_dataset_temporal_coverage, spatial_aggregation_preserves, spatial_extent_bbox, subject_column, target_concept_id, target_concept_vocabulary, time_column, uncertainty, value_uncertainty_column

Optional missing (35): chain_compatibility_assertions, clinical_date_assignment_convention, cohort_size_anchored, concept_mappings, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, exposure_model_ensemble_member_count, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, variable_column, variable_key

Source: examples/scenarios/heat_index/heat_index_input_b_rh_era5.yaml

# Heat Index demo — input B: the relative-humidity parent sidecar.
# ERA5 reanalysis, ~31 km (0.25°) grid, UTC day boundary, daily MEAN.
# Referenced by heat_index_derived.yaml via equation_inputs[input_role=relative_humidity].
# This is the COARSER, utc, mean-aggregated input. Every line marked "<-- diverges"
# is a divergence from input A that the single output number would otherwise hide.
---
schema_version: "0.1"
provenance_id: "01HFA7K8R3M6XP-era5-rh"

variable_identity:
  variable_name: rh
  variable_label: "daily mean near-surface relative humidity"
  standard_name: CF:relative_humidity
  concept_status: proposed
  cf_cell_methods: "time: mean"
  units_ucum: "%"
  units_display: "%"
  value_data_type: continuous_numeric
  value_range_plausible_min: 0
  value_range_plausible_max: 100

data_layout:
  table_orientation: wide
  value_column: rh

spatial_reference:
  native_spatial_resolution_m: 31000               # <-- diverges from input A (1000 m)
  native_spatial_resolution_descriptor: "~31 km (0.25°) reanalysis grid"
  crs: "EPSG:4326"
  spatial_extent_descriptor: "global"
  extraction_method: nearest_cell
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: mean                # <-- diverges from input A (maximum)
  temporal_aggregation_window_seconds: 86400
  day_boundary_convention: utc_midnight            # <-- diverges from input A (local_midnight)
  temporal_coverage_start: "1940-01-01"
  temporal_coverage_end: "2024-12-31"
  extraction_window_start: "2022-07-18"
  extraction_window_end: "2022-07-20"
  calendar: gregorian

source_dataset:
  source_dataset_name: "ERA5 hourly data on single levels"
  source_dataset_short_code: era5
  source_dataset_doi: "10.24381/cds.adbb2d47"
  source_dataset_version: "ERA5"
  source_producer_institution: "ECMWF / Copernicus Climate Change Service (C3S)"
  source_license_spdx: "Copernicus-Licence"
  source_native_format: grib1
  source_access_url: "https://cds.climate.copernicus.eu/"

exposure_model:
  exposure_model_type: reanalysis
  exposure_model_inputs:
  - "ECMWF IFS 4D-Var assimilation of multi-source observations"
  exposure_model_known_biases:
  - "near-surface humidity biased in arid regions"
  - "coarse grid smooths sub-grid humidity gradients"

linkage_method:
  linkage_strategy: point_extraction_at_residence
  geocoding_precision_propagated: range
  geocoding_score_propagated: 0.95
  address_period_alignment: address_history_from_emr

tool_run:
  tool_name: era5_extract
  tool_version: "0.4.2"
  container_image_repository: "ghcr.io/envar-org/era5-extract"
  container_image_digest: "sha256:f4e3d2c1b0a9..."
  run_arguments: '{"variable": "relative_humidity", "statistic": "daily_mean"}'
  run_timestamp_utc: "2026-05-23T14:21:09Z"
  output_file_sha256: "7a6b5c4d3e2f..."
  output_row_count: 459

provenance_chain:
  provenance_chain_terminus_type: raw_source_download
  provenance_chain_steps:
  - tool_name: geocoder
    tool_version: "3.3.0"
    run_timestamp_utc: "2026-05-23T14:02:11Z"

subject: "cohort:phoenix_aki_2022"
# Illustrative companion data-file row (values live in the batch sidecar, not
# inline — see schema/README.md): date=2022-07-19  value=18.0  unit=%
phi_status: no_phi

Module	State	Present	Missing slots
(record root)	partial	14/17	uncertainty, health_layer_linkage, deposit_metadata
data_layout	partial	2/10	variable_column, variable_key, subject_column, time_column, native_value_column, value_uncertainty_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
derived_heat_metric	partial	8/18	wind_speed_measurement_height_m, solar_radiation_basis, heat_wave_threshold_definition, heat_wave_threshold_specifier, heat_wave_min_consecutive_days, percentile_reference_period_start, percentile_reference_period_end, percentile_reference_geographic_scope, percentile_reference_seasonal_window, metric_temporal_aggregation_rule
exposure_model	partial	3/7	exposure_model_paper_doi, exposure_model_cross_validation_r2, exposure_model_ensemble_member_count, bias_correction_applied
health_layer_linkage	absent	0/3	health_layer_target, health_layer_link_field, cohort_size_anchored
linkage_method	partial	4/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	partial	2/3	chain_compatibility_assertions
source_dataset	partial	6/14	source_dataset_doi, source_dataset_temporal_coverage, source_dataset_spatial_extent, source_citation_apa, source_citation_bibtex, source_access_url, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	6/10	spatial_extent_bbox, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	partial	7/9	temporal_coverage_start, temporal_coverage_end
tool_run	partial	8/14	tool_description, run_duration_seconds, run_environment, input_file_sha256, input_row_count, run_log_excerpt
uncertainty	absent	0/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_data_handling_method, missing_value_sentinel, data_completeness_pct
variable_identity	partial	10/17	native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula, target_concept_vocabulary, target_concept_id, concept_mappings

Recommended missing (39): bias_correction_applied, data_completeness_pct, exposure_model_cross_validation_r2, exposure_model_paper_doi, health_layer_link_field, health_layer_linkage, health_layer_target, input_file_sha256, input_row_count, lag_alignment_applied, metric_temporal_aggregation_rule, missing_data_handling_method, model_aggregate_uncertainty, native_units_ucum, null_semantics_column, partial_day_attribution_rule, per_value_uncertainty_type, per_value_uncertainty_units_ucum, percentile_reference_geographic_scope, percentile_reference_seasonal_window, privacy_transformation, privacy_transformation_note, solar_radiation_basis, source_access_url, source_citation_apa, source_dataset_doi, source_dataset_spatial_extent, source_dataset_temporal_coverage, spatial_aggregation_preserves, spatial_extent_bbox, subject_column, target_concept_id, target_concept_vocabulary, temporal_coverage_end, temporal_coverage_start, time_column, uncertainty, value_uncertainty_column, wind_speed_measurement_height_m

Optional missing (40): chain_compatibility_assertions, clinical_date_assignment_convention, cohort_size_anchored, concept_mappings, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, exposure_model_ensemble_member_count, extraction_buffer_m, heat_wave_min_consecutive_days, heat_wave_threshold_definition, heat_wave_threshold_specifier, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, percentile_reference_period_end, percentile_reference_period_start, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, variable_column, variable_key

Source: examples/scenarios/heat_index/heat_index_derived.yaml

# Heat Index demo — the DERIVED metric sidecar (Option B decomposition).
#
# Heat Index (Rothfusz/NWS) computed from TWO physical-state inputs that come
# from DIFFERENT products and diverge in resolution, day-boundary convention,
# and temporal aggregation:
#
#   input A  air_temperature   daymet_v4  1 km    local_midnight  maximum
#   input B  relative_humidity era5       ~31 km  utc             mean
#
# Under Option B the two inputs are NOT inlined as light descriptors; each is a
# full upstream sidecar (heat_index_input_a_*.yaml, heat_index_input_b_*.yaml),
# referenced below by provenance_id through `equation_inputs` and listed as a
# step in `provenance_chain`. The divergence then stays explicit and a
# completeness checker can WARN on it instead of it vanishing into "HI = 44 °C".
---
schema_version: "0.1"
provenance_id: "01HFA7K8R3M6XP-heatindex"

variable_identity:
  variable_name: heat_index
  variable_label: "daily maximum NWS Heat Index"
  standard_name: ENVAR:heat_index   # local registry term — CF defines no Heat Index standard name
  concept_status: proposed
  cf_cell_methods: "time: maximum"
  units_ucum: Cel
  units_display: "°C"
  value_data_type: continuous_numeric
  value_range_plausible_min: -50
  value_range_plausible_max: 80

data_layout:
  table_orientation: wide
  value_column: heat_index

spatial_reference:
  # Resolution INHERITED from the coarser input (era5, ~31 km), not the 1 km TMAX.
  native_spatial_resolution_m: 31000
  native_spatial_resolution_descriptor: >-
    effective ~31 km — limited by the coarser relative-humidity input (era5);
    see equation_inputs and the per-input sidecars
  crs: "EPSG:4326"
  spatial_extent_descriptor: "Phoenix metro"
  extraction_method: nearest_cell
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: maximum
  temporal_aggregation_window_seconds: 86400
  # The two inputs disagree on the day boundary (local_midnight vs utc); this
  # record carries the air-temperature convention but the mismatch is real and
  # is recorded via the decomposed input sidecars rather than hidden here.
  day_boundary_convention: local_midnight
  extraction_window_start: "2022-07-18"
  extraction_window_end: "2022-07-20"
  calendar: gregorian

source_dataset:
  # The derived metric is itself a new sidecar; its "source" is the derivation,
  # with the true upstream products carried by the referenced input sidecars.
  source_dataset_name: "EnVar-derived NWS Heat Index"
  source_dataset_short_code: envar_heat_index
  source_dataset_version: "0.1"
  source_producer_institution: "EnVar pipeline"
  source_license_spdx: Apache-2.0
  source_native_format: parquet

exposure_model:
  exposure_model_type: equation_derived
  exposure_model_inputs:
  - "air_temperature (see equation_inputs / provenance_id 01HFA7K8R3M6XP-daymet-tmax)"
  - "relative_humidity (see equation_inputs / provenance_id 01HFA7K8R3M6XP-era5-rh)"
  exposure_model_known_biases:
  - "inherits the coarser ~31 km humidity resolution"
  - "inputs use different day-boundary conventions (local_midnight vs utc)"

derived_heat_metric:
  heat_metric_family: heat_index
  equation_variant: rothfusz_1990_nws
  indoor_outdoor: outdoor
  equation_validity_range: '{"min_temperature_F": 80, "min_relative_humidity_pct": 40}'
  equation_inputs:
  - input_role: air_temperature
    input_provenance_id: "01HFA7K8R3M6XP-daymet-tmax"
    input_source_short_code: daymet_v4
  - input_role: relative_humidity
    input_provenance_id: "01HFA7K8R3M6XP-era5-rh"
    input_source_short_code: era5

linkage_method:
  linkage_strategy: point_extraction_at_residence
  geocoding_precision_propagated: range
  geocoding_score_propagated: 0.95
  address_period_alignment: address_history_from_emr

tool_run:
  tool_name: envar_heat_index
  tool_version: "0.1.0"
  container_image_repository: "ghcr.io/envar-org/heat-index"
  container_image_digest: "sha256:c1d2e3f4a5b6..."
  run_arguments: '{"equation": "rothfusz_1990_nws", "indoor_outdoor": "outdoor"}'
  run_timestamp_utc: "2026-05-23T14:25:30Z"
  output_file_sha256: "2b3c4d5e6f7a..."
  output_row_count: 459

# Both upstream derivations are steps in the chain — this is the B linkage that
# equation_inputs indexes into. The chain terminates once per parent product.
provenance_chain:
  provenance_chain_terminus_type: raw_source_download
  provenance_chain_steps:
  - tool_name: daymet
    tool_version: "1.0.0"
    run_timestamp_utc: "2026-05-23T14:18:42Z"
    output_file_sha256: "1c2d3e4f5a6b..."
  - tool_name: era5_extract
    tool_version: "0.4.2"
    run_timestamp_utc: "2026-05-23T14:21:09Z"
    output_file_sha256: "7a6b5c4d3e2f..."

subject: "cohort:phoenix_aki_2022"
phi_status: no_phi
# Illustrative companion data-file row (values live in the batch sidecar, not
# inline — see schema/README.md): date=2022-07-19  value=44.0  unit=Cel

BLOCKING (Core missing): concept_status, value_data_type

2 validation problem(s)

• 'concept_status' is a required property in /variable_identity
• 'value_data_type' is a required property in /variable_identity

Module	State	Present	Missing slots
(record root)	partial	14/16	health_layer_linkage, deposit_metadata
data_layout	partial	5/10	variable_column, variable_key, value_uncertainty_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	2/7	exposure_model_paper_doi, exposure_model_cross_validation_r2, exposure_model_known_biases, exposure_model_ensemble_member_count, bias_correction_applied
health_layer_linkage	absent	0/3	health_layer_target, health_layer_link_field, cohort_size_anchored
linkage_method	partial	3/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, geocoding_score_propagated, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	partial	1/3	provenance_chain_steps, chain_compatibility_assertions
source_dataset	partial	8/14	source_dataset_temporal_coverage, source_dataset_spatial_extent, source_citation_apa, source_citation_bibtex, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	4/10	native_spatial_resolution_descriptor, spatial_extent_bbox, spatial_extent_descriptor, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	partial	6/9	temporal_aggregation_window_seconds, temporal_coverage_start, temporal_coverage_end
tool_run	partial	10/14	tool_description, run_duration_seconds, run_environment, run_log_excerpt
uncertainty	partial	1/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_data_handling_method, data_completeness_pct
variable_identity	partial	8/17	variable_label, units_display, target_concept_vocabulary, target_concept_id, concept_status, concept_mappings, value_data_type, value_range_plausible_min, value_range_plausible_max

Core missing (2): concept_status, value_data_type

Recommended missing (35): bias_correction_applied, data_completeness_pct, exposure_model_cross_validation_r2, exposure_model_known_biases, exposure_model_paper_doi, geocoding_score_propagated, health_layer_link_field, health_layer_linkage, health_layer_target, lag_alignment_applied, missing_data_handling_method, model_aggregate_uncertainty, native_spatial_resolution_descriptor, null_semantics_column, partial_day_attribution_rule, per_value_uncertainty_type, per_value_uncertainty_units_ucum, privacy_transformation, privacy_transformation_note, provenance_chain_steps, source_citation_apa, source_dataset_spatial_extent, source_dataset_temporal_coverage, spatial_aggregation_preserves, spatial_extent_bbox, spatial_extent_descriptor, target_concept_id, target_concept_vocabulary, temporal_aggregation_window_seconds, temporal_coverage_end, temporal_coverage_start, value_range_plausible_max, value_range_plausible_min, value_uncertainty_column, variable_label

Optional missing (31): chain_compatibility_assertions, clinical_date_assignment_convention, cohort_size_anchored, concept_mappings, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, exposure_model_ensemble_member_count, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, units_display, variable_column, variable_key

Source: examples/scenarios/standards/amadeus_gridmet_tmmx.yaml

# Amadeus → gridMET 4 km TMAX — EnVar translation of a REAL pipeline run.
#
# Translated from ~/ws/projects/EnVar/examples/heat/amadeus/outputs/envar/
# gridmet_tmmx.provenance.yaml (emitted 2026-06-25 by the amadeus 2.0.0 R
# package running inside the envar-amadeus:4.4 container; translated
# 2026-07-03). Field-for-field mapping of what the pipeline actually emitted —
# slots the pipeline does not supply are OMITTED, not papered over, so the
# completeness checker shows Amadeus's true coverage. Translator-added
# envelope only: schema_version, subject, phi_status, and data_layout (which
# describes the pipeline's own output CSV, outputs/gridmet_tmmx.csv).
#
# Note on value_data_type: the run's THREDDS header capture
# (outputs/gridmet_tmmx.cf_metadata.json) records the storage dtype (packed
# short → Kelvin via scale/offset) and no CF flag_values/flag_meanings —
# which is how CF expresses "continuous numeric" implicitly. A translator
# COULD derive value_data_type: continuous_numeric from that, but Amadeus
# declares no semantic data type, so under the strict emitted-only policy
# the slot stays absent here. Contrast omop_gaia_daymet_tmax.yaml, whose
# catalog layer declares it explicitly.
schema_version: "0.1"
provenance_id: "SH16BKV29EX1K6462TF5RHFJFM-gridmet"
subject: "cohort:envar_heat_demo_2022"
phi_status: no_phi

variable_identity:
  variable_name: tmmx
  standard_name: CF:air_temperature
  cf_cell_methods: "time: maximum"
  units_ucum: Cel
  # Native-unit conversion as documented by the run's THREDDS capture
  # (outputs/gridmet_tmmx.cf_metadata.json: units=K, scale_factor=0.1,
  # add_offset=220.0). Until 2026-07 this lived here as a comment because
  # the schema had no slot for it — the reverse gap survey
  # (docs/reverse-gap-survey.md) added these slots.
  native_units_ucum: K
  native_value_scale_factor: 0.1
  native_value_offset: 220.0
  unit_conversion_formula: "K = stored * 0.1 + 220.0; Cel = K - 273.15"

data_layout:
  table_orientation: wide
  value_column: value_celsius
  # the pipeline's CSV ships the Kelvin twin column alongside value_celsius
  native_value_column: value_kelvin
  subject_column: person_id
  time_column: date

spatial_reference:
  native_spatial_resolution_m: 4000
  crs: "EPSG:4326"
  extraction_method: nearest_cell
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: maximum
  day_boundary_convention: local_midnight
  calendar: gregorian
  extraction_window_start: "2022-07-15"
  extraction_window_end: "2022-07-22"

source_dataset:
  source_dataset_name: "gridMET (METDATA)"
  source_dataset_short_code: gridmet
  source_dataset_doi: "10.1002/joc.3413"
  source_dataset_version: current
  source_producer_institution: "University of Idaho Climatology Lab"
  source_license_spdx: CC0-1.0
  source_native_format: netcdf4_cf
  source_access_url: "https://www.climatologylab.org/gridmet.html"

uncertainty:
  # declared by the run's THREDDS capture (_FillValue / missing_value);
  # slot added by the reverse gap survey (docs/reverse-gap-survey.md)
  missing_value_sentinel: "32767"

exposure_model:
  exposure_model_type: statistical_blend
  exposure_model_inputs:
  - "PRISM monthly normals"
  - "NLDAS-2 sub-daily reanalysis"

linkage_method:
  linkage_strategy: point_extraction_at_residence
  geocoding_precision_propagated: range
  address_period_alignment: address_history_from_emr

tool_run:
  tool_name: amadeus
  tool_version: "2.0.0"
  container_image_repository: envar-amadeus
  container_image_digest: "sha256:339832bf73f9c9e25e28dc40cdab7ce089121df8ce51eac6075dd00db77da3a8"
  run_arguments: >-
    amadeus::calculate_covariates("gridmet", locs = patient_locations,
    variables = "tmmx", date_start = "2022-07-15", date_end = "2022-07-22")
  run_timestamp_utc: "2026-06-25T08:33:31Z"
  input_file_sha256: "12cb1bca74dde87d45cabf09ef0af7d13e08589629a75ed15d5ae727470f7fb6"
  input_row_count: 3
  output_file_sha256: "6677711bb8698788a939bf39772e52f182a4e70d331c472ffef19e64f28f4919"
  output_row_count: 24

# The source sidecar's provenance_chain was empty: the amadeus run itself
# downloads the raw GridMET NetCDF from THREDDS.
provenance_chain:
  provenance_chain_terminus_type: raw_source_download

BLOCKING (Core missing): concept_status, value_data_type

2 validation problem(s)

• 'concept_status' is a required property in /variable_identity
• 'value_data_type' is a required property in /variable_identity

Module	State	Present	Missing slots
(record root)	partial	13/16	uncertainty, health_layer_linkage, deposit_metadata
data_layout	partial	4/10	variable_column, variable_key, native_value_column, value_uncertainty_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	2/7	exposure_model_paper_doi, exposure_model_cross_validation_r2, exposure_model_known_biases, exposure_model_ensemble_member_count, bias_correction_applied
health_layer_linkage	absent	0/3	health_layer_target, health_layer_link_field, cohort_size_anchored
linkage_method	partial	3/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, geocoding_score_propagated, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	partial	2/3	chain_compatibility_assertions
source_dataset	partial	8/14	source_dataset_temporal_coverage, source_dataset_spatial_extent, source_citation_apa, source_citation_bibtex, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	4/10	native_spatial_resolution_descriptor, spatial_extent_bbox, spatial_extent_descriptor, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	partial	6/9	temporal_aggregation_window_seconds, temporal_coverage_start, temporal_coverage_end
tool_run	partial	9/14	tool_description, run_arguments, run_duration_seconds, run_environment, run_log_excerpt
uncertainty	absent	0/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_data_handling_method, missing_value_sentinel, data_completeness_pct
variable_identity	partial	4/17	variable_label, units_display, native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula, target_concept_vocabulary, target_concept_id, concept_status, concept_mappings, value_data_type, value_range_plausible_min, value_range_plausible_max

Core missing (2): concept_status, value_data_type

Recommended missing (37): bias_correction_applied, data_completeness_pct, exposure_model_cross_validation_r2, exposure_model_known_biases, exposure_model_paper_doi, geocoding_score_propagated, health_layer_link_field, health_layer_linkage, health_layer_target, lag_alignment_applied, missing_data_handling_method, model_aggregate_uncertainty, native_spatial_resolution_descriptor, native_units_ucum, null_semantics_column, partial_day_attribution_rule, per_value_uncertainty_type, per_value_uncertainty_units_ucum, privacy_transformation, privacy_transformation_note, run_arguments, source_citation_apa, source_dataset_spatial_extent, source_dataset_temporal_coverage, spatial_aggregation_preserves, spatial_extent_bbox, spatial_extent_descriptor, target_concept_id, target_concept_vocabulary, temporal_aggregation_window_seconds, temporal_coverage_end, temporal_coverage_start, uncertainty, value_range_plausible_max, value_range_plausible_min, value_uncertainty_column, variable_label

Optional missing (36): chain_compatibility_assertions, clinical_date_assignment_convention, cohort_size_anchored, concept_mappings, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, exposure_model_ensemble_member_count, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, units_display, variable_column, variable_key

Source: examples/scenarios/standards/degauss_daymet_tmax.yaml

# DeGAUSS → Daymet 1 km TMAX — EnVar translation of a REAL pipeline run.
#
# Translated from ~/ws/projects/EnVar/examples/heat/degauss/outputs/envar/
# cohort_addresses_geocoded_daymet.provenance.json (emitted 2026-06-25 by the
# ghcr.io/degauss-org/daymet:1.0.0 container, geocoding via
# ghcr.io/degauss-org/geocoder:3.3.0; translated 2026-07-03). Field-for-field
# mapping of what the pipeline actually emitted — slots the pipeline does not
# supply are OMITTED so the completeness checker shows DeGAUSS's true
# coverage. Translator-added envelope only: schema_version, subject,
# phi_status, and data_layout (describing the pipeline's own output CSV,
# outputs/cohort_addresses_geocoded_daymet.csv). Note the chain: the source
# sidecar carries the geocoder step as a full nested sidecar (its own
# source_dataset and linkage); the schema's provenance_chain_steps keep only
# its ToolRun portion.
schema_version: "0.1"
provenance_id: "01KVYYF39VGAXAG0DMRCHHGAJA-daymet"
subject: "cohort:envar_heat_demo_2022"
phi_status: no_phi

variable_identity:
  variable_name: tmax
  standard_name: CF:air_temperature
  cf_cell_methods: "time: maximum"
  units_ucum: Cel

data_layout:
  table_orientation: wide
  value_column: tmax
  subject_column: person_id
  time_column: date

spatial_reference:
  native_spatial_resolution_m: 1000
  crs: "EPSG:4326"
  extraction_method: inverse_distance_weighted_4_nearest_cells
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: maximum
  day_boundary_convention: local_midnight
  calendar: daymet_365    # Daymet keeps Feb 29 but drops Dec 31 in leap years — not gregorian
  extraction_window_start: "2022-07-15"
  extraction_window_end: "2022-07-22"

source_dataset:
  source_dataset_name: "Daymet V4 Daily Surface Weather Data"
  source_dataset_short_code: daymet_v4
  source_dataset_doi: "10.3334/ORNLDAAC/2129"
  source_dataset_version: "V4 R1"
  source_producer_institution: "NASA ORNL DAAC"
  source_license_spdx: public-domain-us-gov
  source_native_format: netcdf4_cf
  source_access_url: "https://daymet.ornl.gov/"

exposure_model:
  exposure_model_type: spatial_interpolation
  exposure_model_inputs:
  - "GHCN-Daily station observations"

linkage_method:
  linkage_strategy: point_extraction_at_residence
  geocoding_precision_propagated: range
  address_period_alignment: address_history_from_emr

tool_run:
  tool_name: daymet
  tool_version: "1.0.0"
  container_image_repository: "ghcr.io/degauss-org/daymet"
  container_image_digest: "sha256:bfe282259823b7fa92ea9b41e77b51defe455d704a8b6a142c0fe5f58c78cc72"
  run_timestamp_utc: "2026-06-25T08:31:11Z"
  input_file_sha256: "fa4b4684edaab06f452eb538108650744bd3b28aee28a37b1ac49fdad1488578"
  input_row_count: 3
  output_file_sha256: "8093b669a977013b00541f7f2564bed826e4746520c3ff20267435259a3afcc9"
  output_row_count: 24

provenance_chain:
  provenance_chain_terminus_type: raw_source_download
  provenance_chain_steps:
  - tool_name: geocoder
    tool_version: "3.3.0"
    container_image_repository: "ghcr.io/degauss-org/geocoder"
    container_image_digest: "sha256:ec9b75eff7cd7432efcc84d3e7d55b593cc06e0cd2868b512dbc70ef99a1fdc6"
    run_timestamp_utc: "2026-06-25T08:31:11Z"
    input_file_sha256: "b285ec7e176006b0d6f107378099ef8be707b249b56753faa35e92d82bdb6e99"
    input_row_count: 3
    output_file_sha256: "3a4ec454a15a88ec654a888ea7266f365768994bca2f06e562cbface2ceb5ba7"
    output_row_count: 3

Module	State	Present	Missing slots
(record root)	partial	14/16	uncertainty, deposit_metadata
data_layout	partial	4/10	variable_column, variable_key, native_value_column, value_uncertainty_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	2/7	exposure_model_paper_doi, exposure_model_cross_validation_r2, exposure_model_known_biases, exposure_model_ensemble_member_count, bias_correction_applied
health_layer_linkage	partial	2/3	cohort_size_anchored
linkage_method	partial	3/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, geocoding_score_propagated, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	partial	2/3	chain_compatibility_assertions
source_dataset	partial	9/14	source_dataset_temporal_coverage, source_citation_apa, source_citation_bibtex, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	5/10	native_spatial_resolution_descriptor, spatial_extent_bbox, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	partial	8/9	temporal_aggregation_window_seconds
tool_run	partial	9/14	tool_description, run_duration_seconds, run_environment, output_file_sha256, run_log_excerpt
uncertainty	absent	0/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_data_handling_method, missing_value_sentinel, data_completeness_pct
variable_identity	partial	12/17	units_display, native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula

Recommended missing (25): bias_correction_applied, data_completeness_pct, exposure_model_cross_validation_r2, exposure_model_known_biases, exposure_model_paper_doi, geocoding_score_propagated, lag_alignment_applied, missing_data_handling_method, model_aggregate_uncertainty, native_spatial_resolution_descriptor, native_units_ucum, null_semantics_column, output_file_sha256, partial_day_attribution_rule, per_value_uncertainty_type, per_value_uncertainty_units_ucum, privacy_transformation, privacy_transformation_note, source_citation_apa, source_dataset_temporal_coverage, spatial_aggregation_preserves, spatial_extent_bbox, temporal_aggregation_window_seconds, uncertainty, value_uncertainty_column

Optional missing (35): chain_compatibility_assertions, clinical_date_assignment_convention, cohort_size_anchored, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, exposure_model_ensemble_member_count, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, units_display, variable_column, variable_key

Source: examples/scenarios/standards/omop_gaia_daymet_tmax.yaml

# GAIA-OMOP → Daymet single-pixel TMAX — EnVar translation of a REAL run.
#
# Translated from ~/ws/projects/EnVar/examples/heat/omop-gaia/outputs/envar/
# daymet.provenance.json + geocoder.provenance.json + MANIFEST.json AND the
# native metadata layer outputs/gaia_catalog/meta_{json-ld,etl,dcat}_
# daymet_tmax.json — the three OHDSI GIS Working Group files the MANIFEST
# lists as fed into gaia-db's backbone.load_jsonld_file() (run emitted
# 2026-06-25 by the real gaia-db container pipeline: DeGAUSS geocoder →
# Daymet single-pixel API → working.envar_spatial_join_perday →
# external_exposure.csv; translated 2026-07-04). Field-for-field mapping of
# what the pipeline actually emitted — omissions are real gaps. This is the
# only pipeline of the three that emits a health-layer concept binding:
# external_exposure.exposure_concept_id carries the proposed concept and
# exposure_source_value carries this sidecar's provenance_id, so
# target_concept_*/concept_status and health_layer_linkage are source-emitted
# here, not translator inventions. The GAIA catalog layer additionally
# supplies (human-authored at dataset-registration time — the format demands
# them): qudt:dataType numeric + float4 → value_data_type; the attribute
# string's label, −50…60 plausible range and 2018–2022 registered coverage;
# the POLYGON extent; the NERC standard-name propertyID. Translator-added
# envelope only: schema_version, subject, phi_status, and data_layout
# (describing the pipeline's own OMOP export, outputs/external_exposure.csv).
# The Daymet single-pixel API returns the value of the 1 km cell containing
# the point, mapped to extraction_method: nearest_cell.
schema_version: "0.1"
provenance_id: "NWWRFHEMRXQZ4WNHBPKJKKM6YS-omop-gaia-daymet"
subject: "cohort:envar_heat_demo_2022"
phi_status: no_phi

variable_identity:
  variable_name: tmax
  variable_label: "Daily maximum 2m air temperature"
  standard_name: CF:air_temperature
  cf_cell_methods: "time: maximum"
  units_ucum: Cel
  value_data_type: continuous_numeric   # gaia_catalog: qudt:dataType numeric, float4
  value_range_plausible_min: -50
  value_range_plausible_max: 60
  target_concept_vocabulary: omop
  target_concept_id: "proposed:daily-max-air-temperature"
  concept_status: proposed
  concept_mappings:
  - "http://vocab.nerc.ac.uk/standard_name/air_temperature/"

data_layout:
  table_orientation: wide
  value_column: value_as_number
  subject_column: person_id
  time_column: exposure_start_date

spatial_reference:
  native_spatial_resolution_m: 1000
  crs: "EPSG:4326"
  spatial_extent_descriptor: "North America"   # gaia_catalog json-ld spatialCoverage
  extraction_method: nearest_cell
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: maximum
  day_boundary_convention: local_midnight
  calendar: daymet_365    # Daymet keeps Feb 29 but drops Dec 31 in leap years — not gregorian
  # registered coverage of the catalog entry (gaia_catalog etl attribute
  # string), narrower than Daymet's full 1980– archive
  temporal_coverage_start: "2018-01-01"
  temporal_coverage_end: "2022-12-31"
  extraction_window_start: "2022-07-15"
  extraction_window_end: "2022-07-22"

source_dataset:
  source_dataset_name: "Daymet V4 Daily Surface Weather Data"
  source_dataset_short_code: daymet_v4
  source_dataset_doi: "10.3334/ORNLDAAC/2129"
  source_dataset_version: "V4 R1"
  source_producer_institution: "NASA ORNL DAAC"
  source_license_spdx: public-domain-us-gov
  source_native_format: netcdf4_cf
  source_access_url: "https://daymet.ornl.gov/single-pixel/"
  source_dataset_spatial_extent: "POLYGON((-178 14, -52 14, -52 83, -178 83, -178 14))"

exposure_model:
  exposure_model_type: spatial_interpolation
  exposure_model_inputs:
  - "GHCN-Daily station observations"

linkage_method:
  linkage_strategy: point_extraction_at_residence
  geocoding_precision_propagated: unknown
  address_period_alignment: address_history_from_emr

tool_run:
  tool_name: daymet-singlepixel
  tool_version: "v4-r1"
  run_arguments: >-
    GET https://daymet.ornl.gov/single-pixel/api/data (3 requests,
    1.5 s delay); spatial join via working.envar_spatial_join_perday
    inside the gaia-db:envar-heat container
  run_timestamp_utc: "2026-06-25T08:35:40Z"
  input_file_sha256: "425508d90c2fb841e768a91a64249c01b49c747d3a0237ac566ac52a38f20be4"
  input_row_count: 3
  output_row_count: 24

provenance_chain:
  provenance_chain_terminus_type: raw_source_download
  provenance_chain_steps:
  - tool_name: geocoder
    tool_version: "3.3.0"
    container_image_repository: "ghcr.io/degauss-org/geocoder"
    container_image_digest: "sha256:ec9b75eff7cd7432efcc84d3e7d55b593cc06e0cd2868b512dbc70ef99a1fdc6"
    run_timestamp_utc: "2026-06-25T08:35:40Z"
    input_file_sha256: "36d1124609b3c9f49229c5992e8faa954d625196e62f9909ec6cc4914187a820"
    input_row_count: 3
    output_row_count: 3

health_layer_linkage:
  health_layer_target: omop_external_exposure
  health_layer_link_field: exposure_source_value

BLOCKING (Core missing): day_boundary_convention, linkage_method, linkage_strategy, source_dataset_version

6 validation problem(s)

• Additional properties are not allowed ('day_boundary_convention_missing_reason' was unexpected) in /temporal_reference
• None is not of type 'string' in /temporal_reference/day_boundary_convention
• None is not one of ['local_midnight', 'utc_midnight', 'ending_1200_gmt', 'solar_noon_centered', 'observation_dependent', 'not_applicable'] in /temporal_reference/day_boundary_convention
• Additional properties are not allowed ('source_acknowledgement_freetext', 'source_dataset_version_missing_reason' were unexpected) in /source_dataset
• None is not of type 'string' in /source_dataset/source_dataset_version
• 'linkage_method' is a required property in /

Module	State	Present	Missing slots
(record root)	partial	12/16	uncertainty, provenance_chain, linkage_method, deposit_metadata
data_layout	partial	2/10	variable_column, variable_key, subject_column, time_column, native_value_column, value_uncertainty_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	1/7	exposure_model_inputs, exposure_model_paper_doi, exposure_model_cross_validation_r2, exposure_model_known_biases, exposure_model_ensemble_member_count, bias_correction_applied
health_layer_linkage	partial	1/3	health_layer_link_field, cohort_size_anchored
linkage_method	absent	0/14	linkage_strategy, linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, geocoding_precision_propagated, geocoding_score_propagated, address_period_alignment, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	absent	0/3	provenance_chain_steps, provenance_chain_terminus_type, chain_compatibility_assertions
source_dataset	partial	2/14	source_dataset_doi, source_dataset_version, source_dataset_temporal_coverage, source_dataset_spatial_extent, source_producer_institution, source_citation_apa, source_citation_bibtex, source_license_spdx, source_access_url, source_native_format, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	5/10	spatial_extent_bbox, spatial_extent_descriptor, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	partial	2/9	temporal_aggregation_window_seconds, day_boundary_convention, temporal_coverage_start, temporal_coverage_end, extraction_window_start, extraction_window_end, calendar
tool_run	partial	4/14	tool_description, container_image_repository, container_image_digest, run_arguments, run_timestamp_utc, run_duration_seconds, run_environment, input_row_count, output_row_count, run_log_excerpt
uncertainty	absent	0/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_data_handling_method, missing_value_sentinel, data_completeness_pct
variable_identity	partial	9/17	units_display, native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula, concept_mappings, value_range_plausible_min, value_range_plausible_max

Core missing (4): day_boundary_convention, linkage_method, linkage_strategy, source_dataset_version

Recommended missing (52): address_period_alignment, bias_correction_applied, calendar, container_image_digest, container_image_repository, data_completeness_pct, exposure_model_cross_validation_r2, exposure_model_inputs, exposure_model_known_biases, exposure_model_paper_doi, extraction_window_end, extraction_window_start, geocoding_precision_propagated, geocoding_score_propagated, health_layer_link_field, input_row_count, lag_alignment_applied, missing_data_handling_method, model_aggregate_uncertainty, native_units_ucum, null_semantics_column, output_row_count, partial_day_attribution_rule, per_value_uncertainty_type, per_value_uncertainty_units_ucum, privacy_transformation, privacy_transformation_note, provenance_chain, provenance_chain_steps, provenance_chain_terminus_type, run_arguments, run_timestamp_utc, source_access_url, source_citation_apa, source_dataset_doi, source_dataset_spatial_extent, source_dataset_temporal_coverage, source_license_spdx, source_native_format, source_producer_institution, spatial_aggregation_preserves, spatial_extent_bbox, spatial_extent_descriptor, subject_column, temporal_aggregation_window_seconds, temporal_coverage_end, temporal_coverage_start, time_column, uncertainty, value_range_plausible_max, value_range_plausible_min, value_uncertainty_column

Optional missing (36): chain_compatibility_assertions, clinical_date_assignment_convention, cohort_size_anchored, concept_mappings, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, exposure_model_ensemble_member_count, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_max_distance_to_station_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, units_display, variable_column, variable_key

Explained nulls (absent, but documented with a *_missing_reason — counted as present): target_concept_id

Source: tests/data/invalid/EnvironmentalExposureRecord-tmax_core_missing.yaml

schema_version: "0.1"
provenance_id: "01HXAMADEUS0000000000GRIDMET"

variable_identity:
  variable_name: tmmx                      # GridMET's native column name
  variable_label: "daily maximum near-surface air temperature"
  standard_name: CF:air_temperature
  cf_cell_methods: "time: maximum"
  units_ucum: Cel
  value_data_type: continuous_numeric
  target_concept_vocabulary: omop
  target_concept_id:
  target_concept_id_missing_reason: not_provided_by_source
  concept_status: gap

data_layout:
  table_orientation: wide
  value_column: tmmx

spatial_reference:
  native_spatial_resolution_m: 4000
  native_spatial_resolution_descriptor: "~4 km regular grid"
  crs: "EPSG:4326"
  extraction_method: nearest_cell
  target_geography_type: point_residence

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: maximum
  # CORE GAP: GridMET blends UTC-referenced NLDAS-2 with PRISM normals; the
  # Amadeus output does not record which day-boundary convention applies.
  day_boundary_convention:
  day_boundary_convention_missing_reason: not_provided_by_source

source_dataset:
  source_dataset_name: "GridMET (University of Idaho gridded surface meteorology)"
  source_dataset_short_code: gridmet
  # CORE GAP: version not surfaced by the Amadeus acknowledgement string.
  source_dataset_version:
  source_dataset_version_missing_reason: not_provided_by_source
  source_acknowledgement_freetext: >-
    Data provided by the University of Idaho; GridMET via Amadeus.

exposure_model:
  exposure_model_type: statistical_blend

tool_run:
  tool_name: amadeus
  tool_version: "1.3.2"
  input_file_sha256: "3a1b9c..."
  output_file_sha256: "7f2e4d..."

health_layer_linkage:
  health_layer_target: omop_external_exposure
subject: "cohort:demo_min"
# Companion data row (in the accompanying CSV/parquet, not the sidecar):
#   date: "2022-07-19"  value: 45.1  unit: Cel
phi_status: no_phi

BLOCKING (Core missing): day_boundary_convention, linkage_max_distance_to_station_m, native_spatial_resolution_m, source_dataset_version

6 validation problem(s)

• 'native_spatial_resolution_m' is a required property in /spatial_reference
• Additional properties are not allowed ('day_boundary_convention_missing_reason' was unexpected) in /temporal_reference
• None is not of type 'string' in /temporal_reference/day_boundary_convention
• None is not one of ['local_midnight', 'utc_midnight', 'ending_1200_gmt', 'solar_noon_centered', 'observation_dependent', 'not_applicable'] in /temporal_reference/day_boundary_convention
• 'source_dataset_version' is a required property in /source_dataset
• Additional properties are not allowed ('tool_version_missing_reason' was unexpected) in /tool_run

Module	State	Present	Missing slots
(record root)	partial	13/16	uncertainty, provenance_chain, deposit_metadata
data_layout	partial	2/10	variable_column, variable_key, subject_column, time_column, native_value_column, value_uncertainty_column, quality_flag_column, null_semantics_column
deposit_metadata	absent	0/6	deposit_doi, deposit_repository, deposit_license_spdx, deposit_redistribution_constraints_inherited, recommended_citation, dcat_distribution_url
exposure_model	partial	1/7	exposure_model_inputs, exposure_model_paper_doi, exposure_model_cross_validation_r2, exposure_model_known_biases, exposure_model_ensemble_member_count, bias_correction_applied
health_layer_linkage	partial	1/3	health_layer_link_field, cohort_size_anchored
linkage_method	partial	1/14	linkage_buffer_radius_m, linkage_buffer_aggregation_method, linkage_max_distance_to_station_m, linkage_working_crs, geocoding_precision_propagated, geocoding_score_propagated, address_period_alignment, clinical_date_assignment_convention, partial_day_attribution_rule, lag_alignment_applied, lag_alignment_specifier, privacy_transformation, privacy_transformation_note
provenance_chain	absent	0/3	provenance_chain_steps, provenance_chain_terminus_type, chain_compatibility_assertions
source_dataset	partial	5/14	source_dataset_doi, source_dataset_version, source_dataset_temporal_coverage, source_dataset_spatial_extent, source_citation_apa, source_citation_bibtex, source_native_format, source_homogenisation_status, source_acdd_attributes
spatial_reference	partial	4/10	native_spatial_resolution_m, spatial_extent_bbox, spatial_extent_descriptor, extraction_buffer_m, population_weighting_source, spatial_aggregation_preserves
temporal_reference	partial	2/9	temporal_aggregation_window_seconds, day_boundary_convention, temporal_coverage_start, temporal_coverage_end, extraction_window_start, extraction_window_end, calendar
tool_run	partial	2/14	tool_description, container_image_repository, container_image_digest, run_arguments, run_timestamp_utc, run_duration_seconds, run_environment, input_file_sha256, input_row_count, output_file_sha256, output_row_count, run_log_excerpt
uncertainty	absent	0/7	per_value_uncertainty_type, per_value_uncertainty_units_ucum, model_aggregate_uncertainty, quality_flag_vocabulary, missing_data_handling_method, missing_value_sentinel, data_completeness_pct
variable_identity	partial	9/17	units_display, native_units_ucum, native_value_scale_factor, native_value_offset, unit_conversion_formula, concept_mappings, value_range_plausible_min, value_range_plausible_max

Core missing (4): day_boundary_convention, linkage_max_distance_to_station_m, native_spatial_resolution_m, source_dataset_version

Recommended missing (51): address_period_alignment, bias_correction_applied, calendar, container_image_digest, container_image_repository, data_completeness_pct, exposure_model_cross_validation_r2, exposure_model_inputs, exposure_model_known_biases, exposure_model_paper_doi, extraction_window_end, extraction_window_start, geocoding_precision_propagated, geocoding_score_propagated, health_layer_link_field, input_file_sha256, input_row_count, lag_alignment_applied, missing_data_handling_method, model_aggregate_uncertainty, native_units_ucum, null_semantics_column, output_file_sha256, output_row_count, partial_day_attribution_rule, per_value_uncertainty_type, per_value_uncertainty_units_ucum, privacy_transformation, privacy_transformation_note, provenance_chain, provenance_chain_steps, provenance_chain_terminus_type, run_arguments, run_timestamp_utc, source_citation_apa, source_dataset_doi, source_dataset_spatial_extent, source_dataset_temporal_coverage, source_native_format, spatial_aggregation_preserves, spatial_extent_bbox, spatial_extent_descriptor, subject_column, temporal_aggregation_window_seconds, temporal_coverage_end, temporal_coverage_start, time_column, uncertainty, value_range_plausible_max, value_range_plausible_min, value_uncertainty_column

Optional missing (35): chain_compatibility_assertions, clinical_date_assignment_convention, cohort_size_anchored, concept_mappings, dcat_distribution_url, deposit_doi, deposit_license_spdx, deposit_metadata, deposit_redistribution_constraints_inherited, deposit_repository, exposure_model_ensemble_member_count, extraction_buffer_m, lag_alignment_specifier, linkage_buffer_aggregation_method, linkage_buffer_radius_m, linkage_working_crs, missing_value_sentinel, native_value_column, native_value_offset, native_value_scale_factor, population_weighting_source, quality_flag_column, quality_flag_vocabulary, recommended_citation, run_duration_seconds, run_environment, run_log_excerpt, source_acdd_attributes, source_citation_bibtex, source_homogenisation_status, tool_description, unit_conversion_formula, units_display, variable_column, variable_key

Explained nulls (absent, but documented with a *_missing_reason — counted as present): target_concept_id

Source: tests/data/invalid/EnvironmentalExposureRecord-pm25_core_missing.yaml

schema_version: "0.1"
provenance_id: "01HXEPAAQS00000000000PM25MON"

variable_identity:
  variable_name: pm25
  variable_label: "24-hour mean fine particulate matter (PM2.5) mass concentration"
  standard_name: CF:mass_concentration_of_pm2p5_ambient_aerosol_particles_in_air
  cf_cell_methods: "time: mean"
  units_ucum: ug/m3
  value_data_type: continuous_numeric
  target_concept_vocabulary: omop
  target_concept_id:
  target_concept_id_missing_reason: not_provided_by_source
  concept_status: gap

data_layout:
  table_orientation: wide
  value_column: pm25

spatial_reference:
  native_spatial_resolution_descriptor: "point station (FRM/FEM monitor)"
  crs: "EPSG:4326"
  extraction_method: point_station_lookup
  target_geography_type: point_residence
  # CORE GAP: nearest-station assignment has no documented max distance, so
  # the spatial precision of the assignment is unknown.

temporal_reference:
  temporal_resolution: daily
  temporal_aggregation_method: mean
  # CORE GAP: AQS daily summaries are local-standard-time; not recorded here.
  day_boundary_convention:
  day_boundary_convention_missing_reason: not_provided_by_source

source_dataset:
  source_dataset_name: "US EPA Air Quality System (AQS)"
  source_dataset_short_code: epa_aqs
  source_producer_institution: "US Environmental Protection Agency"
  source_access_url: "https://www.epa.gov/aqs"
  source_license_spdx: public-domain-us-gov

exposure_model:
  exposure_model_type: direct_measurement

linkage_method:
  linkage_strategy: nearest_station_with_max_distance
  # CORE-adjacent GAP: max distance not set, so far-from-monitor patients are
  # silently assigned a possibly-irrelevant value.
  linkage_max_distance_to_station_m:
  linkage_max_distance_to_station_m_missing_reason: not_provided_by_source

tool_run:
  tool_name: epa_aqs_api
  tool_version: "unknown"
  tool_version_missing_reason: not_provided_by_source

health_layer_linkage:
  health_layer_target: omop_external_exposure
subject: "cohort:demo_min_pm"
# Companion data row (in the accompanying CSV/parquet, not the sidecar):
#   date: "2022-07-19"  value: 12.4  unit: ug/m3
phi_status: no_phi