utilsforecast

Install

PyPI

pip install utilsforecast

Conda

conda install -c conda-forge utilsforecast

How to use

Generate synthetic data

from utilsforecast.data import generate_series

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

|     | unique_id | ds         | y          |
|-----|-----------|------------|------------|
| 0   | 0         | 2000-01-01 | 0.422133   |
| 1   | 0         | 2000-01-02 | 1.501407   |
| 2   | 0         | 2000-01-03 | 2.568495   |
| 3   | 0         | 2000-01-04 | 3.529085   |
| 4   | 0         | 2000-01-05 | 4.481929   |
| ... | ...       | ...        | ...        |
| 481 | 2         | 2000-06-11 | 163.914625 |
| 482 | 2         | 2000-06-12 | 166.018479 |
| 483 | 2         | 2000-06-13 | 160.839176 |
| 484 | 2         | 2000-06-14 | 162.679603 |
| 485 | 2         | 2000-06-15 | 165.089288 |

Plotting

from utilsforecast.plotting import plot_series

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

Preprocessing

from utilsforecast.preprocessing import fill_gaps

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

Example output with missing dates:

|     | unique_id | ds         | y         |
|-----|-----------|------------|-----------|
| 213 | 0         | 2000-08-01 | 18.543147 |
| 214 | 0         | 2000-08-02 | 19.941764 |
| 216 | 0         | 2000-08-04 | 21.968733 |
| 220 | 0         | 2000-08-08 | 19.091509 |
| 221 | 0         | 2000-08-09 | 20.220739 |

fill_gaps(with_gaps, freq='D')

Returns:

|     | unique_id | ds         | y         |
|-----|-----------|------------|-----------|
| 0   | 0         | 2000-08-01 | 18.543147 |
| 1   | 0         | 2000-08-02 | 19.941764 |
| 2   | 0         | 2000-08-03 | NaN       |
| 3   | 0         | 2000-08-04 | 21.968733 |
| 4   | 0         | 2000-08-05 | NaN       |
| 5   | 0         | 2000-08-06 | NaN       |
| 6   | 0         | 2000-08-07 | NaN       |
| 7   | 0         | 2000-08-08 | 19.091509 |
| 8   | 0         | 2000-08-09 | 20.220739 |

Evaluating

from functools import partial
import numpy as np

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

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)

|     | unique_id | metric | seas_naive | rand_model |
|-----|-----------|--------|------------|------------|
| 0   | 0         | mape   | 0.024139   | 0.440173   |
| 1   | 1         | mape   | 0.054259   | 0.278123   |
| 2   | 2         | mape   | 0.042642   | 0.480316   |
| 3   | 0         | mase   | 0.907149   | 16.418014  |
| 4   | 1         | mase   | 0.991635   | 6.404254   |
| 5   | 2         | mase   | 1.013596   | 11.365040  |

Release files for utilsforecast 0.2.16

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for utilsforecast 0.2.16
File	Size	Uploaded
utilsforecast-0.2.16.tar.gz	72.2 kB	Apr 27, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for utilsforecast 0.2.16
File	Interpreter	ABI	Platform	Reset
utilsforecast-0.2.16-py3-none-any.whl 46.6 kB Apr 27, 2026	Python 3	none	any	Details

Total release size: 118.8 kB

Release files / utilsforecast-0.2.16.tar.gz

Download URL	utilsforecast-0.2.16.tar.gz
Size	72.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`dca406231d002279562ae897dbcb9e419c2fc5bf48908be02834b3187ce5a52b`
BLAKE2b-256 checksum How to use checksums	`15f8c6be49b618e974f07a3d05f578344a9e38cc793fb2b1ff0baf1988cb2e59`
Upload date	Apr 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Nixtla/utilsforecast
Publishing commit: github.com/Nixtla/utilsforecast/tree/ce2c7ddc7b71228ece21edf72ef9567d7467c0ab

Workflow

Publishing configuration: github.com/Nixtla/utilsforecast/blob/ce2c7ddc7b71228ece21edf72ef9567d7467c0ab/.github/workflows/release.yml
Publishing logs: github.com/Nixtla/utilsforecast/actions/runs/25022009145/attempts/1

Artifact

Subject: utilsforecast-0.2.16.tar.gz
SHA-256 checksum: dca406231d002279562ae897dbcb9e419c2fc5bf48908be02834b3187ce5a52b Verifying attestations

Release files / utilsforecast-0.2.16-py3-none-any.whl

Download URL	utilsforecast-0.2.16-py3-none-any.whl
Size	46.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`985e7bbe999cd2c27e331c5c49e8b7934c617f3df0b933c105fbe71dae0283ed`
BLAKE2b-256 checksum How to use checksums	`fa5c3628953eba90eb2f3b73958354c3f3cfd9e70cfb8370c9729b81aa7b237a`
Upload date	Apr 27, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Nixtla/utilsforecast
Publishing commit: github.com/Nixtla/utilsforecast/tree/ce2c7ddc7b71228ece21edf72ef9567d7467c0ab

Workflow

Publishing configuration: github.com/Nixtla/utilsforecast/blob/ce2c7ddc7b71228ece21edf72ef9567d7467c0ab/.github/workflows/release.yml
Publishing logs: github.com/Nixtla/utilsforecast/actions/runs/25022009145/attempts/1

Artifact

Subject: utilsforecast-0.2.16-py3-none-any.whl
SHA-256 checksum: 985e7bbe999cd2c27e331c5c49e8b7934c617f3df0b933c105fbe71dae0283ed Verifying attestations