EnVar microschema · class
Linkage Method
LinkageMethod
How a gridded environmental value gets attached to a patient: the resolution of the patient's spatiotemporal trajectory down to the resolution the exposure data supports. Covers the linkage strategy and buffer parameters, the propagated geocoder precision and score, how patient location-over-time is modelled (the spatial axis), and the clinical-date-assignment convention, partial-day attribution, and lag alignment (the temporal axis). One per record.
Where it sits
Composed intoEnvironmentalExposureRecord
Fields
Environmental data comes as a map of values, but health data belongs to people. This slot records the rule used to pick a person's value off that map — for example reading the value exactly at their home, or averaging the values in a circle around it.
How a gridded value is attached to a patient location.
Examples
point_extraction_at_residence — extract the grid-cell value at the geocoded residence (Daymet tmax scenario)
population_weighted_area_to_residence — population-weighted aggregation over the residence tract (ACAG PM2.5 scenario)
Allowed values
point_extraction_at_residence Take the single value at the exact grid cell (or interpolated point) that con...
buffer_aggregation_around_residence Draw a circle of a fixed radius around the residence and summarise every valu...
area_membership_residence_in_polygon Give the patient the value already attached to whichever administrative or se...
nearest_station_with_max_distance Use the reading from the closest monitoring station to the residence, but onl...
population_weighted_area_to_residence Combine the values over an area around the residence, but weight each part of...
Covered by — 5 standards
Why it matters & mappings
The strategy determines which grid cells or stations contribute to a patient's value: point extraction, buffer aggregation, and population weighting can assign materially different exposures to the same address. Without it the person-level value cannot be reproduced or compared across studies — this is the "linkage descriptor" gap named by the GECC/EIRENE forum.
When exposure is averaged over a circle drawn around a person's home, this is how wide that circle is, in metres.
Buffer radius in metres for buffer-aggregation strategies.
Example
500 — 500 m buffer around the geocoded residence
Why it matters & mappings
For buffer strategies the radius defines the exposure footprint: a 500 m and a 5 km buffer around the same residence can average over very different air or heat conditions, so the assigned value is not reproducible without it.
If several map values fall inside the circle around a home, they must be boiled down to one number. This records how — for example by taking the average, or the highest value.
Aggregation method applied within the buffer (mean / max / median / area-weighted mean).
Example
area_weighted_mean — area-weighted mean over the aggregation area (ACAG PM2.5 scenario)
Allowed values
mean Arithmetic mean of values in the buffer
max Maximum value in the buffer
median Median of values in the buffer
area_weighted_mean Area-weighted mean of values in the buffer
Why it matters & mappings
Within the same buffer, mean, max, and area-weighted mean yield different exposure values; omitting the method makes the assigned value irreproducible and cross-study comparisons unsafe.
Some methods take the reading from the closest measuring station. This is the farthest a station may be from the home before the match is considered too unreliable and no value is assigned.
Maximum distance to a station for nearest-station strategies; values beyond this distance get null.
Example
50000 — stations farther than 50 km from the residence yield null
Why it matters & mappings
For nearest-station strategies this cutoff decides whether a distant monitor still counts as "nearby"; beyond it the assignment is meaningless and should be null. Without the cutoff, values assigned from stations tens of kilometres away are indistinguishable from tight matches, silently degrading exposure quality.
A hospital visit at 11 pm can count as "today" or "tomorrow" depending on which clock and cutoff you use. This records the rule the clinical data used to turn a timestamp into a calendar date.
The clinical-side mirror of day_boundary_convention (envar_temporal): which timezone / day-boundary rule collapsed the clinical timestamp to the date used in the join. A boundary mismatch between this and the exposure-side day_boundary_convention silently misattributes boundary-hour events to the wrong day, which is what makes the Core day_boundary_convention checkable at all. Metadata about the join — never the clinical timestamp itself; carries no PHI.
Examples
local_midnight — matches the exposure-side day_boundary_convention (Daymet tmax scenario)
date_only_no_time — clinical record carried only a date, so no boundary rule applies (ACAG PM2.5 scenario)
Allowed values
local_midnight Clinical date assigned at local midnight at the patient location
utc_midnight Clinical date assigned at 00:00 UTC
source_system_local_time Clinical date assigned in the source clinical system's local time, whose offs...
date_only_no_time The clinical record carried only a date (no time of day), so no boundary rule...
unknown The clinical-date-assignment convention is unknown
Why it matters & mappings
If the clinical side collapsed timestamps to dates with a different day-boundary rule than the exposure side, events near midnight are silently joined to the wrong day's exposure; recording both rules is what makes that mismatch detectable at all.
Geocoding means turning a street address into map coordinates, and it does not always land on the exact house — sometimes only on the street, the ZIP area, or the city. This records how exact the landing was.
Quality category propagated from the upstream geocoder (DeGAUSS precision column).
Example
range — street-centerline point interpolated within an address-range segment
Allowed values
range Street-centerline point interpolated within an address-range segment
street Representative point on the matched street segment
intersection Geocoded crossing of two named streets
zip Centroid of the matched 5-digit ZIP code
city City centroid; lowest precision
unknown Precision is unknown
Covered by — 5 standards
Why it matters & mappings
Geocoding precision determines whether "residence" means the actual house or a ZIP-code centroid kilometres away — which changes which grid cell the patient falls in and therefore their assigned exposure. Propagating it lets analysts filter or down-weight coarsely located records.
See also: https://degauss.org/
When software converts an address into map coordinates it also rates its own confidence, from 0 to 1. This carries that rating along with the exposure record.
Geocoder score (0-1) propagated from the upstream geocoder so the exposure record knows the spatial precision of its anchor.
Example
0.95
Covered by — 5 standards
Why it matters & mappings
The score quantifies how confident the geocoder was in its address match; without it downstream analysts cannot apply quality cutoffs, and poorly matched addresses contaminate the exposure assignment invisibly.
See also: https://degauss.org/
People move house and travel, so "where the patient was" changes over time. This records whether the study used one fixed address, a full address history, or accounted for known trips away from home.
How the patient's location-over-time (the spatial axis of trajectory resolution) was modelled.
Example
address_history_from_emr — an EMR-sourced address history covers the observation period
Allowed values
single_static_address A single address is used for the whole observation period
address_history_from_emr An EMR-sourced address history is used
known_travel_interval A documented trip away from the residence is accounted for (e
synthetic_residence_period A synthetic residence period was constructed for the patient
Covered by — 5 standards
Why it matters & mappings
Assuming a single static address smears home-location exposure across days the patient was actually elsewhere; how location-over-time was modelled changes which days get which values and can bias exposure estimates.
If someone leaves on a trip mid-day, which place's environment "counts" for that day? This records the choice — the place they left, the place they arrived, both, or neither.
How boundary / transition days of the patient's trajectory (trip start / end, travel days) are attributed when location changes within a day. The temporal partner to the known_travel_interval address alignment.
Example
not_applicable — no trajectory transitions occur in the observation period
Allowed values
origin_location The transition day is attributed to the origin location
destination_location The transition day is attributed to the destination location
both_days_included Both ends of the transition are counted (exposure attributed at both location...
excluded Transition days are excluded from exposure attribution
not_applicable No trajectory transitions occur (e
Covered by — 5 standards
Why it matters & mappings
On a transition day the patient is in two places; whether that day is credited to the origin, the destination, both, or excluded changes which exposure value the day receives, and an undocumented rule makes the linkage irreproducible.
Health effects can trail exposure by days — a heat wave today may send someone to hospital next week — so analyses sometimes pair a clinical event with earlier exposure values. This records whether such a shift was already built into the data.
Whether and how values were lag-aligned to a clinical event. Relocated from envar_temporal: lag alignment attaches a value to an event (a linkage concern), not an intrinsic temporal property. See lag_alignment_specifier for the concrete lag value(s).
Example
none — values are at native dates; no lag alignment applied
Allowed values
none No lag alignment applied; values are at native dates
lag_n_days A single-day lag of N days has been applied
distributed_lag A distributed lag over a range of days has been applied
Covered by — 5 standards
Why it matters & mappings
If values were already shifted relative to the clinical event and this is not recorded, an analyst may apply the lag again — double-lagging is a silent analytic error that misdates every exposure.
See also: https://cran.r-project.org/package=dlnm
To protect privacy, a pipeline may deliberately move, blur, or drop a person's location after matching them to environmental data — so the value they end up with may be the value at a nearby place, not their real one. This records whether such a change was made and of what kind, so the perturbation is visible instead of hidden.
Any privacy-protecting transformation applied to the linked location after the spatial join, which changes the recorded location of the exposure (none / deterministic geographic jitter / suppression / aggregation to a coarser unit / stochastic perturbation). A linkage-stage concern: the transform is applied when the ambient value is attached to a person, so the value ultimately carried may be the value at a perturbed rather than the true location. A deterministic hex-reassignment jitter is the motivating case.
Examples
deterministic_geographic_jitter — the participant is reassigned to the largest hex in the same ZIP3 when the true hex's ZIP3 population is small
none — no privacy transform applied; the linked location is the true one
Allowed values
none No privacy transformation applied; the linked location is the true one
deterministic_geographic_jitter The location is deterministically reassigned to a nearby unit under a reprodu...
suppression The value or location is suppressed (dropped / withheld) when a disclosure ri...
aggregation_to_coarser_unit The location is coarsened to a larger geographic unit (e
stochastic_perturbation The location is perturbed by a random (non-deterministic) offset — contrast t...
Covered by — 5 standards
Why it matters & mappings
A privacy transform applied AFTER the spatial join changes the recorded location of the exposure, so a downstream analyst cannot tell a faithfully-linked value from a privacy-perturbed one; the ambient value attached to a person may be the value at a reassigned location, not the true one. Recording the transform is what keeps that perturbation declared rather than silent — and it is a linkage-stage concern, squarely in the layer EnVar defers to whoever performs the person-join.
The spelled-out details of the privacy change: what set it off (for example a small local population), the exact cutoff used, whether it always does the same thing, and the legal rule it follows.
Free-text detail of the privacy transformation named in privacy_transformation: the trigger / threshold, determinism, and governance basis. E.g. "reassign to largest hex in same ZIP3 when hex∩ZIP3 population ≤ 20,000; HIPAA expert determination; deterministic".
Example
reassign to largest hex in same ZIP3 when hex∩ZIP3 population ≤ 20,000; HIPAA expert determination; deterministic — deterministic privacy jitter, spelled out
Covered by — 5 standards
Why it matters & mappings
The transform name alone does not say what triggered it, at what threshold, or under what governance — two deterministic-jitter records with different thresholds perturb locations differently. Recording the trigger, determinism, and legal basis is what makes the perturbation reproducible and auditable rather than merely acknowledged.
When the circle-width field is empty, this says why — for example because no circle was used at all.
Reason linkage_buffer_radius_m is null.
Example
not_applicable — strategy is point extraction, so no buffer radius applies
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "no buffer applies because the strategy is point extraction" from "the radius was simply not recorded" — without it a null radius is ambiguous and the linkage cannot be audited.
When the how-values-were-combined field is empty, this says why.
Reason linkage_buffer_aggregation_method is null.
Example
not_applicable — strategy is point extraction, so no buffer aggregation applies
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Separates "not applicable — no buffer aggregation was performed" from an undocumented gap; without the reason a null method leaves the linkage unauditable.
When the maximum-station-distance field is empty, this says why.
Reason linkage_max_distance_to_station_m is null.
Example
not_applicable — strategy is gridded extraction, not nearest-station
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes "not applicable — the data is gridded, not station-based" from an undocumented cutoff; a bare null hides whether unlimited-distance station matches were allowed.
Before matching patient locations to map tiles, software sometimes converts all coordinates into a different mapping system that is better for measuring areas. This names that intermediate system, because the choice can nudge a location into a neighbouring tile.
Coordinate reference system the point-to-cell join was actually executed in, as an EPSG identifier or PROJ string, when it differs from the native SpatialReference.crs — e.g. reprojecting WGS84 points into an equal-area CRS before the spatial join.
Example
EPSG:5070 — CONUS Albers equal-area, the local_epsg the GAIA spatial join runs in
Why it matters & mappings
Reprojection can move a point across a cell boundary: two runs with the same native CRS but different working CRS are different linkages that can assign different exposures to the same address. Recording the working CRS makes the join reproducible rather than deployment-dependent.
See also: https://epsg.io/5070
When the geocoder-confidence field is empty, this says why.
Reason geocoding_score_propagated is null.
Example
upstream_data_not_propagated — the geocoder emitted a score but the pipeline dropped it
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Records whether the score was never produced or was produced but dropped by the pipeline — the difference between an upstream limitation and a fixable ETL gap.
When the clinical date-rule field is empty, this says why.
Reason clinical_date_assignment_convention is null.
Example
available_but_not_extracted — the clinical system documents its convention but the pipeline does not yet surface it
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Distinguishes a convention that is undocumented at the source from one the pipeline has not yet extracted — which determines whether the day-boundary cross-check can ever be completed.
When the travel-day rule field is empty, this says why.
Reason partial_day_attribution_rule is null.
Example
not_provided_by_source — the trajectory source does not document transition-day handling
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Separates "not applicable — the patient never changed location" from an undocumented handling of travel days; without it a null rule cannot be audited.
This spells out exactly how many days the exposure values were shifted relative to the clinical event — for example 3 days, or a whole range like 0 to 21 days.
Free-form specifier paired with lag_alignment_applied to capture the concrete lag values (e.g. "3" for a 3-day lag, or "0-21" for a distributed lag from 0 to 21 days). Empty when lag_alignment_applied = none.
Example
0-3 — distributed lag from 0 to 3 days before the clinical event (with lag_alignment_applied = distributed_lag)
Why it matters & mappings
Knowing that a lag was applied is useless without the concrete value(s); a 3-day lag and a distributed lag over 0-21 days define entirely different exposure windows and cannot be reconstructed after the fact.
When the lag field is empty, this says why — for example because the documentation is still being written.
Reason lag_alignment_applied is null.
Example
under_investigation — lag-alignment documentation for this ETL is still being populated
Allowed values
not_provided_by_source Source product does not produce this information
available_but_not_extracted Source produces this information but the current pipeline does not surface it
upstream_data_not_propagated An upstream tool emitted this information but the current pipeline dropped it...
under_investigation We are working on populating this slot
not_applicable This slot does not apply to this variable / record
Why it matters & mappings
Records why the lag-alignment status is unknown; without it analysts cannot tell whether the data is safely unlagged or the documentation simply has not caught up, leaving the double-lagging risk open.
Full field reference — every slot, cardinality & inheritance
| Field | Name | Tier | Cardinality / Range | Description |
|---|---|---|---|---|
| Linkage Strategy | linkage_strategy |
core | 1 LinkageStrategyEnum |
How a gridded value is attached to a patient location |
| Buffer Radius (Metres) | linkage_buffer_radius_m |
conditionally core | 0..1 Float |
Buffer radius in metres for buffer-aggregation strategies |
| Reason Buffer Radius Is Missing | linkage_buffer_radius_m_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason linkage_buffer_radius_m is null |
| Buffer Aggregation Method | linkage_buffer_aggregation_method |
conditionally core | 0..1 BufferAggregationEnum |
Aggregation method applied within the buffer (mean / max / median / area-weig... |
| Reason Buffer Aggregation Is Missing | linkage_buffer_aggregation_method_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason linkage_buffer_aggregation_method is null |
| Maximum Distance to Station (Metres) | linkage_max_distance_to_station_m |
conditionally core | 0..1 Float |
Maximum distance to a station for nearest-station strategies; values beyond t... |
| Reason Station Distance Is Missing | linkage_max_distance_to_station_m_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason linkage_max_distance_to_station_m is null |
| Linkage Working CRS | linkage_working_crs |
optional | 0..1 String |
Coordinate reference system the point-to-cell join was actually executed in, ... |
| Propagated Geocoding Precision | geocoding_precision_propagated |
recommended | 0..1 GeocodingPrecisionEnum |
Quality category propagated from the upstream geocoder (DeGAUSS precision c... |
| Propagated Geocoding Score | geocoding_score_propagated |
recommended | 0..1 Float |
Geocoder score (0-1) propagated from the upstream geocoder so the exposure re... |
| Reason Geocoding Score Is Missing | geocoding_score_propagated_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason geocoding_score_propagated is null |
| Address Period Alignment | address_period_alignment |
recommended | 0..1 AddressPeriodAlignmentEnum |
How the patient's location-over-time (the spatial axis of trajectory resoluti... |
| Clinical Date Assignment Convention | clinical_date_assignment_convention |
conditionally core | 0..1 ClinicalDateAssignmentEnum |
The clinical-side mirror of day_boundary_convention (envar_temporal): which... |
| Reason Date Convention Is Missing | clinical_date_assignment_convention_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason clinical_date_assignment_convention is null |
| Partial-Day Attribution Rule | partial_day_attribution_rule |
recommended | 0..1 PartialDayAttributionEnum |
How boundary / transition days of the patient's trajectory (trip start / end,... |
| Reason Attribution Rule Is Missing | partial_day_attribution_rule_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason partial_day_attribution_rule is null |
| Lag Alignment Applied | lag_alignment_applied |
recommended | 0..1 LagAlignmentEnum |
Whether and how values were lag-aligned to a clinical event |
| Lag Alignment Specifier | lag_alignment_specifier |
optional | 0..1 String |
Free-form specifier paired with lag_alignment_applied to capture the concre... |
| Reason Lag Alignment Is Missing | lag_alignment_applied_missing_reason |
optional | 0..1 MissingReasonEnum |
Reason lag_alignment_applied is null |
| Privacy Transformation | privacy_transformation |
recommended | 0..1 PrivacyTransformationEnum |
Any privacy-protecting transformation applied to the linked location after ... |
| Privacy Transformation Note | privacy_transformation_note |
recommended | 0..1 String |
Free-text detail of the privacy transformation named in `privacy_transformati... |
Conditional rules on this class
| Rule Applied | Preconditions | Postconditions |
|---|---|---|
| slot_conditions | {'linkage_strategy': {'equals_string': 'buffer_aggregation_around_residence'}} |
{'linkage_buffer_radius_m': {'required': True}} |
| Rule Applied | Preconditions | Postconditions |
|---|---|---|
| slot_conditions | {'linkage_strategy': {'equals_string_in': ['buffer_aggregation_around_residence', 'area_membership_residence_in_polygon', 'population_weighted_area_to_residence']}} |
{'linkage_buffer_aggregation_method': {'required': True}} |
| Rule Applied | Preconditions | Postconditions |
|---|---|---|
| slot_conditions | {'linkage_strategy': {'equals_string': 'nearest_station_with_max_distance'}} |
{'linkage_max_distance_to_station_m': {'required': True}} |
| Rule Applied | Preconditions | Postconditions |
|---|---|---|
| slot_conditions | {'lag_alignment_applied': {'equals_string_in': ['lag_n_days', 'distributed_lag']}} |
{'clinical_date_assignment_convention': {'required': True}} |
Diagram & LinkML source
classDiagram
class LinkageMethod
click LinkageMethod href "../../classes/LinkageMethod/"
LinkageMethod : address_period_alignment
LinkageMethod --> "0..1" AddressPeriodAlignmentEnum : address_period_alignment
click AddressPeriodAlignmentEnum href "../../enums/AddressPeriodAlignmentEnum/"
LinkageMethod : clinical_date_assignment_convention
LinkageMethod --> "0..1" ClinicalDateAssignmentEnum : clinical_date_assignment_convention
click ClinicalDateAssignmentEnum href "../../enums/ClinicalDateAssignmentEnum/"
LinkageMethod : clinical_date_assignment_convention_missing_reason
LinkageMethod --> "0..1" MissingReasonEnum : clinical_date_assignment_convention_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
LinkageMethod : geocoding_precision_propagated
LinkageMethod --> "0..1" GeocodingPrecisionEnum : geocoding_precision_propagated
click GeocodingPrecisionEnum href "../../enums/GeocodingPrecisionEnum/"
LinkageMethod : geocoding_score_propagated
LinkageMethod : geocoding_score_propagated_missing_reason
LinkageMethod --> "0..1" MissingReasonEnum : geocoding_score_propagated_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
LinkageMethod : lag_alignment_applied
LinkageMethod --> "0..1" LagAlignmentEnum : lag_alignment_applied
click LagAlignmentEnum href "../../enums/LagAlignmentEnum/"
LinkageMethod : lag_alignment_applied_missing_reason
LinkageMethod --> "0..1" MissingReasonEnum : lag_alignment_applied_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
LinkageMethod : lag_alignment_specifier
LinkageMethod : linkage_buffer_aggregation_method
LinkageMethod --> "0..1" BufferAggregationEnum : linkage_buffer_aggregation_method
click BufferAggregationEnum href "../../enums/BufferAggregationEnum/"
LinkageMethod : linkage_buffer_aggregation_method_missing_reason
LinkageMethod --> "0..1" MissingReasonEnum : linkage_buffer_aggregation_method_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
LinkageMethod : linkage_buffer_radius_m
LinkageMethod : linkage_buffer_radius_m_missing_reason
LinkageMethod --> "0..1" MissingReasonEnum : linkage_buffer_radius_m_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
LinkageMethod : linkage_max_distance_to_station_m
LinkageMethod : linkage_max_distance_to_station_m_missing_reason
LinkageMethod --> "0..1" MissingReasonEnum : linkage_max_distance_to_station_m_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
LinkageMethod : linkage_strategy
LinkageMethod --> "1" LinkageStrategyEnum : linkage_strategy
click LinkageStrategyEnum href "../../enums/LinkageStrategyEnum/"
LinkageMethod : linkage_working_crs
LinkageMethod : partial_day_attribution_rule
LinkageMethod --> "0..1" PartialDayAttributionEnum : partial_day_attribution_rule
click PartialDayAttributionEnum href "../../enums/PartialDayAttributionEnum/"
LinkageMethod : partial_day_attribution_rule_missing_reason
LinkageMethod --> "0..1" MissingReasonEnum : partial_day_attribution_rule_missing_reason
click MissingReasonEnum href "../../enums/MissingReasonEnum/"
LinkageMethod : privacy_transformation
LinkageMethod --> "0..1" PrivacyTransformationEnum : privacy_transformation
click PrivacyTransformationEnum href "../../enums/PrivacyTransformationEnum/"
LinkageMethod : privacy_transformation_note
name: LinkageMethod
annotations:
domain_of_use:
tag: domain_of_use
value: environmental_exposure
description: 'How a gridded environmental value gets attached to a patient: the resolution
of the patient''s spatiotemporal trajectory down to the resolution the exposure
data supports. Covers the linkage strategy and buffer parameters, the propagated
geocoder precision and score, how patient location-over-time is modelled (the spatial
axis), and the clinical-date-assignment convention, partial-day attribution, and
lag alignment (the temporal axis). One per record.'
title: Linkage Method
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://degauss.org/
rank: 1000
slot_usage:
linkage_strategy:
name: linkage_strategy
required: true
attributes:
linkage_strategy:
name: linkage_strategy
annotations:
tier:
tag: tier
value: core
justification:
tag: justification
value: 'The strategy determines which grid cells or stations contribute to
a patient''s value: point extraction, buffer aggregation, and population
weighting can assign materially different exposures to the same address.
Without it the person-level value cannot be reproduced or compared across
studies — this is the "linkage descriptor" gap named by the GECC/EIRENE
forum.'
explanation:
tag: explanation
value: Environmental data comes as a map of values, but health data belongs
to people. This slot records the rule used to pick a person's value off
that map — for example reading the value exactly at their home, or averaging
the values in a circle around it.
covered_by:
tag: covered_by
annotations:
omop_gaia:
tag: omop_gaia
annotations:
extent:
tag: extent
value: partial
status:
tag: status
value: asserted
where:
tag: where
value: working.spatial_join_exposure SQL (st_within with a hard-coded
buffer); spatial_join_log.txt
note:
tag: note
value: 'GAIA''s linkage strategy is only implicit in the st_within
SQL join semantics, not exposed as a documented structured slot.
Conservative: partial.'
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: DeGAUSS carries no structured linkage-strategy slot; the point-extraction
rule is implicit.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: Amadeus carries no linkage-strategy slot; the value is extracted
at request coordinates with no recorded strategy.
cher:
tag: cher
annotations:
extent:
tag: extent
value: partial
status:
tag: status
value: asserted
where:
tag: where
value: table_column_dictionary column tagged Spatial – Primary + reference
to boundaries schema
note:
tag: note
value: 'C-HER''s Spatial tags and boundaries-schema references encode
a spatial join relationship, though not EnVar''s linkage-strategy
enum. Conservative: partial.'
codata:
tag: codata
annotations:
extent:
tag: extent
value: out_of_layer
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: The gridded-to-patient linkage strategy is an instance-layer
derivation choice, outside CODATA's conceptual variable layer.
description: How a gridded value is attached to a patient location.
title: Linkage Strategy
examples:
- value: point_extraction_at_residence
description: extract the grid-cell value at the geocoded residence (Daymet tmax
scenario)
- value: population_weighted_area_to_residence
description: population-weighted aggregation over the residence tract (ACAG
PM2.5 scenario)
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: LinkageStrategyEnum
required: true
linkage_buffer_radius_m:
name: linkage_buffer_radius_m
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: 'For buffer strategies the radius defines the exposure footprint: a
500 m and a 5 km buffer around the same residence can average over very
different air or heat conditions, so the assigned value is not reproducible
without it.'
explanation:
tag: explanation
value: When exposure is averaged over a circle drawn around a person's home,
this is how wide that circle is, in metres.
description: Buffer radius in metres for buffer-aggregation strategies.
title: Buffer Radius (Metres)
examples:
- value: '500'
description: 500 m buffer around the geocoded residence
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: float
linkage_buffer_radius_m_missing_reason:
name: linkage_buffer_radius_m_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "no buffer applies because the strategy is point extraction"
from "the radius was simply not recorded" — without it a null radius is
ambiguous and the linkage cannot be audited.
explanation:
tag: explanation
value: When the circle-width field is empty, this says why — for example because
no circle was used at all.
description: Reason `linkage_buffer_radius_m` is null.
title: Reason Buffer Radius Is Missing
examples:
- value: not_applicable
description: strategy is point extraction, so no buffer radius applies
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: MissingReasonEnum
linkage_buffer_aggregation_method:
name: linkage_buffer_aggregation_method
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: Within the same buffer, mean, max, and area-weighted mean yield different
exposure values; omitting the method makes the assigned value irreproducible
and cross-study comparisons unsafe.
explanation:
tag: explanation
value: If several map values fall inside the circle around a home, they must
be boiled down to one number. This records how — for example by taking the
average, or the highest value.
description: Aggregation method applied within the buffer (mean / max / median
/ area-weighted mean).
title: Buffer Aggregation Method
examples:
- value: area_weighted_mean
description: area-weighted mean over the aggregation area (ACAG PM2.5 scenario)
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: BufferAggregationEnum
linkage_buffer_aggregation_method_missing_reason:
name: linkage_buffer_aggregation_method_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Separates "not applicable — no buffer aggregation was performed" from
an undocumented gap; without the reason a null method leaves the linkage
unauditable.
explanation:
tag: explanation
value: When the how-values-were-combined field is empty, this says why.
description: Reason `linkage_buffer_aggregation_method` is null.
title: Reason Buffer Aggregation Is Missing
examples:
- value: not_applicable
description: strategy is point extraction, so no buffer aggregation applies
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: MissingReasonEnum
linkage_max_distance_to_station_m:
name: linkage_max_distance_to_station_m
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: For nearest-station strategies this cutoff decides whether a distant
monitor still counts as "nearby"; beyond it the assignment is meaningless
and should be null. Without the cutoff, values assigned from stations tens
of kilometres away are indistinguishable from tight matches, silently degrading
exposure quality.
explanation:
tag: explanation
value: Some methods take the reading from the closest measuring station. This
is the farthest a station may be from the home before the match is considered
too unreliable and no value is assigned.
description: Maximum distance to a station for nearest-station strategies; values
beyond this distance get null.
title: Maximum Distance to Station (Metres)
examples:
- value: '50000'
description: stations farther than 50 km from the residence yield null
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: float
linkage_max_distance_to_station_m_missing_reason:
name: linkage_max_distance_to_station_m_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes "not applicable — the data is gridded, not station-based"
from an undocumented cutoff; a bare null hides whether unlimited-distance
station matches were allowed.
explanation:
tag: explanation
value: When the maximum-station-distance field is empty, this says why.
description: Reason `linkage_max_distance_to_station_m` is null.
title: Reason Station Distance Is Missing
examples:
- value: not_applicable
description: strategy is gridded extraction, not nearest-station
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: MissingReasonEnum
linkage_working_crs:
name: linkage_working_crs
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: 'Reprojection can move a point across a cell boundary: two runs with
the same native CRS but different working CRS are different linkages that
can assign different exposures to the same address. Recording the working
CRS makes the join reproducible rather than deployment-dependent.'
explanation:
tag: explanation
value: Before matching patient locations to map tiles, software sometimes
converts all coordinates into a different mapping system that is better
for measuring areas. This names that intermediate system, because the choice
can nudge a location into a neighbouring tile.
description: Coordinate reference system the point-to-cell join was actually executed
in, as an EPSG identifier or PROJ string, when it differs from the native `SpatialReference.crs`
— e.g. reprojecting WGS84 points into an equal-area CRS before the spatial join.
title: Linkage Working CRS
comments:
- 'Added after the reverse gap survey (docs/reverse-gap-survey.md, 2026-07): GAIA''s
ETL descriptor carries both `epsg` (native, 4326) and `local_epsg` (5070) —
the working CRS its PostGIS join actually executes in. EnVar had exactly one
`crs` slot, so the second one had no home; the survey''s verdict was that the
working CRS is a linkage hyperparameter, not a duplicate of the native CRS.'
examples:
- value: EPSG:5070
description: CONUS Albers equal-area, the `local_epsg` the GAIA spatial join
runs in
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://epsg.io/5070
owner: LinkageMethod
domain_of:
- LinkageMethod
range: string
geocoding_precision_propagated:
name: geocoding_precision_propagated
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: Geocoding precision determines whether "residence" means the actual
house or a ZIP-code centroid kilometres away — which changes which grid
cell the patient falls in and therefore their assigned exposure. Propagating
it lets analysts filter or down-weight coarsely located records.
explanation:
tag: explanation
value: Geocoding means turning a street address into map coordinates, and
it does not always land on the exact house — sometimes only on the street,
the ZIP area, or the city. This records how exact the landing was.
covered_by:
tag: covered_by
annotations:
omop_gaia:
tag: omop_gaia
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No geocoding-precision column on location.csv or external_exposure.csv.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: full
status:
tag: status
value: verified
where:
tag: where
value: geocoder + daymet CSV `precision` column (range/street/zip/etc.)
evidence:
tag: evidence
value: EnVar/examples/heat/COMPARISON.md §B (Geocoding precision —
✅ for DeGAUSS)
note:
tag: note
value: DeGAUSS carries the geocoding precision category first-class
in the `precision` column — the motivating source for this slot.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: Amadeus collapses the address to lat/lon at the THREDDS request
and carries no geocoding precision.
cher:
tag: cher
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: C-HER geocodes participants to points but does not carry the
precision of the geocode.
codata:
tag: codata
annotations:
extent:
tag: extent
value: out_of_layer
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: Propagated geocoder precision is an instance-layer linkage
quality signal, outside CODATA's conceptual scope.
description: Quality category propagated from the upstream geocoder (DeGAUSS `precision`
column).
title: Propagated Geocoding Precision
examples:
- value: range
description: street-centerline point interpolated within an address-range segment
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://degauss.org/
owner: LinkageMethod
domain_of:
- LinkageMethod
range: GeocodingPrecisionEnum
geocoding_score_propagated:
name: geocoding_score_propagated
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: The score quantifies how confident the geocoder was in its address
match; without it downstream analysts cannot apply quality cutoffs, and
poorly matched addresses contaminate the exposure assignment invisibly.
explanation:
tag: explanation
value: When software converts an address into map coordinates it also rates
its own confidence, from 0 to 1. This carries that rating along with the
exposure record.
covered_by:
tag: covered_by
annotations:
omop_gaia:
tag: omop_gaia
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No geocoder match-score column on location.csv or external_exposure.csv.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: full
status:
tag: status
value: verified
where:
tag: where
value: geocoder + daymet CSV `score` column
evidence:
tag: evidence
value: EnVar/examples/heat/COMPARISON.md §B (Geocoder match score
— ✅ for DeGAUSS)
note:
tag: note
value: DeGAUSS carries the geocoder match score first-class in the
`score` column.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: Amadeus carries no geocoder match score.
cher:
tag: cher
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: C-HER carries no geocoder confidence score.
codata:
tag: codata
annotations:
extent:
tag: extent
value: out_of_layer
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: A propagated geocoder score is an instance-layer linkage quality
signal, outside CODATA's conceptual scope.
description: Geocoder score (0-1) propagated from the upstream geocoder so the
exposure record knows the spatial precision of its anchor.
title: Propagated Geocoding Score
examples:
- value: '0.95'
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://degauss.org/
owner: LinkageMethod
domain_of:
- LinkageMethod
range: float
geocoding_score_propagated_missing_reason:
name: geocoding_score_propagated_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Records whether the score was never produced or was produced but dropped
by the pipeline — the difference between an upstream limitation and a fixable
ETL gap.
explanation:
tag: explanation
value: When the geocoder-confidence field is empty, this says why.
description: Reason `geocoding_score_propagated` is null.
title: Reason Geocoding Score Is Missing
examples:
- value: upstream_data_not_propagated
description: the geocoder emitted a score but the pipeline dropped it
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: MissingReasonEnum
address_period_alignment:
name: address_period_alignment
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: Assuming a single static address smears home-location exposure across
days the patient was actually elsewhere; how location-over-time was modelled
changes which days get which values and can bias exposure estimates.
explanation:
tag: explanation
value: People move house and travel, so "where the patient was" changes over
time. This records whether the study used one fixed address, a full address
history, or accounted for known trips away from home.
covered_by:
tag: covered_by
annotations:
omop_gaia:
tag: omop_gaia
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: GAIA/OMOP models a single static location per person and no
address-history / location-over-time alignment.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: DeGAUSS geocodes one address per row and models no location-over-
time period.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: Amadeus takes fixed lat/lon and models no address period.
cher:
tag: cher
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: C-HER joins a participant point to a hex with no location-over-
time alignment.
codata:
tag: codata
annotations:
extent:
tag: extent
value: out_of_layer
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: How patient location-over-time is modelled is an instance-layer
linkage concern, outside CODATA's conceptual scope.
description: How the patient's location-over-time (the spatial axis of trajectory
resolution) was modelled.
title: Address Period Alignment
examples:
- value: address_history_from_emr
description: an EMR-sourced address history covers the observation period
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: AddressPeriodAlignmentEnum
clinical_date_assignment_convention:
name: clinical_date_assignment_convention
annotations:
tier:
tag: tier
value: conditionally_core
justification:
tag: justification
value: If the clinical side collapsed timestamps to dates with a different
day-boundary rule than the exposure side, events near midnight are silently
joined to the wrong day's exposure; recording both rules is what makes that
mismatch detectable at all.
explanation:
tag: explanation
value: A hospital visit at 11 pm can count as "today" or "tomorrow" depending
on which clock and cutoff you use. This records the rule the clinical data
used to turn a timestamp into a calendar date.
description: 'The clinical-side mirror of `day_boundary_convention` (envar_temporal):
which timezone / day-boundary rule collapsed the clinical timestamp to the date
used in the join. A boundary mismatch between this and the exposure-side `day_boundary_convention`
silently misattributes boundary-hour events to the wrong day, which is what
makes the Core `day_boundary_convention` checkable at all. Metadata *about the
join* — never the clinical timestamp itself; carries no PHI.'
title: Clinical Date Assignment Convention
examples:
- value: local_midnight
description: matches the exposure-side day_boundary_convention (Daymet tmax
scenario)
- value: date_only_no_time
description: clinical record carried only a date, so no boundary rule applies
(ACAG PM2.5 scenario)
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: ClinicalDateAssignmentEnum
clinical_date_assignment_convention_missing_reason:
name: clinical_date_assignment_convention_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Distinguishes a convention that is undocumented at the source from
one the pipeline has not yet extracted — which determines whether the day-boundary
cross-check can ever be completed.
explanation:
tag: explanation
value: When the clinical date-rule field is empty, this says why.
description: Reason `clinical_date_assignment_convention` is null.
title: Reason Date Convention Is Missing
examples:
- value: available_but_not_extracted
description: the clinical system documents its convention but the pipeline does
not yet surface it
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: MissingReasonEnum
partial_day_attribution_rule:
name: partial_day_attribution_rule
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: On a transition day the patient is in two places; whether that day
is credited to the origin, the destination, both, or excluded changes which
exposure value the day receives, and an undocumented rule makes the linkage
irreproducible.
explanation:
tag: explanation
value: If someone leaves on a trip mid-day, which place's environment "counts"
for that day? This records the choice — the place they left, the place they
arrived, both, or neither.
covered_by:
tag: covered_by
annotations:
omop_gaia:
tag: omop_gaia
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: GAIA/OMOP models no trajectory transitions, so no partial-day
attribution rule is carried.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: DeGAUSS models no travel/transition days, so no partial-day
attribution is carried.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: Amadeus models no trajectory transitions, so no partial-day
attribution is carried.
cher:
tag: cher
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: C-HER is spatial-only and models no transition-day attribution.
codata:
tag: codata
annotations:
extent:
tag: extent
value: out_of_layer
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: Transition-day attribution is an instance-layer trajectory
concern, outside CODATA's conceptual scope.
description: How boundary / transition days of the patient's trajectory (trip
start / end, travel days) are attributed when location changes within a day.
The temporal partner to the `known_travel_interval` address alignment.
title: Partial-Day Attribution Rule
examples:
- value: not_applicable
description: no trajectory transitions occur in the observation period
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: PartialDayAttributionEnum
partial_day_attribution_rule_missing_reason:
name: partial_day_attribution_rule_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Separates "not applicable — the patient never changed location" from
an undocumented handling of travel days; without it a null rule cannot be
audited.
explanation:
tag: explanation
value: When the travel-day rule field is empty, this says why.
description: Reason `partial_day_attribution_rule` is null.
title: Reason Attribution Rule Is Missing
examples:
- value: not_provided_by_source
description: the trajectory source does not document transition-day handling
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: MissingReasonEnum
lag_alignment_applied:
name: lag_alignment_applied
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: If values were already shifted relative to the clinical event and this
is not recorded, an analyst may apply the lag again — double-lagging is
a silent analytic error that misdates every exposure.
explanation:
tag: explanation
value: Health effects can trail exposure by days — a heat wave today may send
someone to hospital next week — so analyses sometimes pair a clinical event
with earlier exposure values. This records whether such a shift was already
built into the data.
covered_by:
tag: covered_by
annotations:
omop_gaia:
tag: omop_gaia
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: GAIA/OMOP emits values at native dates with no lag-alignment
record.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: DeGAUSS emits per-day values at native dates with no lag-alignment
record.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: Amadeus emits per-day values at native dates with no lag-alignment
record.
cher:
tag: cher
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: C-HER is spatial-only and carries no lag-alignment record.
codata:
tag: codata
annotations:
extent:
tag: extent
value: out_of_layer
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: Lag alignment to a clinical event is an instance-layer linkage
concern, outside CODATA's conceptual scope.
description: 'Whether and how values were lag-aligned to a clinical event. Relocated
from envar_temporal: lag alignment attaches a value to an event (a linkage concern),
not an intrinsic temporal property. See `lag_alignment_specifier` for the concrete
lag value(s).'
title: Lag Alignment Applied
examples:
- value: none
description: values are at native dates; no lag alignment applied
from_schema: https://w3id.org/linkml/microschemas/envar
see_also:
- https://cran.r-project.org/package=dlnm
owner: LinkageMethod
domain_of:
- LinkageMethod
range: LagAlignmentEnum
lag_alignment_specifier:
name: lag_alignment_specifier
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Knowing that a lag was applied is useless without the concrete value(s);
a 3-day lag and a distributed lag over 0-21 days define entirely different
exposure windows and cannot be reconstructed after the fact.
explanation:
tag: explanation
value: This spells out exactly how many days the exposure values were shifted
relative to the clinical event — for example 3 days, or a whole range like
0 to 21 days.
description: Free-form specifier paired with `lag_alignment_applied` to capture
the concrete lag values (e.g. `"3"` for a 3-day lag, or `"0-21"` for a distributed
lag from 0 to 21 days). Empty when `lag_alignment_applied` = `none`.
title: Lag Alignment Specifier
examples:
- value: 0-3
description: distributed lag from 0 to 3 days before the clinical event (with
lag_alignment_applied = distributed_lag)
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: string
lag_alignment_applied_missing_reason:
name: lag_alignment_applied_missing_reason
annotations:
tier:
tag: tier
value: optional
justification:
tag: justification
value: Records why the lag-alignment status is unknown; without it analysts
cannot tell whether the data is safely unlagged or the documentation simply
has not caught up, leaving the double-lagging risk open.
explanation:
tag: explanation
value: When the lag field is empty, this says why — for example because the
documentation is still being written.
description: Reason `lag_alignment_applied` is null.
title: Reason Lag Alignment Is Missing
examples:
- value: under_investigation
description: lag-alignment documentation for this ETL is still being populated
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: MissingReasonEnum
privacy_transformation:
name: privacy_transformation
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: A privacy transform applied AFTER the spatial join changes the recorded
location of the exposure, so a downstream analyst cannot tell a faithfully-linked
value from a privacy-perturbed one; the ambient value attached to a person
may be the value at a reassigned location, not the true one. Recording the
transform is what keeps that perturbation declared rather than silent —
and it is a linkage-stage concern, squarely in the layer EnVar defers to
whoever performs the person-join.
explanation:
tag: explanation
value: To protect privacy, a pipeline may deliberately move, blur, or drop
a person's location after matching them to environmental data — so the value
they end up with may be the value at a nearby place, not their real one.
This records whether such a change was made and of what kind, so the perturbation
is visible instead of hidden.
covered_by:
tag: covered_by
annotations:
omop_gaia:
tag: omop_gaia
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: The heat-scenario GAIA/OMOP join carries the true geocoded
location with no privacy-transformation record on location.csv or
external_exposure.csv.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: DeGAUSS runs inside the institution and emits the true geocoded
location; no privacy transform is recorded in its CSVs.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: Amadeus extracts at the true request coordinates with no privacy-transformation
record.
cher:
tag: cher
annotations:
extent:
tag: extent
value: full
status:
tag: status
value: asserted
where:
tag: where
value: C-HER hex-reassignment privacy jitter (small-population hex
→ largest hex in same ZIP3)
note:
tag: note
value: C-HER applies the deterministic hex-reassignment privacy jitter
this slot models — it is the motivating case.
codata:
tag: codata
annotations:
extent:
tag: extent
value: out_of_layer
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: A post-join privacy transformation is an instance-layer linkage
step, outside CODATA's conceptual scope.
description: 'Any privacy-protecting transformation applied to the linked location
*after* the spatial join, which changes the recorded location of the exposure
(`none` / deterministic geographic jitter / suppression / aggregation to a coarser
unit / stochastic perturbation). A linkage-stage concern: the transform is applied
when the ambient value is attached to a person, so the value ultimately carried
may be the value at a perturbed rather than the true location. A deterministic
hex-reassignment jitter is the motivating case.'
title: Privacy Transformation
examples:
- value: deterministic_geographic_jitter
description: the participant is reassigned to the largest hex in the same ZIP3
when the true hex's ZIP3 population is small
- value: none
description: no privacy transform applied; the linked location is the true one
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: PrivacyTransformationEnum
privacy_transformation_note:
name: privacy_transformation_note
annotations:
tier:
tag: tier
value: recommended
justification:
tag: justification
value: The transform name alone does not say what triggered it, at what threshold,
or under what governance — two deterministic-jitter records with different
thresholds perturb locations differently. Recording the trigger, determinism,
and legal basis is what makes the perturbation reproducible and auditable
rather than merely acknowledged.
explanation:
tag: explanation
value: 'The spelled-out details of the privacy change: what set it off (for
example a small local population), the exact cutoff used, whether it always
does the same thing, and the legal rule it follows.'
covered_by:
tag: covered_by
annotations:
omop_gaia:
tag: omop_gaia
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No privacy transform is applied in the GAIA/OMOP heat scenario,
so there is no trigger/threshold/governance detail to record.
degauss:
tag: degauss
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No privacy transform is applied by DeGAUSS here, so there is
no transform detail to record.
amadeus:
tag: amadeus
annotations:
extent:
tag: extent
value: absent
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: No privacy transform is applied by Amadeus, so there is no
transform detail to record.
cher:
tag: cher
annotations:
extent:
tag: extent
value: full
status:
tag: status
value: asserted
where:
tag: where
value: C-HER §4.5 trigger (hex∩ZIP3 population threshold), deterministic
rule, HIPAA expert-determination basis
note:
tag: note
value: C-HER spells out the concrete trigger, determinism, and legal
basis of its jitter — exactly the detail this note slot captures.
codata:
tag: codata
annotations:
extent:
tag: extent
value: out_of_layer
status:
tag: status
value: asserted
where:
tag: where
value: no column
note:
tag: note
value: The detail of a post-join privacy transform is instance-layer,
outside CODATA's conceptual scope.
description: 'Free-text detail of the privacy transformation named in `privacy_transformation`:
the trigger / threshold, determinism, and governance basis. E.g. "reassign to
largest hex in same ZIP3 when hex∩ZIP3 population ≤ 20,000; HIPAA expert determination;
deterministic".'
title: Privacy Transformation Note
examples:
- value: reassign to largest hex in same ZIP3 when hex∩ZIP3 population ≤ 20,000;
HIPAA expert determination; deterministic
description: deterministic privacy jitter, spelled out
from_schema: https://w3id.org/linkml/microschemas/envar
owner: LinkageMethod
domain_of:
- LinkageMethod
range: string
rules:
- preconditions:
slot_conditions:
linkage_strategy:
name: linkage_strategy
equals_string: buffer_aggregation_around_residence
postconditions:
slot_conditions:
linkage_buffer_radius_m:
name: linkage_buffer_radius_m
required: true
description: 'Buffer aggregation needs its radius: the buffer size is a hyperparameter
that changes which cells contribute to the value (tier conditionally_core context
"buffer strategies").'
- preconditions:
slot_conditions:
linkage_strategy:
name: linkage_strategy
equals_string_in:
- buffer_aggregation_around_residence
- area_membership_residence_in_polygon
- population_weighted_area_to_residence
postconditions:
slot_conditions:
linkage_buffer_aggregation_method:
name: linkage_buffer_aggregation_method
required: true
description: Strategies that aggregate over an area (buffer, polygon membership,
population-weighted area) must state how cell values were combined (tier conditionally_core
context "buffer/area strategies").
- preconditions:
slot_conditions:
linkage_strategy:
name: linkage_strategy
equals_string: nearest_station_with_max_distance
postconditions:
slot_conditions:
linkage_max_distance_to_station_m:
name: linkage_max_distance_to_station_m
required: true
description: Nearest-station linkage must state its distance cutoff — without it
"nearest" is unbounded and irreproducible (tier conditionally_core context "station
strategies").
- preconditions:
slot_conditions:
lag_alignment_applied:
name: lag_alignment_applied
equals_string_in:
- lag_n_days
- distributed_lag
postconditions:
slot_conditions:
clinical_date_assignment_convention:
name: clinical_date_assignment_convention
required: true
description: 'Day-boundary cross-check, SPEC.md rule 8: when a lagged or event-matched
analysis is declared, the clinical-side date convention is required so the two
declared day rulers can be compared (tier conditionally_core context "lag_alignment_applied
!= none").'
See Also
Identifier and Mapping Information
Annotations
| property | value |
|---|---|
| domain_of_use | environmental_exposure |
Schema Source
- from schema: https://w3id.org/linkml/microschemas/envar
Mappings
| Mapping Type | Mapped Value |
|---|---|
| self | envar:LinkageMethod |
| native | envar:LinkageMethod |