{"id":2348,"library":"utilsforecast","title":"Utilsforecast: Forecasting Utilities for Time Series","description":"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.","status":"active","version":"0.2.15","language":"en","source_language":"en","source_url":"https://github.com/Nixtla/utilsforecast","tags":["forecasting","time series","utilities","data preprocessing","evaluation","plotting","nixtla"],"install":[{"cmd":"pip install utilsforecast","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge utilsforecast","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false},{"reason":"Core data structures and time series operations.","package":"pandas","optional":false},{"reason":"Numerical operations, often used internally.","package":"numpy","optional":false}],"imports":[{"symbol":"fill_gaps","correct":"from utilsforecast.preprocessing import fill_gaps"},{"symbol":"evaluate","correct":"from utilsforecast.evaluation import evaluate"},{"symbol":"mape","correct":"from utilsforecast.losses import mape"},{"symbol":"generate_series","correct":"from utilsforecast.data import generate_series"},{"symbol":"plot_series","correct":"from utilsforecast.plotting import plot_series"}],"quickstart":{"code":"import pandas as pd\nimport numpy as np\nfrom utilsforecast.data import generate_series\nfrom utilsforecast.preprocessing import fill_gaps\nfrom utilsforecast.evaluation import evaluate\nfrom utilsforecast.losses import mape, mse\nfrom functools import partial\n\n# 1. Generate synthetic data with some missing values\nseries = generate_series(n_series=3, max_length=50, equal_ends=True, seed=42)\n# Introduce some gaps for demonstration\nmis_idx = np.random.choice(series.index, size=int(len(series) * 0.1), replace=False)\nseries_with_gaps = series.drop(mis_idx)\n\n# 2. Fill missing values\nfilled_series = fill_gaps(series_with_gaps, freq='D')\nprint(\"Original series head (with gaps if any):\")\nprint(series_with_gaps.head())\nprint(\"\\nFilled series head:\")\nprint(filled_series.head())\n\n# 3. Prepare data for evaluation (example with dummy models)\n# Assume 'y_true' is the actual target and 'model1', 'model2' are predictions\n# For demonstration, we'll create a dummy 'y' and then 'predictions'\nfilled_series['y_true'] = filled_series['y']\nfilled_series['model1'] = filled_series['y_true'] * np.random.uniform(0.9, 1.1, len(filled_series))\nfilled_series['model2'] = filled_series['y_true'] * np.random.uniform(0.8, 1.2, len(filled_series))\n\n# Split into train and validation (simplified for quickstart)\nhorizon = 7\nvalid_df = filled_series.groupby('unique_id').tail(horizon).copy()\ntrain_df = filled_series.drop(valid_df.index).copy()\n\n# Ensure target column for evaluation matches original 'y'\nvalid_df['y'] = valid_df['y_true']\ntrain_df['y'] = train_df['y_true']\n\n# 4. Evaluate dummy models\n# Mase requires a training set to compute the scaling factor\ndummy_mase = partial(mse, seasonality=1)\nmetrics_df = evaluate(valid_df, metrics=[mape, dummy_mase], train_df=train_df)\nprint(\"\\nEvaluation Results:\")\nprint(metrics_df.head())\n","lang":"python","description":"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`."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or a later version.","message":"Python 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.","severity":"breaking","affected_versions":">=0.2.12"},{"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.","message":"Scaled 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.","severity":"gotcha","affected_versions":"<0.2.15"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"<0.2.12"},{"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.","message":"Version 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.","severity":"deprecated","affected_versions":"<0.2.10"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}