# Rollforward & time series
URL: https://docs.valsight.ai/rollforward-time-series/
Description: Use this category when you need time-based logic such as projections, running totals, moving windows, and timing effects.
Use this category when you need **time-based logic** such as projections, running totals, moving windows, and timing effects.

These functions operate along the time axis to help you forecast values into the future, build cumulative KPIs, smooth values over time, or model delayed impacts.

## Start here if you want to:

* **Project values forward** using drivers
* Use **cumulative KPIs** like `YTD`
* Use **rolling windows** such as moving average or moving sum
* Model **timing effects** such as delays or stretched profiles
* Use a **previous-period** building block for loop logic

## Not here if you want to:

* Use standard growth comparisons or deltas → see [Compare periods](/compare-periods/)
* Reshape dimensionality → see [Dimensionality & hierarchies](/dimensionality-hierarchies/)

## Mental model

* **Projection**: calculate future periods based on a base and driver logic
* **Cumulative**: sum or multiply over time, either continuously or with periodic resets
* **Rolling window**: aggregate across a sliding window of prior periods
* **Timing effects**: shift or spread impacts across time
* **Loop logic**: reference previous-period values with an explicit base case

## Common patterns

| Name                               | What it does                                                        | Formula                                              |
| ---------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------- |
| Project forward with drivers       | Use when you want a flexible driver-based projection.               | `ROLLFORWARD_ADVANCED('Base', 'Driver1', 'Driver2')` |
| Build a running total              | Use when you want cumulative values across the full time axis.      | `RUNNINGSUM('Node')`                                 |
| Cumulative KPI with reset          | Use when you want cumulative totals that reset within each year.    | `YTD('Node')`                                        |
| Smooth values with a moving window | Use when you want a rolling average over prior periods.             | `MOVINGAVG('Node', "TimeLevel", WindowSize)`         |
| Model delayed impact               | Use when an effect should appear after a delay.                     | `TIMELAG('Node', 'TimeLagNode', "TimeLevel")`        |
| Loop logic with a base case        | Use when you need loop-style logic with an explicit starting point. | `PREVIOUS('Node', "Level", 'BaseNode', "BaseValue")` |

## Functions in this category

**Projection**

| Function                                        | Description                                                                                                                                             |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ROLLFORWARD\_ADVANCED](/rollforward-advanced/) | Projects a node into the future including the effects of defined driver nodes and optional parameters (e.g., seasonal/average projection, aging logic). |
| [ROLLFORWARD](/rollforward/)                    | Projects a node into the future including the additive effects of defined driver nodes.                                                                 |
| [ROLLFORWARD\_MUL](/rollforward-mul/)           | Projects a node into the future including the multiplicative effects of defined driver nodes.                                                           |

**Cumulative and rolling calculations**

| Function                     | Description                                                                                        |
| ---------------------------- | -------------------------------------------------------------------------------------------------- |
| [RUNNINGSUM](/runningsum/)   | Calculates the cumulative sum along the time axis.                                                 |
| [RUNNINGPROD](/runningprod/) | Calculates the cumulative product along the time axis.                                             |
| [MOVINGAVG](/movingavg/)     | Returns the moving average of the current value and preceding values, as defined by a time window. |
| [MOVINGSUM](/movingsum/)     | Returns the moving sum of the current value and preceding values, as defined by a time window.     |
| **MTD** (see [YTD](/ytd/))   | Returns month-to-date values as a running sum per month over the lowest time level.                |
| **QTD** (see [YTD](/ytd/))   | Returns quarter-to-date values as a running sum per quarter over the lowest time level.            |
| [YTD](/ytd/)                 | Returns year-to-date values as a running sum per year over the lowest time level.                  |
| **WTD** (see [YTD](/ytd/))   | Returns week-to-date values as a running sum per week over the lowest time level.                  |

**Timing and loop logic**

| Function                               | Description                                                                                                                          |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| [TIMELAG](/timelag/)                   | Applies time-lagged effects at a given time granularity to model delays or growth curves.                                            |
| [STRETCH\_CURVE](/stretch-curve/)      | Stretches curves along the X-axis by a factor, starting at 0 by default or at an optional X position.                                |
| [SCHEDULEPROJECTS](/scheduleprojects/) | Calculates a project KPI (e.g., revenue) over time given each project’s timing.                                                      |
| [PREVIOUS](/previous/)                 | Returns the previous period’s value, except at a base period where it takes a specified base node value, enabling loop calculations. |

**Statistical forecasting**

| Function         | Description                                                                       |
| ---------------- | --------------------------------------------------------------------------------- |
| [ARIMA](/arima/) | Forecasts values using an autoregressive integrated moving average (ARIMA) model. |

## Choosing between similar functions

**ROLLFORWARD\_ADVANCED vs ROLLFORWARD / ROLLFORWARD\_MUL**

* Use `ROLLFORWARD_ADVANCED` when you need richer projection options and more control
* Use `ROLLFORWARD` for additive drivers
* Use `ROLLFORWARD_MUL` for multiplicative drivers

**MTD/QTD/YTD/WTD vs RUNNINGSUM**

* Use to-date functions for totals that reset within periods
* Use `RUNNINGSUM` for a running total across the full time axis

**MOVINGAVG/MOVINGSUM vs to-date functions**

* Use moving functions for rolling windows
* Use to-date functions for cumulative totals within the current period

**PREVIOUS vs Compare periods shortcuts**

* Use `PREVIOUS` when you need a base case and loop-style logic
* Use `PM`/`PY`/`PQ`/`PW` for simple previous-period references

**TIMELAG vs STRETCH\_CURVE**

* Use `TIMELAG` for delayed effects
* Use `STRETCH_CURVE` for stretching/compressing a profile

## Pitfalls & troubleshooting

* **Future periods are missing in projections:** confirm the base series has values in the last actual period and drivers are defined for the projection range
* **Projection results look wrong:** validate the base node and each driver node separately, then add drivers back one by one
* **Cumulative totals are too large:** confirm whether you used `RUNNINGSUM` (no reset) versus `MTD/QTD/YTD/WTD` (resets)
* **Moving windows look shifted:** verify the time level and window definition and confirm with spot checks in Data preview
* **PREVIOUS behaves unexpectedly at the first period:** verify the base case and handle missing values explicitly if needed
* **Timing effects feel wrong:** confirm the time granularity and whether you need a lag (`TIMELAG`) versus a profile stretch (`STRETCH_CURVE`) or project scheduling (`SCHEDULEPROJECTS`)

## Related

* [Compare periods](/compare-periods/): standard growth comparisons and previous-period shortcuts
* [Dimensionality & hierarchies](/dimensionality-hierarchies/): prepare output shape or create empty simulation space
* [Troubleshooting guide](/troubleshooting-guide/): missing values and unexpected results
* [Function catalog](/function-catalog/): full signatures, parameters, and examples