Helical features

Helical features encode dates as cyclic seasonal variables. A date is mapped onto a circle so that the end and start of a year are close; sine/cosine coordinates and optional higher harmonic orders become model features. Class/context interaction rasters can multiply these time features with class or context support.

Minimum inputs

Input	Required?	Notes
Target dates	Yes	Text, CSV date field or raster folder with dates in filenames.
Reference grid	Required for raster outputs	Defines extent, CRS and raster size.
Class/soft stack or hard label raster	Only for class × time stacks	Soft stacks are normalized; hard labels are converted to one-hot class bands.
Context stack	Only for context × time stacks	Must match the reference grid.

Important controls

Control	Effect
Feature mode	Selects annual, semiannual, quarterly or multi-harmonic features.
Max harmonic K	Maximum harmonic order `K`; harmonic `k=1` is annual, `k=2` semiannual, and larger `k` captures shorter cycles.
Year length and phase origin	Define the cyclic year and the day used as phase zero.
Include linear time / date spacing	Adds trend and temporal-spacing columns.
Write raster / interaction stacks	Creates constant time-feature rasters and optional class/context × time interactions.

Core calculations

φ = ((DOY − d₀) / Y) mod 1

Seasonal phase: Y is the year length and d₀ is the phase-origin day. Phase wraps at the year boundary, so late December and early January remain close.

s_k = sin(2π · k · φ)

c_k = cos(2π · k · φ), k = 1,…,K

Harmonics: k=1 is annual, k=2 semiannual. Higher k values add shorter cyclic components.

t_norm = elapsed_days / max(total_span_days, 1)

Linear time: optional trend feature between 0 and 1. It complements cyclic features when long-term progression matters.

class-time_c,k(x) = support_c(x) · s_k

class-time_c,k+K(x) = support_c(x) · c_k

Interactions: class/context support gates the seasonal feature spatially. Only bounded temporal features are multiplied into interaction rasters; raw year/day metadata remain in the CSV.

Main outputs

Output	Meaning
Helical feature CSV	One row per date with phase, sine/cosine harmonics and optional linear/spacing columns.
Helical raster stacks	Constant-value time-feature rasters for raster-only modelling pipelines.
Class × helical stacks	Class support multiplied by bounded time features.
Context × helical stacks	Context bands multiplied by bounded time features.
Report JSON	Mode, date count, harmonic count and generated paths.