docs: update seasonal model documentation with state-space details and 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()

Author: YuminosukeSato

README.md

@@ -103,7 +103,7 @@ Tests run on every commit with seed-fixed MCMC for deterministic reproduction.
 |---|---|---|
 | `point_effect_mean` | ±3% relative | Passing on core scenarios |
 | `cumulative_effect_total` | ±3% relative | Passing on core scenarios |
-| `ci_lower` / `ci_upper` | Tight parity | `±1.5%` no-covariates, `±1%` covariates, explicit Phase 2 acceptance `±3%`, seasonal fixture `±5%` |
+| `ci_lower` / `ci_upper` | Tight parity | `±1%` no-covariates, `±1%` covariates, explicit Phase 2 acceptance `±3%`, seasonal `±1%` |
 | `p_value` | Significance match | Classification at alpha=0.05 |
 
 ### What is matching R and what is not
@@ -118,7 +118,7 @@ Tests run on every commit with seed-fixed MCMC for deterministic reproduction.
 | Spike-and-slab variable selection | Matching | Coordinate-wise sampling with StudentSpikeSlabPrior defaults (`expected.r2=0.8`, `prior.df=50`, `prior.information.weight=0.01`, `diagonal.shrinkage=0.5`) |
 | expected.model.size | Matching | Unified default `2` in `CausalImpact` and `ModelOptions` |
 | expected.r2 = 0.8, prior.df = 50 | Matching | Same documented residual variance prior defaults as BoomSpikeSlab / bsts |
-| Seasonal component (`nseasons`, `season_duration`) | Supported | R-compatible API with seasonal fixture coverage |
+| Seasonal component (`nseasons`, `season_duration`) | Matching | State-space model matching R bsts `AddSeasonal()` (±1% CI parity) |
 | Dynamic regression | Supported | Time-varying coefficients via random-walk FFBS; `dynamic_regression=True` |
 | Local linear trend | Supported | Opt in with `state_model="local_linear_trend"` |
 

docs/compatibility-matrix.md

@@ -8,7 +8,7 @@ Comparison of features between R CausalImpact (bsts 1.4.1) and this Python imple
 |---|---|---|---|
 | Local level | Yes | Yes | Identical algorithm |
 | Local linear trend | Yes | Yes | `state_model="local_linear_trend"` |
-| Seasonality | Yes | Yes | R-compatible API with seasonal fixture coverage |
+| Seasonality | Yes | Yes | State-space model matching R bsts `AddSeasonal()` |
 | Dynamic regression | Yes | Yes | `dynamic_regression=True` |
 | Regression (static) | Yes | Yes | Identical algorithm |
 
@@ -71,7 +71,7 @@ Comparison of features between R CausalImpact (bsts 1.4.1) and this Python imple
 |---|---|---|
 | point_effect_mean | ±3% relative | Passing |
 | cumulative_effect_total | ±3% relative | Passing |
-| ci_lower / ci_upper | Tight parity (`±1.5%` no-cov, `±1%` covariates, `±5%` seasonal) | Passing |
+| ci_lower / ci_upper | Tight parity (`±1%` no-cov, `±1%` covariates, `±1%` seasonal) | Passing |
 | p_value significance | Match at alpha=0.05 | Passing |
 
 Tests run against R CausalImpact 1.4.1 fixtures on every PR.

docs/examples.md

@@ -183,6 +183,37 @@ Posterior prob. of a causal effect: 99.95%
 True effect = 8.0, estimated = 7.57. The 95% CI [5.99, 9.18] contains the true
 value.
 
+### How it works
+
+The seasonal component uses a state-space model matching R bsts `AddSeasonal()`.
+The state vector is `[μ_t, s_1(t), ..., s_{S-1}(t)]` where `S = nseasons`.
+Seasonal states evolve via a sum-to-zero transition: the next season equals
+the negative sum of the previous `S-1` seasons plus noise.
+
+### Using `season_duration`
+
+When each season spans multiple time steps (e.g., daily data with weekly
+seasonality where each day of the week lasts one step), set `season_duration`
+accordingly. The seasonal transition only fires at season boundaries
+(`t % season_duration == 0`); in between, the seasonal state is frozen.
+
+```python
+# Daily data with 7-day weekly pattern (default: season_duration=1)
+ci = CausalImpact(
+    data, pre_period, post_period,
+    model_args={"nseasons": 7, "season_duration": 1, "seed": 42},
+)
+
+# Bi-weekly data with 26 two-week seasons per year
+ci = CausalImpact(
+    data, pre_period, post_period,
+    model_args={"nseasons": 26, "season_duration": 2, "seed": 42},
+)
+```
+
+When `season_duration` is omitted, it defaults to 1 (every time step is a new
+season).
+
 ---
 
 ## 4. Dynamic Regression