# `Soothsayer.Seasonality`
[🔗](https://github.com/georgeguimaraes/soothsayer/blob/v0.6.3/lib/soothsayer/seasonality.ex#L1)

Seasonality component for Soothsayer forecasting models.

Handles network building and feature engineering for yearly and weekly seasonality
using Fourier series decomposition.

# `add_fourier_features`

```elixir
@spec add_fourier_features(Explorer.DataFrame.t(), String.t(), map()) ::
  Explorer.DataFrame.t()
```

Adds Fourier feature columns to a DataFrame for seasonality modeling.

## Parameters

  * `df` - An `Explorer.DataFrame` containing the input data.
  * `ds_column` - The name of the date column.
  * `seasonality_config` - A map containing the seasonality configuration.

## Returns

  An `Explorer.DataFrame` with additional columns for Fourier terms.

## Examples

    iex> df = Explorer.DataFrame.new(%{"ds" => [~D[2023-01-01]], "y" => [1.0]})
    iex> config = %{yearly: %{enabled: true, fourier_terms: 2}, weekly: %{enabled: false, fourier_terms: 2}}
    iex> result = Soothsayer.Seasonality.add_fourier_features(df, "ds", config)
    iex> "yearly_sin_1" in result.names
    true

# `build_components`

```elixir
@spec build_components(%{yearly: Axon.t(), weekly: Axon.t()}, map()) :: %{
  yearly: Axon.t(),
  weekly: Axon.t()
}
```

Builds seasonality component layers.

## Parameters

  * `inputs` - Map of Axon input nodes from `build_inputs/1`.
  * `config` - Model configuration map.

## Returns

  A map with `:yearly` and `:weekly` keys containing Axon layers.

# `build_features`

```elixir
@spec build_features([Date.t()], map()) :: %{
  yearly: Nx.Tensor.t(),
  weekly: Nx.Tensor.t()
}
```

Builds seasonality feature tensors from dates.

## Parameters

  * `dates` - List of dates.
  * `config` - Model configuration map with `:seasonality` key.

## Returns

  A map with `:yearly` and `:weekly` keys containing Nx tensors.

## Examples

    iex> dates = [~D[2023-01-01], ~D[2023-01-02], ~D[2023-01-03]]
    iex> config = %{seasonality: %{yearly: %{enabled: true, fourier_terms: 2}, weekly: %{enabled: true, fourier_terms: 2}}}
    iex> result = Soothsayer.Seasonality.build_features(dates, config)
    iex> Nx.shape(result.yearly)
    {3, 4}

# `build_inputs`

```elixir
@spec build_inputs(map()) :: %{yearly: Axon.t(), weekly: Axon.t()}
```

Creates Axon input nodes for seasonality components.

## Parameters

  * `config` - Model configuration map with `:seasonality` key.

## Returns

  A map with `:yearly` and `:weekly` keys containing Axon input nodes.

---

*Consult [api-reference.md](api-reference.md) for complete listing*