TIMELAG
Category: Rollforward & time series
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 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.
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. |