Registry / data / utilsforecast

utilsforecast

JSON →
library0.2.16pypypi✓ verified 25d ago

Utilsforecast provides essential helper functions for time series forecasting workflows, forming a core part of the Nixtlaverse ecosystem alongside libraries like StatsForecast, MLForecast, and NeuralForecast. It offers utilities for data preprocessing, feature engineering, evaluation, and plotting. The library is actively maintained with frequent releases, typically addressing bug fixes, performance enhancements, and new metric/feature additions.

pip install utilsforecast
INSTALL
IMPORT
SIG · UTILSFORECAST
U
utilsforecast
datapythonv0.2.16
Install
8.7s avg
Import
944ms
Disk
176MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.2.16 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.962s · 170.5MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 8.7s · import 0.926s · 163MB
176MB installed
● package 176MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

fill_gaps
from utilsforecast.preprocessing import fill_gaps
evaluate
from utilsforecast.evaluation import evaluate
mape
from utilsforecast.losses import mape
generate_series
from utilsforecast.data import generate_series
plot_series
from utilsforecast.plotting import plot_series

This quickstart demonstrates how to generate synthetic time series data, fill in artificial gaps using `fill_gaps`, and then evaluate simple dummy forecasts using common metrics like MAPE and MSE with `evaluate`.

import pandas as pd import numpy as np from utilsforecast.data import generate_series from utilsforecast.preprocessing import fill_gaps from utilsforecast.evaluation import evaluate from utilsforecast.losses import mape, mse from functools import partial # 1. Generate synthetic data with some missing values series = generate_series(n_series=3, max_length=50, equal_ends=True, seed=42) # Introduce some gaps for demonstration mis_idx = np.random.choice(series.index, size=int(len(series) * 0.1), replace=False) series_with_gaps = series.drop(mis_idx) # 2. Fill missing values filled_series = fill_gaps(series_with_gaps, freq='D') print("Original series head (with gaps if any):") print(series_with_gaps.head()) print("\nFilled series head:") print(filled_series.head()) # 3. Prepare data for evaluation (example with dummy models) # Assume 'y_true' is the actual target and 'model1', 'model2' are predictions # For demonstration, we'll create a dummy 'y' and then 'predictions' filled_series['y_true'] = filled_series['y'] filled_series['model1'] = filled_series['y_true'] * np.random.uniform(0.9, 1.1, len(filled_series)) filled_series['model2'] = filled_series['y_true'] * np.random.uniform(0.8, 1.2, len(filled_series)) # Split into train and validation (simplified for quickstart) horizon = 7 valid_df = filled_series.groupby('unique_id').tail(horizon).copy() train_df = filled_series.drop(valid_df.index).copy() # Ensure target column for evaluation matches original 'y' valid_df['y'] = valid_df['y_true'] train_df['y'] = train_df['y_true'] # 4. Evaluate dummy models # Mase requires a training set to compute the scaling factor dummy_mase = partial(mse, seasonality=1) metrics_df = evaluate(valid_df, metrics=[mape, dummy_mase], train_df=train_df) print("\nEvaluation Results:") print(metrics_df.head())
Debug
Known issues
breakingPython 3.8 support was dropped in version 0.2.12. Users on Python 3.8 will need to upgrade their Python environment to 3.9 or newer to use versions 0.2.12 and above.
fix
Upgrade your Python environment to 3.9 or a later version.
affects: >=0.2.12
gotchaScaled metric computations (e.g., RMSSE) were corrected in version 0.2.15. Prior versions might have computed these metrics against an incorrect denominator, leading to potentially misleading evaluation results.
fix
Update to version 0.2.15 or newer to ensure correct scaled metric calculations. Review any custom scaled metric implementations if you were working around previous inaccuracies.
affects: <0.2.15
gotchaThe `fill_gaps` function received a fix in version 0.2.12 to validate the `freq` parameter with the input data. Incorrect `freq` values might have caused silent issues or errors in earlier versions.
fix
Ensure the `freq` parameter passed to `fill_gaps` accurately reflects the frequency of your time series data. Update to version 0.2.12 or newer for improved validation.
affects: <0.2.12
deprecatedVersion 0.2.10 addressed Pandas frequency alias deprecations within `generate_series`. While not immediately breaking, reliance on deprecated Pandas aliases might lead to future warnings or errors with newer Pandas versions.
fix
Update to version 0.2.10 or newer. Ensure your Pandas version is up-to-date and be aware of changes in frequency alias conventions within Pandas documentation.
affects: <0.2.10
Errors
Common errors & fixes
ImportError: cannot import name 'mae' from 'utilsforecast.losses'
You are trying to import a specific loss function directly from the `utilsforecast.losses` module, which instead contains backend-specific submodules like `numpy` or `torch`, or the metric might be in `utilsforecast.metrics`.
fix
Import `mae` from `utilsforecast.metrics` for evaluation metrics or `utilsforecast.losses.numpy` (or `torch`) for specific loss functions, e.g., `from utilsforecast.metrics import mae` or `from utilsforecast.losses.numpy import mae`.
KeyError: "['unique_id', 'ds', 'y']"
Utilsforecast functions expect input DataFrames to have specific column names: `unique_id` for series identifiers, `ds` for timestamps, and `y` for target values, and these columns were not found.
fix
Rename your DataFrame columns to `unique_id`, `ds`, and `y` before passing them to utilsforecast functions, e.g., `df = df.rename(columns={'series_id': 'unique_id', 'timestamp_col': 'ds', 'target_value': 'y'})`.
AttributeError: 'DataFrame' object has no attribute 'group_by_cols'
You are attempting to call `group_by_cols` as a method on a Pandas DataFrame, but it is a standalone function imported from `utilsforecast.data`.
fix
Import `group_by_cols` from `utilsforecast.data` and pass your DataFrame as an argument, e.g., `from utilsforecast.data import group_by_cols; grouped_df = group_by_cols(df, ['unique_id'])`.
ValueError: The 'ds' column must be a datetime object or a string that can be parsed as a datetime.
The 'ds' (datestamp) column in your DataFrame is not of a datetime type and cannot be automatically parsed into a valid datetime format by utilsforecast functions.
fix
Convert the 'ds' column to a datetime format using Pandas, e.g., `df['ds'] = pd.to_datetime(df['ds'])` before using the DataFrame with utilsforecast functions.
Upgrade
Version history
0.2.16latest on PyPI · released Apr 27, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.
pandasrequiredCore data structures and time series operations.
numpyrequiredNumerical operations, often used internally.
Agent activity
32 hits · last 30 days
node
26
OpenAI (training)
1
Resources
utilsforecast — pip install utilsforecast · libregistry