RainbowStats™ · Command reference
LAG — Previous Observations
Align earlier values with later observations for comparisons, growth calculations and dynamic models.
LAG returns a lagged time series or applies the same lag to each series in a data list. A positive lag places an earlier observation’s value at a later observation’s date. The values retain their original economic meaning and units.
Quick start: current and previous unemployment
x = SERIES_SINCE(UNRATE,20010101)
previous = SET_NAME(LAG(x,1),"Previous observation unemployment rate")
LINE_CHART(LIST(x,previous))Run this example in RainbowStats
The unemployment rate is monthly, so a one-observation lag corresponds to the preceding month when observations are consecutive. The chart compares current unemployment with the previous observation’s rate.
DIFF or LOGDIFF when the desired result is a change.Syntax and supported inputs
LAG(series)
LAG(series,n)
LAG(seriesList)
LAG(seriesList,n)| Argument or form | Meaning |
|---|---|
series | A single data series. Returns a lagged series. |
seriesList | A data-series list. Returns a list with the lag applied separately to each member. |
n | Integer number of observation intervals. Use a positive integer for the backward-looking lags documented here. |
| One argument | Defaults to a lag of 1. |
| Two arguments | Uses the supplied integer lag. The dispatcher parses this argument as an integer. |
The command accepts one or two arguments. For a list, the same integer lag is applied to every member. Different lags for different variables can be constructed individually and then assembled with LIST.
Lag direction and observation dates
LAG(x,n)[t] = x[t−n]For n = 1, the value displayed at February’s date comes from January; the value at March’s date comes from February. The lagged series loses the earliest observations that have no predecessor within the supplied input.
| Output date | Current value | LAG(x,1) |
|---|---|---|
| January | 100 | No earlier input observation |
| February | 110 | 100 — January’s value |
| March | 108 | 110 — February’s value |
| April | 115 | 108 — March’s value |
The returned lagged values remain in the original units. For unemployment expressed in percent, lagged unemployment is still a rate in percent.
12 means twelve months. On a quarterly series, 4 means four quarters. On daily financial data, 5 usually spans five stored observations, not necessarily five calendar days. Gaps and irregular sampling change elapsed time.Examples: comparisons, changes and regression
Use the default one-observation lag
x = SERIES_SINCE(UNRATE,20010101)
LINE_CHART(LAG(x))Calculate a twelve-month absolute change
x = SERIES_SINCE(UNRATE,20000101)
change = x-LAG(x,12)
LINE_CHART(SET_UNITS(SET_NAME(change,"Twelve-month unemployment-rate change"),"Percentage points"))For a consecutive monthly series, this subtracts the unemployment rate twelve months earlier. It is a percentage-point change, not a percentage growth rate.
Calculate a simple year-over-year percentage change
x = SERIES_SINCE(CPIAUCSL,20000101)
inflation = 100*(x/LAG(x,12)-1)
LINE_CHART(SET_UNITS(SET_NAME(inflation,"Twelve-month CPI percentage change"),"Percent change"))This ratio requires an appropriate nonzero comparison value. For a logarithmic change instead, use 100*LOGDIFF(x,12); the two growth measures differ.
Lag every series in a list
levels = LIST(SERIES_SINCE(UNRATE,20010101),SERIES_SINCE(TCU,20010101))
previous = LAG(levels,1)
previousThe result remains a data-series list. Displaying it directly may show metadata rather than a chart. Each member is lagged on its own observation sequence; use compatible frequencies and inspect alignment before combining results.
Use a lagged explanatory variable
employment = DIFF(SERIES_SINCE(PAYEMS,20010101))
production = DIFF(SERIES_SINCE(INDPRO,20010101))
r = REGRESSION(LIST(employment,LAG(production,1)))
EXTRACT(r,"slideshow")This relates current payroll changes to the preceding observation’s industrial-production change. The first list member is the dependent variable. Lagging a predictor does not by itself establish causality or eliminate omitted-variable problems.
Choose a lag, difference or log change
| Expression | Meaning |
|---|---|
LAG(x,1) | Previous level, aligned at the current observation date. |
x-LAG(x,1) | One-period absolute change; corresponds to the usual first-difference calculation. |
DIFF(x) | Direct command for one-period absolute changes. |
x-LAG(x,12) | Absolute change over twelve observation intervals. |
100*(x/LAG(x,12)-1) | Simple percentage change over twelve observation intervals. |
LOGDIFF(x,12) | Fractional natural-log change over twelve observation intervals; multiply by 100 for percent log change. |
DIFF(DIFF(x)) | Second difference. This is distinct from x-LAG(x,2). |
Do not use EXTRACT(x,"lag") for the supplied series or data-list operators: neither implements that named extract. Use the direct LAG command.
Working with the data
- Retain enough history. If a requested display begins in January and needs a twelve-month lag, include the preceding year in the input. Lagging an already clipped sample cannot recover omitted history.
- Check spacing and frequency. Monthly, quarterly and daily lags cover different intervals. Missing observations can make a lag span more elapsed time than expected.
- Align after transformation. Lags shorten the usable input sample. Check common observations before regression, correlation or arithmetic comparisons.
- Distinguish observation dates from publication dates. A lag does not reconstruct what was known at a historical decision date. For forecasting, account separately for release delays and data revisions.
- Interpret plots correctly. The x-axis uses the lagged series’ output dates; its values come from earlier observations. Label the lag explicitly with
SET_NAME. - Use documented integer lags. The examples cover positive backward-looking lags. Do not assume fractional-lag interpolation or a lead convention for negative integers.