TIMELAG

Overview

The TIMELAG function calculates time-lagged effects on a chosen time granularity.
Each value from the input node is distributed over future periods according to a lag profile. Multiple contributions can overlap when several input values are lagged into the same period.

Use this when an effect should show up gradually or with a delay across time periods, for example to model delayed investment effects or gradual impact curves.

Syntax

TIMELAG('ValueNode', 'TimeLagNode', "TimeLevel")

Example usage: TIMELAG('Investment', 'TimeLagNode', "Year")

Parameters

Parameter	Description	Type	Required
Value Node	Input node with the values that should be time-lagged. Must have the selected time level.	Node reference	Yes
TimeLag Node	Node containing values between `0` and `1` (= 100%) on the `Sequence` dimension, defining how the lag is applied. Sequence entry `0` refers to the impact in the base year. This node should not have the selected time level.	Node reference	Yes
Time Level	Name of the time level where one time-level step equals one sequence step, specified in double quotes (e.g.`"Year"`)	Level name	Yes

Output Shape

Aspect	Behavior
Dimensionality	Preserves the non-time levels of the Value Node. The time level is set as specified.
Values	Each input value is multiplied by the lag input and spread across future periods. Overlapping contributions are summed.
Row count	Typically increases, as each input value generates multiple output rows across the lag window.

Watch Out

The Value Node must have a time level at least as fine-grained as specified in the function.
The TimeLag Node must not contain any time level.
The TimeLag Node cannot be more fine-grained than the Value Node on non-sequence levels.
Beyond the last defined sequence entry, the last lag value is repeated indefinitely. If the last entry is 0.75, the contribution permanently stays at 75%. It does not automatically reach 100%.
Gaps in the sequence (e.g. entries at 0, 1, 2, 4 but not 3) are treated as zero.
If the sequence does not start at 0, position 0 defaults to zero.
If the TimeLag Node has no matching lag profile for a given category, the output for that category is zero (not the original values).
If the Value Node has data at a finer time level than the specified Time Level (e.g. monthly data with "Year"), values are automatically aggregated before the lag is applied.

Examples

Distributing a single value with a gradual ramp-up

This example shows how a single investment is gradually phased in over time. 20% of the effect is felt immediately, 50% after one year, and the full effect is reached after two years.

Input node: Cost

Year	Cost
2025	100

Input node: LagProfile

Sequence	Effect
0	0.2
1	0.5
2	1

Formula: TIMELAG('Cost', 'LagProfile', "Year")

Year	-> TIMELAG Result
2025	100 * 0.2 = 20
2026	100 * 0.5 = 50
2027	100 * 1 = 100

The effect ramps up from 20% to 100% over two years. From 2027 onward, the full value persists because the last sequence entry (1) repeats indefinitely.

Overlapping contributions from multiple input periods

This example shows how investments are distributed over future years based on a lag profile. The lag profile gradually releases each investment amount over three sequence steps, so later years can contain overlapping contributions from multiple inputs.

Input node: Investment

Year	Investment
2025	10
2026	0
2027	15
2028	0

Input node: TimeLagNode

Sequence	Effect
0	0
1	0.25
2	0.5
3	1

Formula: TIMELAG('Investment', 'TimeLagNode', "Year")

Year	→ TIMELAG Result
2025	10 * 0 = 0
2026	10 * 0.25 = 2.5
2027	10 * 0.5 = 5
2028	10 * 1 + 15 * 0.25 = 13.75
2029	10 * 1 + 15 * 0.5 = 17.5
2030	10 * 1 + 15 * 1 = 25

From 2028 onward, both the 2025 investment (at full effect) and the 2027 investment (ramping up) contribute to the result.

Different lag profiles per category

The TimeLag Node can include non-sequence dimensions to define separate lag curves per category. Here, Category A ramps up in one year while Category B ramps up over three years.

Input node: Investment

Year	Category	Investment
2025	A	100
2025	B	100

Input node: LagProfile

Sequence	Category	Effect
0	A	0.5
1	A	1
0	B	0
1	B	0.25
2	B	0.5
3	B	1

Formula: TIMELAG('Investment', 'LagProfile', "Year")

Year	Category	-> TIMELAG Result
2025	A	100 * 0.5 = 50
2026	A	100 * 1 = 100
2025	B	100 * 0 = 0
2026	B	100 * 0.25 = 25
2027	B	100 * 0.5 = 50
2028	B	100 * 1 = 100

Category A reaches full effect after one year. Category B ramps up gradually over three years. The lag profile node can also use a coarser level than the Value Node (e.g. Product Group on the lag profile while the Value Node has Product). Child values inherit the parent's lag curve.

Temporary effect with a zero-ending sequence

If the last sequence entry is 0, the contribution decays to nothing permanently. This models impulse or temporary effects that fully disappear after a defined period.

Input node: Campaign

Year	Campaign
2025	100

Input node: LagProfile

Sequence	Effect
0	0
1	1
2	0.5
3	0

Formula: TIMELAG('Campaign', 'LagProfile', "Year")

Year	-> TIMELAG Result
2025	100 * 0 = 0
2026	100 * 1 = 100
2027	100 * 0.5 = 50
2028	100 * 0 = 0

The effect peaks in 2026, decays to half in 2027, and disappears completely from 2028 onward. Because the last sequence entry is 0, the contribution stays at zero permanently.

Related Functions

Function	When to use instead
STRETCH_CURVE	When you want to stretch or compress a defined profile along the axis instead of applying a delayed effect over time.
SCHEDULEPROJECTS	When you want to place project blueprints onto actual start periods instead of distributing an existing value with a lag profile.
SHIFT	When you need to move existing values by a direct offset along a time level instead of distributing them with a lag profile over multiple periods.