Repository: statsmodels/statsmodels

Issue:
HoltWinters: name and docs of the parameter "seasonal_periods" are misleading
#### Describe the bug
As you can see below, the parameter that sets length of my season (e.g 7 in case of week) has the name of `seasonal_periods` that suggest "How many seasons is in your data".
For example, if I have 56 days of training data with weekly seasonality then I assume that `seasonal_periods` expects to have value of `8` (because 56/7 = 8 and | have 8 seasonal periods in training data)
Quoting the docs: 
```
seasonal_periods : int, optional
        The number of seasons to consider for the holt winters.
```

#### Code Sample, a copy-pastable example if possible
```python
from statsmodels.tsa import holtwinters
# assume train['y'] has 56 data point, 8 seasons, 7 points per season
hwmodel = holtwinters.ExponentialSmoothing(train['y'][:-7*8].to_numpy(), trend='add',
    seasonal='add', seasonal_periods=8).fit() # won't work well, as it should be 7 in case of weekly seasonality

```

#### Expected Output

- `seasonal_periods` param should either do what it suggests (accept number of seasons in data set), or
- another parameter like `season_length` should be introduced that does what `seasonal_periods` does right now (accepts season length)

#### Output of ``import statsmodels.api as sm; sm.show_versions()``

<details>
Statsmodels
===========
Installed: 0.9.0 

</details>



Discussion:
PRs to clarify documentation and provide examples are always welcome.

On Wed, Jun 12, 2019, 19:18 Christopher Suchanek <notifications@github.com>
wrote:

> Describe the bug
>
> As you can see below, the parameter that sets length of my season (e.g 7
> in case of week) has the name of seasonal_periods that suggest "How many
> seasons is in your data".
> For example, if I have 56 days of training data with weekly seasonality
> then I assume that seasonal_periods expects to have value of 8 (because
> 56/7 = 8 and | have 8 seasonal periods in training data)
> Quoting the docs:
>
>         The number of seasons to consider for the holt winters.```
>
> #### Code Sample, a copy-pastable example if possible
> ```python
> from statsmodels.tsa import holtwinters
> # assume train['y'] has 56 data point, 8 seasons, 7 points per season
> hwmodel = holtwinters.ExponentialSmoothing(train['y'][:-7*8].to_numpy(), trend='add',
>     seasonal='add', seasonal_periods=8).fit() # won't work well, as it should be 7 in case of weekly seasonality
>
>
> Expected Output
>
>    - seasonal_periods param should either do what it suggests (accept
>    number of seasons in data set), or
>    - another parameter like season_length should be introduced that does
>    what seasonal_periods does right now (accepts season length)
>
> Output of import statsmodels.api as sm; sm.show_versions() Statsmodels
> =========== Installed: 0.9.0
>
> —
> You are receiving this because you are subscribed to this thread.
> Reply to this email directly, view it on GitHub
> <https://github.com/statsmodels/statsmodels/issues/5866?email_source=notifications&email_token=ABKTSRNL5ZMJLUBJSKL2YWDP2E4Y3A5CNFSM4HXN3FI2YY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4GZEGGCA>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABKTSROGXMFICFKKVHTEGZTP2E4Y3ANCNFSM4HXN3FIQ>
> .
>

> PRs to clarify documentation and provide examples are always welcome.

As I already wrote, there are two ways of fixing that and none of them supports backward compatibility:

1. rename `seasonal_periods` to `season_length` - no backward compatibility
2. make `seasonal_periods` do what it claims to be doing - no backward compatibility

@bashtage  LMK which option works best for you and I would be more than happy to create a PR.

Why not something like:

```
seasonal_periods : int, optional
        The number of periods in a season, for the Holt-Winters smoother.
```

Maybe not perfect, but it seems clear to me and it would be less invasive than changes to the code.
I think @ChadFulton is the simplest of the three options.  Can expand it with an example or two

```
The number of periods in a season, for the Holt-Winters smoother, e.g., 12 for monthly data with an annual seasonality or 7 for daily data with a weekly (hebdomadal) cycle.
```

It is also possible to add an example with say weekly data that sets `seasonal_periods` with a short explanation under 

```
Examples
--------
This example shows the smoother is used to model data with a 7-period seasonal component

>>> ...
```
@ChadFulton 
@bashtage  
Once again, currently this parameter sets **the length of a period** and **not** The number of periods in a season
> Once again, currently this parameter sets the length of a period and not The number of periods in a season

I'm not sure I fully agree with this statement.  While i agree that it sets the length of the seasonal cycle, it is both the length of a period and the number of periods in a seasonal cycle.  What it isn't is the number of seasons in the data set, which seems to have been the initial issue. 

However, if the definition is modified to:

```
seasonal_periods : int, optional
    The number of periods in a complete seasonal cycle.
```

Then the definition contains both `seasonal` and `periods` and is an accurate description of the parameter.  This is the simplest way forward since it avoids deprecation which can take many years in practice.  

It would be better to provide one or two in-line examples, as in 

```
seasonal_periods : int, optional
    The number of periods in a complete seasonal cycle, e.g., 4 for quarterly data with an 
    annual cycle or 7 for daily data with a weekly cycle.
```

IMO, the best name is `seasonal_periodicity` or just `periodicity` which is the term used in SARIMAX. 


Resolving patch:
diff --git a/statsmodels/tsa/holtwinters.py b/statsmodels/tsa/holtwinters.py
--- a/statsmodels/tsa/holtwinters.py
+++ b/statsmodels/tsa/holtwinters.py
@@ -460,7 +460,8 @@ class ExponentialSmoothing(TimeSeriesModel):
     seasonal : {"add", "mul", "additive", "multiplicative", None}, optional
         Type of seasonal component.
     seasonal_periods : int, optional
-        The number of seasons to consider for the holt winters.
+        The number of periods in a complete seasonal cycle, e.g., 4 for
+        quarterly data or 7 for daily data with a weekly cycle.
 
     Returns
     -------


Test patch: