LAG

The LAG function returns the values of a dimensioned variable or expression at a specified offset of a dimension prior to the current value of that dimension. Typically, you use the LAG function to retrieve values for a previous time period.

See also LAGABSPCT, LAGDIF, LAGPCT, and LEAD.

Return Value

The data type of the variable argument or NA when you try to lag prior to the first period of a time dimension.

Syntax

LAG(tariable n, dimension, [STATUS|NOSTATUS|limit-clause])

Arguments

variable

A variable or expression that is dimensioned by dimension.

n

The offset (that is, the number of dimension values) to lag. LAG uses this value to determine the number of values that LAG should go back in dimension to retrieve the value of variable. (See "Negative n Value".) To count the values, LAG uses the default status, unless you use the STATUS keyword or the limit-clause argument to specify a different dimension status list.

dimension

The dimension along which the lag occurs. While this can be any dimension, it is typically a hierarchical time dimension of type TEXT that is limited to a single level (for example, the month or year level) or a dimension with a type of DAY, WEEK, MONTH, QUARTER, or YEAR.

When variable has a dimension with a type of DAY, WEEK, MONTH, QUARTER, or YEAR and you want LAG to use that dimension, you can omit the dimension argument.

STATUS

Specifies that LAG should use the current status list (that is, only the dimension values currently in status in their current status order) when computing the lag.

NOSTATUS

Specifies that LAG should use the default status (that is, a list all the dimension values in their original order) when computing the lag.

limit-clause

Specifies that LAG should use the default status limited by limit-clause when computing the lag. You can use any valid LIMIT clause (see the entry for the LIMIT command for further information). To specify that LAG should use the current status limited by limit-clause when computing the lag, specify a LIMIT function for limit-clause.

Notes

Normally, n is a positive integer that indicates the number of time periods (or dimension values) before the current one. When you specify a negative value for n, it indicates the number of time periods after the current one. In effect, using a negative value for n turns LAG into a LEAD function.

Use care when assigning the results of LAG back into the time-series variable. Results are assigned one cell at a time, so you can overwrite the whole array with the first value returned, instead of moving all the values over n positions. You can, however, use LAG to calculate a series of values based on the initial value.

Examples

1999
2000
Jan1999
Feb1999
...
Dec1999
Jan2000
Feb2000
...
Dec2000

TIME           TIMELEVELREL
-------------- ------------
1999           Year
2000           Year
Jan1999        Month
Feb1999        Month
...            ...
Dec1999        Month
Jan2000        Month
Feb2000        Month
...            ...
Dec2000        Month

LIMIT product TO 'racquets'
LIMIT district TO 'Dallas'
LIMIT time TO 'Jan2000' 'Feb2000'-
REPORT DOWN time sales HEADING 'Last Year' LAG(sales, 12, time, -
     LEVELREL timelevelrel)

DISTRICT: DALLAS
               -------PRODUCT-------
               ------RACQUETS-------
TIME           SALES      Last Year
-------------- ---------- ----------
Jan2000        125,879.86 118,686.75
Feb2000        150,833.64 142,305.99