Add duration parameter in TimeSeasonality

[gdeleva]

This PR adds one new parameter to TimeSeasonality: duration.
This determines how long each seasonal period is held constant before moving to the next.

Solves #483

[jessegrabowski]

Awesome start! You have exactly the right idea. I think we can be a bit more clever with the math is all.

For the actual implementation, I don't think we can do anything clever -- we'll need to expand the transition matrix to s * d and repeat the rows (and also repeat the starting values). The replicates should all be from the same symbolic value, so the user still just provides s inputs.

[gdeleva]

@jessegrabowski This PR may be ready for a review. I added the transition matrices (for both cases depending on the value remove_first_state) in the documentation. Please check if their definitions are aligned with what you had in mind. I updated the class body according to the definitions of these matrices.

[AlexAndorra]

Well done @gdeleva , this is looking good! Can you add tests to test_seasonality.py, inspiring you from the current tests (feel free to expand them actually, instead of just creating new ones, to avoid redundances). That way we make sure this is actually doing what we want it to do. Also test this when adding to other components, as shown in the corresponding issue

[jessegrabowski]

You also need to update the logic for the initial_states. The user should only pick priors for s parameters, then you need to duplicate them with pt.repeat d times and save that results in self.ssm['initial_state']

[jessegrabowski]

This is really great! Just a few final nitpicks to reduce the number of tests, then let's merge it in. Thanks for this

[jessegrabowski]

Suggested change

	@pytest.mark.parametrize("d1", [1, 2, 3])
	@pytest.mark.parametrize("d2", [1, 2, 3])
	@pytest.mark.parametrize("d1, d2", [(1, 1), (1, 3), (3, 1), (3, 3)])

Our CI runtime is already pretty hefty

[gdeleva]

Thanks for the suggestion. Done.

[gdeleva]

@jessegrabowski No thank you for the support.

[Copilot]

Pull Request Overview

This pull request adds a duration parameter to the TimeSeasonality class, which determines how long each seasonal period is held constant before moving to the next period. This enhancement allows for more flexible seasonal modeling where seasonal effects can persist for multiple time steps rather than changing at each step.

• Adds a new duration parameter with default value of 1 to maintain backward compatibility
• Updates the mathematical model documentation to explain both remove_first_state=True/False cases with the duration parameter
• Modifies the internal state space representation to accommodate the duration parameter by repeating states and adjusting transition matrices

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
pymc_extras/statespace/models/structural/components/seasonality.py	Implements the duration parameter in TimeSeasonality class with updated mathematical formulation, parameter validation, and symbolic graph construction
tests/statespace/models/structural/components/test_seasonality.py	Comprehensive test updates to validate duration parameter functionality across all existing test scenarios

Comments suppressed due to low confidence (1)

pymc_extras/statespace/models/structural/components/seasonality.py:248

• The default state naming pattern for duration > 1 uses the component name variable in the format f"{name}{i}{j}" but 'name' at this point contains the full component name like 'Seasonal[s=12, d=3]'. This will create confusing state names like 'Seasonal[s=12, d=3]_0_0'. Consider using a cleaner base name for state generation.

                state_names = [

[jessegrabowski]

Could you also rebase this onto the most up-to-date main? That's why the doc test is failing. There's been a bit of a nightmare with little bugs across several packages that is now resolved.

[AlexAndorra]

Looking great @gdeleva ! Plus, looks like it's already working with multiple observed time series, so well done 👏

[jessegrabowski]

Great job!