[FEAT] Simulate and explain

[elephaint]

Adds endpoints:

• simulate — generate temporally correlated sample paths (Schaake shuffle), with optional cross-series coupling (multivariate=True), custom quantile grids, seeds, and partitioned requests.
• explain — model-independent historical feature importance via Granger causality or transfer entropy.
• forecast — new feature_contributions_type parameter (shapley/intervention/granger/transfer_entropy).
• Fixes a silent future-exogenous misalignment bug; X_df is now strictly validated (exactly one row per future (id, time) pair — previously oversized frames were accepted).
• Docs, tutorials, and notebooks for both endpoints; extensive offline test suites.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
unused	🟢 Ready	View Preview	Aug 4, 2026, 9:46 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
nixtla_io_docs	🟢 Ready	View Preview	Aug 4, 2026, 9:47 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[elessar-for-github]

Changes made by this pull request:

.gitignore
[Error processing diff]

nixtla/nixtla_client.py
[Error processing diff]

nixtla_tests/docs/test_simulate_explain_docs.py
[Error processing diff]

nixtla_tests/nixtla_client/test_explain.py
[Error processing diff]

nixtla_tests/nixtla_client/test_feature_contribution_types.py
[Error processing diff]

nixtla_tests/nixtla_client/test_simulate.py
[Error processing diff]

pyproject.toml
[Error processing diff]

timegpt-docs/docs.json
[Error processing diff]

timegpt-docs/forecasting/exogenous-variables/causal-explanations.mdx
[Error processing diff]

timegpt-docs/forecasting/exogenous-variables/interpretability_with_shap.mdx
[Error processing diff]

timegpt-docs/forecasting/explanation/advanced-explanations.mdx
[Error processing diff]

timegpt-docs/forecasting/explanation/intervention.mdx
[Error processing diff]

timegpt-docs/forecasting/explanation/introduction.mdx
[Error processing diff]

timegpt-docs/forecasting/fine-tuning/save_reuse_delete_finetuned_models.mdx
[Error processing diff]

timegpt-docs/forecasting/probabilistic/introduction.mdx
[Error processing diff]

timegpt-docs/forecasting/probabilistic/quantiles.mdx
[Error processing diff]

timegpt-docs/forecasting/probabilistic/simulation.mdx
[Error processing diff]

timegpt-docs/openapi.json
[Error processing diff]

timegpt-docs/reference/sdk_reference.mdx
[Error processing diff]

[github-actions]

Experiment Results

Experiment 1: air-passengers

Description:

variable	experiment
h	12
season_length	12
freq	MS
level	None
n_windows	1

Results:

metric	timegpt-1	timegpt-1-long-horizon	SeasonalNaive	Naive
mae	12.6793	11.0623	47.8333	76
mape	0.027	0.0232	0.0999	0.1425
mse	213.936	199.132	2571.33	10604.2
total_time	32.6921	5.1848	0.0043	0.0031

Plot:

Experiment 2: air-passengers

Description:

variable	experiment
h	24
season_length	12
freq	MS
level	None
n_windows	1

Results:

metric	timegpt-1	timegpt-1-long-horizon	SeasonalNaive	Naive
mae	58.1031	58.4587	71.25	115.25
mape	0.1257	0.1267	0.1552	0.2358
mse	4040.21	4110.79	5928.17	18859.2
total_time	5.3495	0.6303	0.0036	0.0032

Plot:

Experiment 3: electricity-multiple-series

Description:

variable	experiment
h	24
season_length	24
freq	H
level	None
n_windows	1

Results:

metric	timegpt-1	timegpt-1-long-horizon	SeasonalNaive	Naive
mae	178.293	268.13	269.23	1331.02
mape	0.0234	0.0311	0.0304	0.1692
mse	121589	219485	213677	4.68961e+06
total_time	1.179	5.0869	0.0043	0.004

Plot:

Experiment 4: electricity-multiple-series

Description:

variable	experiment
h	168
season_length	24
freq	H
level	None
n_windows	1

Results:

metric	timegpt-1	timegpt-1-long-horizon	SeasonalNaive	Naive
mae	465.497	346.972	398.956	1119.26
mape	0.062	0.0436	0.0512	0.1583
mse	835021	403760	656723	3.17316e+06
total_time	4.338	1.7457	0.0046	0.0042

Plot:

Experiment 5: electricity-multiple-series

Description:

variable	experiment
h	336
season_length	24
freq	H
level	None
n_windows	1

Results:

metric	timegpt-1	timegpt-1-long-horizon	SeasonalNaive	Naive
mae	558.673	459.757	602.926	1340.95
mape	0.0697	0.0565	0.0787	0.17
mse	1.22723e+06	739114	1.61572e+06	6.04619e+06
total_time	0.8559	1.3675	0.0048	0.0043

Plot:

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[marcopeix]

If you look at the preview, some icons do not render in Mintlify, not sure why. Other than that, the new documentation looks really good!