feat: state-space seasonal model matching R bsts AddSeasonal()#11
Merged
Conversation
Seasonal model is being migrated from static dummy-variable regressors to Kalman state variables (R bsts AddSeasonal compat). Tests will break during the transition and be re-enabled after implementation.
Implement Durbin-Koopman (2002) simulation smoother for S-dimensional
state vector [μ_t, s_1(t), ..., s_{S-1}(t)] with sum-to-zero seasonal
transition, matching R bsts AddSeasonal() behavior.
Includes helper functions (apply_state_transition, count_season_boundaries,
seasonal_kalman_smoother) and 17 unit tests covering boundary values
(T=1, S=2/7/12, season_duration=2/7), signal tracking, and numerical
stability.
- sampler.rs: Add seasonal branch in run_single_chain_static() with local_level_seasonal_smoother, sample_sigma2_seasonal (InvGamma conjugate posterior), sample_sigma2_obs_seasonal, and post-period seasonal state propagation. Add 10 unit tests for sigma2_seasonal. Remove dead code (scale_matrix, invert_matrix) from rust-speedup merge. - state_space.rs: Store SeasonalConfig, add has_seasonal(), seasonal_nseasons(), seasonal_duration(). Skip dummy regressors when state-space seasonal is active. - lib.rs: Add sigma_seasonal field to GibbsSamples PyO3 binding.
- Add tests/test_seasonal_smoother.py with 13 integration tests: sigma_seasonal existence/emptiness/positivity/length, point effect and CI bounds finiteness, post-period predictions, significance detection, backward compatibility, boundary values (S=2/12, d=7). - xfail test_seasonal_model_tracks_weekly_pattern in test_integration.py: state-space seasonal adds propagation variance in post-period, making point estimates marginally less precise for constant seasonal patterns with low noise. This matches R bsts behavior.
State-space seasonal smoother achieves <0.1% relative error vs R bsts, far exceeding the original ±5% tolerance with dummy-variable approach. Tolerance changes: - seasonal: ±5% → ±1% (actual: <0.1%) - basic/strong_effect CI: ±1.5% → ±1.0% (actual: <0.5%) - Remove xfail from TestEquivalenceSeasonal (all 5 tests pass) All 33 numerical equivalence tests pass with tightened tolerances.
.cargo/config.toml set target-cpu=native for x86_64-unknown-linux-gnu, causing SIGILL in CI when build scripts compiled with AVX instructions ran on runners without AVX support. rust-cache amplified this by sharing binaries across runners with different CPU feature sets. Move .cargo/ to .gitignore so developers can opt into target-cpu=native locally without affecting CI builds.
- Remove unused pytest import - Remove unused ci variable assignment - Fix line length (89 > 88) - Fix import sorting
…d tightened tolerances - Update CI tolerance from ±5% to ±1% for seasonal (README, compatibility-matrix) - Add season_duration usage examples to docs/examples.md - Document state-space seasonal model matching R bsts AddSeasonal()
- Add seasonal ±1% CI parity note to migration-from-r.md - Fix season.duration param notation in compatibility-matrix.md - Improve season_duration examples with clearer use cases - Add nseasons=1 equivalence note and constraint rules to api.md - Define Matching vs Supported status labels in README.md
YuminosukeSato
added a commit
that referenced
this pull request
Mar 23, 2026
feat: state-space seasonal model matching R bsts AddSeasonal()
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replace the dummy-variable regression approach for seasonal components with a proper Kalman state-space model, matching R bsts
AddSeasonal()behavior. This achieves <0.1% relative error vs R bsts for all seasonal metrics (down from ±5%).[μ_t, s_1(t), ..., s_{S-1}(t)]with sum-to-zero seasonal transitionsample_sigma2_seasonal()with InvGamma conjugate posterior matching R bstsSdPriorChanges
src/kalman.rslocal_level_seasonal_smoother(), helper functions, 17 unit testssrc/sampler.rssample_sigma2_seasonal(), post-period propagation, 10 unit testssrc/state_space.rshas_seasonal(),seasonal_nseasons(),seasonal_duration()src/lib.rssigma_seasonalfield in PyO3GibbsSamplestests/test_seasonal_smoother.pytests/test_numerical_equivalence.pytests/test_integration.pyNumerical equivalence (niter=20000)
Test plan
cargo test)pytest tests/)