Temporal reconciliation

Temporal reconciliation links target dates with label snapshots or validity windows and, by default, can also materialise the matched label sources per target date. The module therefore produces both an audit table and a practical handover folder for training data. The materialised sources can be passed to Spatial Reconstruction for grid alignment and to Soft Targets & Weights through the temporal-quality values.

Minimum inputs

Input	Required?	Notes
Target dates	Yes	Text list, CSV date field or raster folder with dates in filenames.
Label table CSV or label source folder	Optional, but needed for real reconciliation	A table may contain snapshot/validity dates and a source path column. A folder may contain dated rasters/vectors such as `labels_20240701.tif` or `survey_20240701.gpkg`.
Date or validity fields	Method-dependent	Use snapshot date fields for nearest/previous/next; use valid-from/valid-to for validity windows.
Source path field	For materialisation from CSV	Usually `source_path`, `label_path`, `raster_path` or `vector_path`. Relative paths are resolved against the CSV folder.
Tolerance, backtrack, half-life	Optional	Control acceptance and quality decay.

Accepted date formats

YYYY-MM-DD, YYYY/MM/DD, YYYY.MM.DD, YYYYMMDD, DD.MM.YYYY, DD/MM/YYYY

Matching

Method	Meaning
Static	Use one label state for all target dates. Mainly useful for metadata/date-axis generation.
Nearest / previous / next	Pick the closest valid snapshot according to direction and tolerance.
Validity window	Accept labels where `valid_from ≤ target_date ≤ valid_to`; open-ended valid-to is allowed.
Previous valid / backtrack	Use previous snapshots only within the backtrack window.

Core calculations

Δt = t_target − t_label

Date offset: signed temporal distance between target date and matched label snapshot. The output table stores |Δt| in days.

q_t = exp(−ln(2) · |Δt| / T_1/2)

Temporal quality: T_1/2 is the half-life in days. After one half-life, quality is 0.5. The accepted flag is a hard rule; q_t is a soft reliability value for later weighting.

L_target = L_j with accepted(t_target, t_j) = 1 and minimal allowed offset

Materialised label source: for each accepted target date, HELIX copies or indexes the matched raster/vector source as a per-date label source. Rasterisation and source fusion remain the responsibility of Spatial Reconstruction.

Main outputs

Output	Meaning
Date axis CSV	Index, date, year, day-of-year and spacing to previous/next date.
Temporal match CSV	Matched label state, offset, status, accepted flag, temporal quality, source path and materialised source path.
Materialised label-source index CSV	One row per target date with original and copied/indexed source path. Use this as handover to scripts, Model Builder or Spatial Reconstruction.
Reconciled label-source folder	Contains copied matched rasters/vectors where source paths were available and accepted.
Report JSON	Method, counts and output paths.

Temporal selects the correct label state for each date. Spatial Reconstruction then makes the selected source grid-aligned. Soft Targets & Weights can use q_t as reliability or weight information.