Skip to content

[FEAT] Simulate method for sample trajectories - #1072

Merged
Saul (nasaul) merged 14 commits into
Nixtla:mainfrom
ankitlade12:feature/simulate-trajectories
Feb 3, 2026
Merged

Saul (nasaul) merged 14 commits into
Nixtla:mainfrom
ankitlade12:feature/simulate-trajectories

Conversation

@ankitlade12

@ankitlade12 Ankit Hemant Lade (ankitlade12) commented Jan 2, 2026 •

Copy link
Copy Markdown
Contributor

Description

This PR significantly expands the simulate method capabilities across the StatsForecast library. Beyond providing basic sample trajectories, it now supports a wide range of error distributions, enabling high-fidelity probabilistic forecasting and robust scenario analysis.

This implementation centralizes simulation logic, improves model accuracy by incorporating historical residuals, and ensures high consistency across the model library.

Key Changes

  • Advanced Error Distributions:
    • Introduced a centralized statsforecast/simulation.py utility for sampling from multiple distributions: normal, t (Student's t), bootstrap (empirical), laplace, skew-normal, and ged (Generalized Error Distribution).
    • Implemented calibrated variance scaling for all distributions to ensure generated noise matches the model's estimated sigma.
  • Expanded Model Coverage:
    • Smoothing Models: Added simulate methods and analytic prediction intervals to SimpleExponentialSmoothing (Standard & Optimized) and SeasonalExponentialSmoothing (Standard & Optimized).
    • Averaging & Drift Models: Implemented simulate for HistoricAverage, RandomWalkWithDrift, and WindowAverage.
    • Stored Residuals: Updated fit methods across all models to calculate and store residuals and sigma, enabling non-parametric bootstrap simulation support.
  • Improved API & Core Engine:
    • Enhanced StatsForecast.simulate and GroupedArray.simulate to propagate error_distribution and error_params through the hierarchy.
    • Full support for parallel execution (n_jobs) with reproducible seeding for all distributions.

Verification

  • Automated Tests: Added tests/test_simulation_distributions.py covering:
    • High-level StatsForecast API simulations.
    • Individual model-level simulate implementations.
    • Reproducibility across seeds and parallel execution.
    • Bootstrap accuracy using historical residuals.
  • Test Execution: Ran pytest tests/test_simulation_distributions.py — All 5 tests passed.

Checklist

  • I have followed the Conventional Commits style for commit messages.
  • I have added docstrings following the Google style.
  • I have added tests to cover my changes.
  • I have verified that all tests pass.
  • I have run ruff to ensure compliance with the project's style.

@CLAassistant

CLAassistant commented Jan 2, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@MMenchero

Copy link
Copy Markdown
Contributor

Thank you for your contribution Ankit Hemant Lade (@ankitlade12) We'll currently reviewing it and will get back to you soon.

…cross models

- Added statsforecast/simulation.py for centralized error sampling.
- Updated AutoARIMA, AutoETS, AutoCES, AutoTheta to support multiple error distributions.
- Added simulate() and analytic prediction intervals to SimpleExponentialSmoothing and SeasonalExponentialSmoothing.
- Added simulate() to HistoricAverage, RandomWalkWithDrift, and WindowAverage.
- ensured residuals and sigma are stored after fit() for all models to support bootstrap simulation.
- Cleaned up conversational comments and polished code for production readiness.
- Added comprehensive test suite for multi-distribution simulations.
@codspeed

codspeed Bot commented Jan 27, 2026 •

Copy link
Copy Markdown

CodSpeed Performance Report

Merging this PR will not alter performance

Comparing ankitlade12:feature/simulate-trajectories (a4edaf4) with main (fba5c90)

Summary

✅ 6 untouched benchmarks

@MMenchero

Copy link
Copy Markdown
Contributor

Hey Ankit Hemant Lade (@ankitlade12), thanks for expanding your PR. These are the additional features we were planning to ask for. Saul (@nasaul) will review them, and hopefully they’ll be merged into main in the coming days. Thanks for your patience!

@nasaul Saul (nasaul) linked an issue Jan 29, 2026 that may be closed by this pull request
@nasaul Saul (nasaul) changed the title feat: implement simulate method for sample trajectories [FEAT] Simulate method for sample trajectories Jan 29, 2026

@nasaul Saul (nasaul) left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR is a great contribution for the open source, thanks for this. I've fixed a little of the issues that were raised in the CI/Pytests checks. Some minor things must be addressed before merging:

  • Can you add a warning for large simulations?
  • Can you add a tutorial demonstrating the new feature?

There are some CI failures still that are not related to this and should be addressed in #1080 so we'll need that merged before this one.

@review-notebook-app

Copy link
Copy Markdown

Check out this pull request on  ReviewNB

See visual diffs & provide feedback on Jupyter Notebooks.


Powered by ReviewNB

@nasaul
Saul (nasaul) enabled auto-merge (squash) February 3, 2026 22:59

@nasaul Saul (nasaul) left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@nasaul
Saul (nasaul) merged commit 0621049 into Nixtla:main Feb 3, 2026
57 checks passed
Junghwan (shaun0927) added a commit to shaun0927/statsforecast that referenced this pull request Apr 17, 2026
UCM stored model_["sigma"] but no method (predict, predict_in_sample,
forecast) read it; intervals come from statsmodels `forecast.conf_int`
directly, and UCM does not implement `simulate()`. The local
_calculate_sigma also shadowed statsforecast.utils._calculate_sigma
with a different denominator (max(n-1, 1) instead of the convention
n - n_params used by the 30+ call sites in models.py). A follow-up
can wire UCM into the simulate API from Nixtla#1072 if/when that's planned.
Junghwan (shaun0927) added a commit to shaun0927/statsforecast that referenced this pull request Sep 25, 2026
UCM stored model_["sigma"] but no method (predict, predict_in_sample,
forecast) read it; intervals come from statsmodels `forecast.conf_int`
directly, and UCM does not implement `simulate()`. The local
_calculate_sigma also shadowed statsforecast.utils._calculate_sigma
with a different denominator (max(n-1, 1) instead of the convention
n - n_params used by the 30+ call sites in models.py). A follow-up
can wire UCM into the simulate API from Nixtla#1072 if/when that's planned.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support for generating sample trajectories

4 participants