feat!: graduate StateSpaceTimeSeries

[anevolbap]

Part of #982, of #758 (P0) and of #696. Milestone 1.1.0. Targets pymc6_and_pymcmarketing1_migration for now and lands on main after 1.0.0rc1; rebased on the current migration tip after #1112 merged, so the diff is this PR's 11 commits only.

• Remove the FutureWarning from StateSpaceTimeSeries.
• BayesianBasisExpansionTimeSeries is unchanged. It stays experimental and keeps its FutureWarning, per review. A test pins that.
• Edge-case guards and tests: short series, level_order below 1, seasonal_length below 2, missing values in y (the Kalman filter imputes them natively, which covers the P2 item of Feature parity with Google's CausalImpact #758 for this model), integer-index error path, and a warning when out-of-sample dates do not continue the training frequency. The missing-value test is correctness-marked so it runs against real NUTS: asserting that a posterior is finite says nothing against the suite's mocked pm.sample.
• Two fixes to what the graduated model emits. It recovers the frequency of a regularly spaced training index, which rebuilding the index from raw values was dropping, so pymc-extras no longer warns about a missing frequency on every fit. And it builds the state-space model with verbose=False, so construction no longer prints the pymc-extras "Model Requirements" table, which tells the reader to declare priors this class declares itself.
• New notebook interrupted-time-series-bsts.ipynb: trend and seasonality, then covariates, then spike-and-slab with inclusion probabilities. Added to gallery.yaml.
• Document the smoothed-posterior R2 caveat on score().
• Release note in a new .github/release-drafts/1.1.0.md, in the format of the rc1 draft, covering the removed warning and the new seasonal_length and level_order ValueErrors. The rc1 draft is untouched since this PR is not in that release.

Three items from #982 are deliberately not here, since each is a separate behavior change worth its own review: making StateSpaceTimeSeries the default model for InterruptedTimeSeries, exporting it at top level, and adding a cp.InterruptedTimeSeries(data, treatment_time) convenience entry point. The first depends on data-scaled priors (#935). The np.ndarray signature item listed in #982 is already stale: both time-series models take xr.DataArray today, and InterruptedTimeSeries dispatches on PyMCModel against RegressorMixin, not on the model class.

One gap worth naming: #758 and #982 both list "no seasonality" as an edge case to test, and no such path exists. build_model always adds a seasonal component, and pymc-extras ships no identity component, so the seasonal_length guard now says that plainly instead of pointing at a seasonality_component workaround that does not produce a seasonality-free model. A real trend-only option is a separate change if you want it.

Note for reviewers: score() is computed on smoothed in-sample predictions, so it reads optimistic relative to other models. Documented, not changed here.

On the notebook: it is honest about what the demo shows rather than overselling it. With 30 post-period days and diffuse default priors, the trend-only model does not identify the effect (95% interval includes zero, posterior probability of an increase around 0.75). Adding x1 and x2 tightens the interval substantially and raises that probability to about 0.87, but the effect is still not credibly non-zero at the 95% level. The plot titles report a Bayesian R² of 1 on the pre-period; the notebook explains that this comes from the Kalman smoother conditioning on the observed outcome and is not a measure of fit. The beta_exog posterior means sit on the true 2.0 and -1.5 while the individual 94% HDIs span zero, because the state-space level and the regressors compete for the same variation. In the selection example the two real predictors take the top two inclusion places but nothing clears 0.5, so the notebook tells the reader to use the ordering and not the level. If you would rather the notebook demonstrate a clean detection, the setup needs a change (shorter horizon, level_order=1, or data-scaled priors) and I will make it.

Verified locally with pymc 6.2.0, arviz 1.2.0, pymc-extras 0.14.0 on the rebased head: 2592 passed, 20 skipped, 6 deselected; the correctness lane 5 passed; diff-cover against pymc6_and_pymcmarketing1_migration covers 100% of the 10 changed executable lines; mypy clean; prek run --all-files clean; doctests for pymc_models.py 8 passed. The notebook calls .fit() on its three experiments and runs end to end under the mock runner (runner.py --notebook, 16 cells). Its stored outputs come from the earlier full run (runner.py --full, no mocks) and were not regenerated. The selection model reports rhat above 1.01, which is inherent to a spike-and-slab posterior rather than a sampling setup problem, so the notebook says so and points the reader at the inclusion probabilities; the covariate model shows 2 divergences. Sampling is not bit-reproducible across runs even with random_seed set, so the notebook prose avoids quoting values that drift.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[read-the-docs-community]

Documentation build overview

📚 causalpy | 🛠️ Build #34808778 | 📁 Comparing bc57466 against latest (7e23946)

  🔍 Preview build  

854 files changed · + 146 added · ± 677 modified · - 31 deleted

+ Added

• notebooks/interrupted-time-series-bsts.html
• notebooks/up-down-control-geolift-pymc.html
• _modules/causalpy/custom_exceptions.html
• _modules/causalpy/input_data.html
• _modules/causalpy/reporting.html
• _modules/causalpy/utils.html
• api/generated/causalpy.checks.operating_characteristics.html
• api/generated/causalpy.checks.placebo_in_space.PlaceboInSpace.plot_mspe_ratio.html
• api/generated/causalpy.checks.placebo_in_time.PlaceboInTime.plot_calibration.html
• api/generated/causalpy.data.simulate_data.UpDownGeoLiftSimulation.html
• and 136 more...

± Modified

• 404.html
• genindex.html
• index.html
• py-modindex.html
• _modules/index.html
• _static/webpack-macros.html
• api/index.html
• knowledgebase/causal_video_resources.html
• knowledgebase/causal_written_resources.html
• knowledgebase/custom_pymc_models.html
• and 667 more...

- Deleted

• api/generated/causalpy.checks.placebo_in_time.AssuranceResult.html
• api/generated/causalpy.experiments.base.BaseExperiment.get_plot_data.html
• api/generated/causalpy.experiments.diff_in_diff.DifferenceInDifferences.algorithm.html
• api/generated/causalpy.experiments.diff_in_diff.DifferenceInDifferences.get_plot_data.html
• api/generated/causalpy.experiments.instrumental_variable.InstrumentalVariable.algorithm.html
• api/generated/causalpy.experiments.instrumental_variable.InstrumentalVariable.get_plot_data.html
• api/generated/causalpy.experiments.interrupted_time_series.InterruptedTimeSeries.algorithm.html
• api/generated/causalpy.experiments.inverse_propensity_weighting.InversePropensityWeighting.algorithm.html
• api/generated/causalpy.experiments.inverse_propensity_weighting.InversePropensityWeighting.get_plot_data.html
• api/generated/causalpy.experiments.panel_regression.PanelRegression.algorithm.html
• and 21 more...

[codecov]

Codecov Report

❌ Patch coverage is 98.86364% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.15%. Comparing base (698c0e1) to head (bc57466).

Files with missing lines	Patch %	Lines
causalpy/pymc_models.py	90.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@                         Coverage Diff                         @@
##           pymc6_and_pymcmarketing1_migration    #1113   +/-   ##
===================================================================
  Coverage                               97.14%   97.15%           
===================================================================
  Files                                     136      136           
  Lines                                   24586    24672   +86     
  Branches                                 1403     1407    +4     
===================================================================
+ Hits                                    23885    23970   +85     
  Misses                                    484      484           
- Partials                                  217      218    +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cetagostini]

indeed BayesianBasisExpansionTimeSeries should not be deprecated.

[cetagostini]

@anevolbap I don't recognize the branch, can we point to migration branch instead?

[anevolbap]

Dropped the deprecation: BayesianBasisExpansionTimeSeries is back to its base state (experimental, same FutureWarning), and only StateSpaceTimeSeries graduates. Title and body updated.

Also rebased onto the current #1112 head, so the conflict is gone, and the notebook now calls .fit() for the lazy lifecycle.

[cetagostini]

@anevolbap if we are ready then let me know moving this to ready for review, so I can merge.

[drbenvincent]

Moving this to the 1.1.0 milestone. The migration branch is being frozen so the PyMC 5 vs 6 baseline for #1048 can be pinned to the exact tree that goes to main for 1.0.0rc1, and this PR touches pymc_models.py. It can land on main after the rc.