statsmodels.tsa.tsatools.lagmat#

statsmodels.tsa.tsatools.lagmat(x, maxlag, trim='forward', original='ex', use_pandas=False, *, result_object=None)[source]#

Create 2d array of lags

Parameters:

xarray_like

Data; if 2d, observation in rows and variables in columns.

maxlagint or array_like of int

The lags to be applied.

int : All lags from zero to maxlag are included.
array_likeAll lags associated to the values in the array.
Must contain non-negative integers.

trim{‘forward’, ‘backward’, ‘both’, ‘none’, None}, optional

The trimming method to use.

‘forward’ : trim invalid observations in front.
‘backward’ : trim invalid initial observations.
‘both’ : trim invalid observations on both sides.
‘none’, None : no trimming of observations.

original{‘ex’,’sep’,’in’}, optional

How the original is treated.

‘ex’ : drops the original array returning only the lagged values.
‘in’ : returns the original array and the lagged values as a single array.
‘sep’returns a tuple (original array, lagged values). The original
array is truncated to have the same number of rows as the returned lagmat.

use_pandasbool, optional

If true, returns a DataFrame when the input is a pandas Series or DataFrame. If false, return numpy ndarrays.

result_objectbool, optional

Flag controlling whether a LagmatResult is returned. When original="sep" a LagmatResult is always returned. For other values of original a bare array is returned unless result_object=True, which additionally yields a LagmatResult with leads set to None.

Returns:

LagmatResult, ndarray, or DataFrame

When original="sep" (or result_object=True), a LagmatResult with fields:

lagsndarray or DataFrame: The array with lagged observations.
leadsndarray, DataFrame, or None: The original (unlagged) array, truncated to have the same number of rows as lags. None for other values of original, where the original series was either excluded (“ex”) or folded into lags (“in”).

For other values of original a bare array (or, when use_pandas=True and x is a pandas object, a DataFrame) of lagged observations is returned instead.

Notes

When using a pandas DataFrame or Series with use_pandas=True, trim can only be ‘forward’ or ‘both’ since it is not possible to consistently extend index values.

Examples

>>> from statsmodels.tsa.tsatools import lagmat
>>> import numpy as np
>>> X = np.arange(1,7).reshape(-1,2)
>>> lagmat(X, maxlag=2, trim="forward", original='in')
array([[ 1.,  2.,  0.,  0.,  0.,  0.],
   [ 3.,  4.,  1.,  2.,  0.,  0.],
   [ 5.,  6.,  3.,  4.,  1.,  2.]])

>>> lagmat(X, maxlag=2, trim="backward", original='in')
array([[ 5.,  6.,  3.,  4.,  1.,  2.],
   [ 0.,  0.,  5.,  6.,  3.,  4.],
   [ 0.,  0.,  0.,  0.,  5.,  6.]])

>>> lagmat(X, maxlag=2, trim="both", original='in')
array([[ 5.,  6.,  3.,  4.,  1.,  2.]])

>>> lagmat(X, maxlag=2, trim="none", original='in')
array([[ 1.,  2.,  0.,  0.,  0.,  0.],
   [ 3.,  4.,  1.,  2.,  0.,  0.],
   [ 5.,  6.,  3.,  4.,  1.,  2.],
   [ 0.,  0.,  5.,  6.,  3.,  4.],
   [ 0.,  0.,  0.,  0.,  5.,  6.]])

>>> lagmat(X, maxlag=[1, 3], trim="forward", original='ex')
array([[ 1.,  2.,  0.,  0.,  0.,  0.],
   [ 3.,  4.,  1.,  2.,  0.,  0.],
   [ 5.,  6.,  3.,  4.,  1.,  2.]])