"markdown": "---\ntitle: augment_lags\n---\n\n\n\n`augment_lags(data, date_column, value_column, lags=1, engine='pandas')`\n\nAdds lags to a Pandas DataFrame or DataFrameGroupBy object.\n\nThe `augment_lags` function takes a Pandas DataFrame or GroupBy object, a date column, a value column or list of value columns, and a lag or list of lags, and adds lagged versions of the value columns to the DataFrame.\n\n## Parameters\n\n| Name | Type | Description | Default |\n|----------------|----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|\n| `data` | pd.DataFrame or pd.core.groupby.generic.DataFrameGroupBy | The `data` parameter is the input DataFrame or DataFrameGroupBy object that you want to add lagged columns to. | _required_ |\n| `date_column` | str | The `date_column` parameter is a string that specifies the name of the column in the DataFrame that contains the dates. This column will be used to sort the data before adding the lagged values. | _required_ |\n| `value_column` | str or list | The `value_column` parameter is the column(s) in the DataFrame that you want to add lagged values for. It can be either a single column name (string) or a list of column names. | _required_ |\n| `lags` | int or tuple or list | The `lags` parameter is an integer, tuple, or list that specifies the number of lagged values to add to the DataFrame. - If it is an integer, the function will add that number of lagged values for each column specified in the `value_column` parameter. - If it is a tuple, it will generate lags from the first to the second value (inclusive). - If it is a list, it will generate lags based on the values in the list. | `1` |\n| `engine` | str | The `engine` parameter is used to specify the engine to use for augmenting lags. It can be either \"pandas\" or \"polars\". - The default value is \"pandas\". - When \"polars\", the function will internally use the `polars` library for augmenting lags. This can be faster than using \"pandas\" for large datasets. | `'pandas'` |\n\n## Returns\n\n| Type | Description |\n|--------------|-----------------------------------------------------|\n| pd.DataFrame | A Pandas DataFrame with lagged columns added to it. |\n\n## Examples\n\n\n::: {.cell execution_count=1}\n``` {.python .cell-code}\nimport pandas as pd\nimport pytimetk as tk\n\ndf = tk.load_dataset('m4_daily', parse_dates=['date'])\ndf\n```\n\n::: {.cell-output .cell-output-display execution_count=1}\n```{=html}\n<div>\n<style scoped>\n .dataframe tbody tr th:only-of-type {\n vertical-align: middle;\n }\n\n .dataframe tbody tr th {\n vertical-align: top;\n }\n\n .dataframe thead th {\n text-align: right;\n }\n</style>\n<table border=\"1\" class=\"dataframe\">\n <thead>\n <tr style=\"text-align: right;\">\n <th></th>\n <th>id</th>\n <th>date</th>\n <th>value</th>\n </tr>\n </thead>\n <tbody>\n <tr>\n <th>0</th>\n <td>D10</td>\n <td>2014-07-03</td>\n <td>2076.2</td>\n </tr>\n <tr>\n <th>1</th>\n <td>D10</td>\n <td>2014-07-04</td>\n <td>2073.4</td>\n </tr>\n <tr>\n <th>2</th>\n <td>D10</td>\n <td>2014-07-05</td>\n <td>2048.7</td>\n </tr>\n <tr>\n <th>3</th>\n <td>D10</td>\n <td>2014-07-06</td>\n <td>2048.9</td>\n </tr>\n <tr>\n <th>4</th>\n <td>D10</td>\n <td>2014-07-07</td>\n <td>2006.4</td>\n </tr>\n <tr>\n <th>...</th>\n <td>...</td>\n <td>...</td>\n <td>...</td>\n </tr>\n <tr>\n <th>9738</th>\n <td>D500</td>\n <td>2012-09-19</td>\n <td>9418.8</td>\n </tr>\n <tr>\n <th>9739</th>\n <td>D500</td>\n <td>2012-09-20</td>\n <td>9365.7</td>\n </tr>\n <tr>\n <th>9740</th>\n <td>D500</td>\n <td>2012-09-21</td>\n <td>9445.9</td>\n </tr>\n <tr>\n <th>9741</th>\n <td>D500</td>\n <td>2012-09-22</td>\n <td>9497.9</td>\n </tr>\n <tr>\n <th>9742</th>\n <td>D500</td>\n <td>2012-09-23</td>\n <td>9545.3</td>\n </tr>\n </tbody>\n</table>\n<p>9743 rows × 3 columns</p>\n</div>\n```\n:::\n:::\n\n\n::: {.cell execution_count=2}\n``` {.python .cell-code}\n# Example 1 - Add 7 lagged values for a single DataFrame object, pandas engine\nlagged_df_single = (\n df \n .query('id == \"D10\"')\n .augment_lags(\n date_column='date',\n value_column='value',\n lags=(1, 7),\n engine='pandas'\n )\n)\nlagged_df_single\n\n# Example 2 - Add a single lagged value of 2 for each GroupBy object, polars engine\nlagged_df = (\n df \n .groupby('id')\n .augment_lags(\n date_column='date',\n value_column='value',\n lags=2,\n engine='polars'\n )\n)\nlagged_df\n```\n\n::: {.cell-output .cell-output-display execution_count=2}\n```{=html}\n<div>\n<style scoped>\n .dataframe tbody tr th:only-of-type {\n vertical-align: middle;\n }\n\n .dataframe tbody tr th {\n vertical-align: top;\n }\n\n .dataframe thead th {\n text-align: right;\n }\n</style>\n<table border=\"1\" class=\"dataframe\">\n <thead>\n <tr style=\"text-align: right;\">\n <th></th>\n <th>id</th>\n <th>date</th>\n <th>value</th>\n <th>value_lag_2</th>\n </tr>\n </thead>\n <tbody>\n <tr>\n <th>0</th>\n <td>D10</td>\n <td>2014-07-03</td>\n <td>2076.2</td>\n <td>NaN</td>\n </tr>\n <tr>\n <th>1</th>\n <td>D10</td>\n <td>2014-07-04</td>\n <td>2073.4</td>\n <td>NaN</td>\n </tr>\n <tr>\n <th>2</th>\n <td>D10</td>\n <td>2014-07-05</td>\n <td>2048.7</td>\n <td>2076.2</td>\n </tr>\n <tr>\n <th>3</th>\n <td>D10</td>\n <td>2014-07-06</td>\n <td>2048.9</td>\n <td>2073.4</td>\n </tr>\n <tr>\n <th>4</th>\n <td>D10</td>\n <td>2014-07-07</td>\n <td>2006.4</td>\n <td>2048.7</td>\n </tr>\n <tr>\n <th>...</th>\n <td>...</td>\n <td>...</td>\n <td>...</td>\n <td>...</td>\n </tr>\n <tr>\n <th>9738</th>\n <td>D500</td>\n <td>2012-09-19</td>\n <td>9418.8</td>\n <td>9437.7</td>\n </tr>\n <tr>\n <th>9739</th>\n <td>D500</td>\n <td>2012-09-20</td>\n <td>9365.7</td>\n <td>9431.9</td>\n </tr>\n <tr>\n <th>9740</th>\n <td>D500</td>\n <td>2012-09-21</td>\n <td>9445.9</td>\n <td>9418.8</td>\n </tr>\n <tr>\n <th>9741</th>\n <td>D500</td>\n <td>2012-09-22</td>\n <td>9497.9</td>\n <td>9365.7</td>\n </tr>\n <tr>\n <th>9742</th>\n <td>D500</td>\n <td>2012-09-23</td>\n <td>9545.3</td>\n <td>9445.9</td>\n </tr>\n </tbody>\n</table>\n<p>9743 rows × 4 columns</p>\n</div>\n```\n:::\n:::\n\n\n::: {.cell execution_count=3}\n``` {.python .cell-code}\n# Example 3 add 2 lagged values, 2 and 4, for a single DataFrame object, pandas engine\nlagged_df_single_two = (\n df \n .query('id == \"D10\"')\n .augment_lags(\n date_column='date',\n value_column='value',\n lags=[2, 4],\n engine='pandas'\n )\n)\nlagged_df_single_two\n```\n\n::: {.cell-output .cell-output-display execution_count=3}\n```{=html}\n<div>\n<style scoped>\n .dataframe tbody tr th:only-of-type {\n vertical-align: middle;\n }\n\n .dataframe tbody tr th {\n vertical-align: top;\n }\n\n .dataframe thead th {\n text-align: right;\n }\n</style>\n<table border=\"1\" class=\"dataframe\">\n <thead>\n <tr style=\"text-align: right;\">\n <th></th>\n <th>id</th>\n <th>date</th>\n <th>value</th>\n <th>value_lag_2</th>\n <th>value_lag_4</th>\n </tr>\n </thead>\n <tbody>\n <tr>\n <th>0</th>\n <td>D10</td>\n <td>2014-07-03</td>\n <td>2076.2</td>\n <td>NaN</td>\n <td>NaN</td>\n </tr>\n <tr>\n <th>1</th>\n <td>D10</td>\n <td>2014-07-04</td>\n <td>2073.4</td>\n <td>NaN</td>\n <td>NaN</td>\n </tr>\n <tr>\n <th>2</th>\n <td>D10</td>\n <td>2014-07-05</td>\n <td>2048.7</td>\n <td>2076.2</td>\n <td>NaN</td>\n </tr>\n <tr>\n <th>3</th>\n <td>D10</td>\n <td>2014-07-06</td>\n <td>2048.9</td>\n <td>2073.4</td>\n <td>NaN</td>\n </tr>\n <tr>\n <th>4</th>\n <td>D10</td>\n <td>2014-07-07</td>\n <td>2006.4</td>\n <td>2048.7</td>\n <td>2076.2</td>\n </tr>\n <tr>\n <th>...</th>\n <td>...</td>\n <td>...</td>\n <td>...</td>\n <td>...</td>\n <td>...</td>\n </tr>\n <tr>\n <th>669</th>\n <td>D10</td>\n <td>2016-05-02</td>\n <td>2630.7</td>\n <td>2572.9</td>\n <td>2579.9</td>\n </tr>\n <tr>\n <th>670</th>\n <td>D10</td>\n <td>2016-05-03</td>\n <td>2649.3</td>\n <td>2601.0</td>\n <td>2544.0</td>\n </tr>\n <tr>\n <th>671</th>\n <td>D10</td>\n <td>2016-05-04</td>\n <td>2631.8</td>\n <td>2630.7</td>\n <td>2572.9</td>\n </tr>\n <tr>\n <th>672</th>\n <td>D10</td>\n <td>2016-05-05</td>\n <td>2622.5</td>\n <td>2649.3</td>\n <td>2601.0</td>\n </tr>\n <tr>\n <th>673</th>\n <td>D10</td>\n <td>2016-05-06</td>\n <td>2620.1</td>\n <td>2631.8</td>\n <td>2630.7</td>\n </tr>\n </tbody>\n</table>\n<p>674 rows × 5 columns</p>\n</div>\n```\n:::\n:::\n\n\n",
0 commit comments