Metadata-Version: 2.1
Name: utilsforecast
Version: 0.0.4
Summary: Forecasting utilities
Home-page: https://github.com/Nixtla/utilsforecast
Author: Nixtla
Author-email: business@nixtla.io
License: Apache Software License 2.0
Keywords: time-series analysis forecasting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas >=1.1.1
Provides-Extra: dev
Requires-Dist: matplotlib ; extra == 'dev'
Requires-Dist: plotly ; extra == 'dev'
Requires-Dist: polars ; extra == 'dev'
Provides-Extra: plotting
Requires-Dist: matplotlib ; extra == 'plotting'
Requires-Dist: plotly ; extra == 'plotting'
Requires-Dist: plotly-resampler ; extra == 'plotting'

utilsforecast
================

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Install

``` sh
pip install utilsforecast
```

## How to use

### Generate synthetic data

``` python
from utilsforecast.data import generate_series
```

``` python
series = generate_series(3, with_trend=True, static_as_categorical=False)
series
```

<div>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>unique_id</th>
      <th>ds</th>
      <th>y</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>0</th>
      <td>0</td>
      <td>2000-01-01</td>
      <td>0.422133</td>
    </tr>
    <tr>
      <th>1</th>
      <td>0</td>
      <td>2000-01-02</td>
      <td>1.501407</td>
    </tr>
    <tr>
      <th>2</th>
      <td>0</td>
      <td>2000-01-03</td>
      <td>2.568495</td>
    </tr>
    <tr>
      <th>3</th>
      <td>0</td>
      <td>2000-01-04</td>
      <td>3.529085</td>
    </tr>
    <tr>
      <th>4</th>
      <td>0</td>
      <td>2000-01-05</td>
      <td>4.481929</td>
    </tr>
    <tr>
      <th>...</th>
      <td>...</td>
      <td>...</td>
      <td>...</td>
    </tr>
    <tr>
      <th>481</th>
      <td>2</td>
      <td>2000-06-11</td>
      <td>163.914625</td>
    </tr>
    <tr>
      <th>482</th>
      <td>2</td>
      <td>2000-06-12</td>
      <td>166.018479</td>
    </tr>
    <tr>
      <th>483</th>
      <td>2</td>
      <td>2000-06-13</td>
      <td>160.839176</td>
    </tr>
    <tr>
      <th>484</th>
      <td>2</td>
      <td>2000-06-14</td>
      <td>162.679603</td>
    </tr>
    <tr>
      <th>485</th>
      <td>2</td>
      <td>2000-06-15</td>
      <td>165.089288</td>
    </tr>
  </tbody>
</table>
<p>486 rows × 3 columns</p>
</div>

### Plotting

``` python
from utilsforecast.plotting import plot_series
```

``` python
fig = plot_series(series, plot_random=False, max_insample_length=50, engine='matplotlib')
fig.savefig('imgs/index.png', bbox_inches='tight')
```

![](https://raw.githubusercontent.com/Nixtla/utilsforecast/main/nbs/imgs/index.png)

### Preprocessing

``` python
from utilsforecast.preprocessing import fill_gaps
```

``` python
serie = series[series['unique_id'].eq(0)].tail(10)
# drop some points
with_gaps = serie.sample(frac=0.5, random_state=0).sort_values('ds')
with_gaps
```

<div>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>unique_id</th>
      <th>ds</th>
      <th>y</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>213</th>
      <td>0</td>
      <td>2000-08-01</td>
      <td>18.543147</td>
    </tr>
    <tr>
      <th>214</th>
      <td>0</td>
      <td>2000-08-02</td>
      <td>19.941764</td>
    </tr>
    <tr>
      <th>216</th>
      <td>0</td>
      <td>2000-08-04</td>
      <td>21.968733</td>
    </tr>
    <tr>
      <th>220</th>
      <td>0</td>
      <td>2000-08-08</td>
      <td>19.091509</td>
    </tr>
    <tr>
      <th>221</th>
      <td>0</td>
      <td>2000-08-09</td>
      <td>20.220739</td>
    </tr>
  </tbody>
</table>
</div>

``` python
fill_gaps(with_gaps, freq='D')
```

<div>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>unique_id</th>
      <th>ds</th>
      <th>y</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>0</th>
      <td>0</td>
      <td>2000-08-01</td>
      <td>18.543147</td>
    </tr>
    <tr>
      <th>1</th>
      <td>0</td>
      <td>2000-08-02</td>
      <td>19.941764</td>
    </tr>
    <tr>
      <th>2</th>
      <td>0</td>
      <td>2000-08-03</td>
      <td>NaN</td>
    </tr>
    <tr>
      <th>3</th>
      <td>0</td>
      <td>2000-08-04</td>
      <td>21.968733</td>
    </tr>
    <tr>
      <th>4</th>
      <td>0</td>
      <td>2000-08-05</td>
      <td>NaN</td>
    </tr>
    <tr>
      <th>5</th>
      <td>0</td>
      <td>2000-08-06</td>
      <td>NaN</td>
    </tr>
    <tr>
      <th>6</th>
      <td>0</td>
      <td>2000-08-07</td>
      <td>NaN</td>
    </tr>
    <tr>
      <th>7</th>
      <td>0</td>
      <td>2000-08-08</td>
      <td>19.091509</td>
    </tr>
    <tr>
      <th>8</th>
      <td>0</td>
      <td>2000-08-09</td>
      <td>20.220739</td>
    </tr>
  </tbody>
</table>
</div>

### Evaluating

``` python
from functools import partial

import numpy as np

from utilsforecast.evaluation import evaluate
from utilsforecast.losses import mape, mase
```

``` python
valid = series.groupby('unique_id').tail(7).copy()
train = series.drop(valid.index)
rng = np.random.RandomState(0)
valid['seas_naive'] = train.groupby('unique_id')['y'].tail(7).values
valid['rand_model'] = valid['y'] * rng.rand(valid['y'].shape[0])
daily_mase = partial(mase, seasonality=7)
evaluate(valid, metrics=[mape, daily_mase], train_df=train)
```

<div>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>unique_id</th>
      <th>metric</th>
      <th>seas_naive</th>
      <th>rand_model</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>0</th>
      <td>0</td>
      <td>mape</td>
      <td>0.024139</td>
      <td>0.440173</td>
    </tr>
    <tr>
      <th>1</th>
      <td>1</td>
      <td>mape</td>
      <td>0.054259</td>
      <td>0.278123</td>
    </tr>
    <tr>
      <th>2</th>
      <td>2</td>
      <td>mape</td>
      <td>0.042642</td>
      <td>0.480316</td>
    </tr>
    <tr>
      <th>0</th>
      <td>0</td>
      <td>mase</td>
      <td>0.907149</td>
      <td>16.418014</td>
    </tr>
    <tr>
      <th>1</th>
      <td>1</td>
      <td>mase</td>
      <td>0.991635</td>
      <td>6.404254</td>
    </tr>
    <tr>
      <th>2</th>
      <td>2</td>
      <td>mase</td>
      <td>1.013596</td>
      <td>11.365040</td>
    </tr>
  </tbody>
</table>
</div>
