TIMELAG

In Rollforward & time series

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 function 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: TIMELAG('Investment', 'TimeLagNode', "Year").

Parameters

Value NodeNode referenceRequired

Input node with the values that should be time-lagged. Must have the selected time level.

TimeLag NodeNode referenceRequired

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.

Time LevelLevel nameRequired

Name of the time level where one time-level step equals one sequence step, specified in double quotes (e.g."Year")

Output shape

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

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'

Input node: 'LagProfile'

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

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'

Input node: 'TimeLagNode'

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

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'

Input node: 'LagProfile'

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

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'

Input node: 'LagProfile'

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

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.

See also

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.