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

The main module for the Soothsayer library, providing functions for creating, fitting, and using time series forecasting models.

# `display_network`

```elixir
@spec display_network(Soothsayer.Model.t()) :: Axon.t()
```

Returns a display-friendly version of the network that outputs a single tensor.

This can be used with `Axon.Display.as_graph/2` since it doesn't use
`Axon.container` with a map output.

## Parameters

  * `model` - A `Soothsayer.Model` struct.

## Returns

  An Axon network suitable for visualization.

## Examples

    iex> model = Soothsayer.new()
    iex> input = %{
    ...>   "trend" => Nx.template({1, 11}, :f32),
    ...>   "yearly" => Nx.template({1, 12}, :f32),
    ...>   "weekly" => Nx.template({1, 6}, :f32)
    ...> }
    iex> Axon.Display.as_graph(Soothsayer.display_network(model), input)

# `fit`

```elixir
@spec fit(Soothsayer.Model.t(), Explorer.DataFrame.t(), keyword()) ::
  Soothsayer.Model.t()
```

Fits the Soothsayer model to the provided data.

## Parameters

  * `model` - A `Soothsayer.Model` struct.
  * `data` - An `Explorer.DataFrame` containing the training data.
  * `opts` - Optional keyword list:
    - `:events` - An `Explorer.DataFrame` with "event" and "ds" columns.

## Returns

  An updated `Soothsayer.Model` struct with fitted parameters.

## Examples

    iex> model = Soothsayer.new()
    iex> data = Explorer.DataFrame.new(%{"ds" => [...], "y" => [...]})
    iex> fitted_model = Soothsayer.fit(model, data)
    %Soothsayer.Model{config: %{}, network: %Axon.Node{}, params: %{}}

    iex> events_df = Explorer.DataFrame.new(%{"event" => ["sale"], "ds" => [~D[2023-01-01]]})
    iex> fitted_model = Soothsayer.fit(model, data, events: events_df)
    %Soothsayer.Model{config: %{}, network: %Axon.Node{}, params: %{}}

# `get_ar_weights`

```elixir
@spec get_ar_weights(Soothsayer.Model.t()) :: %{
  required(String.t()) => %{kernel: Nx.Tensor.t(), bias: Nx.Tensor.t()}
}
```

Extracts the raw AR layer weights from a fitted model.

For linear AR models, returns the output layer weights.
For deep AR-Net models, returns all layer weights including hidden layers.

## Parameters

  * `model` - A fitted `Soothsayer.Model` struct with AR enabled.

## Returns

  A map of layer names to weight structs containing `:kernel` and `:bias` tensors.

## Examples

    iex> model = Soothsayer.new(%{ar: %{enabled: true, lags: 3}})
    iex> fitted_model = Soothsayer.fit(model, data)
    iex> weights = Soothsayer.get_ar_weights(fitted_model)
    %{
      "ar_dense_out" => %{kernel: #Nx.Tensor<f32[3][1]>, bias: #Nx.Tensor<f32[1]>}
    }

# `get_event_effects`

```elixir
@spec get_event_effects(Soothsayer.Model.t()) :: %{required(String.t()) =&gt; float()}
```

Extracts the learned event coefficients from a fitted model.

Returns a map of event feature names to their learned coefficients.
Feature names are formatted as "event_name_offset" where offset indicates
the window position relative to the event date.

## Parameters

  * `model` - A fitted `Soothsayer.Model` struct with events configured.

## Returns

  A map of feature names to coefficient values.

## Examples

    iex> model = Soothsayer.new(%{events: %{"sale" => %{lower_window: 0, upper_window: 0}}})
    iex> fitted_model = Soothsayer.fit(model, data, events: events_df)
    iex> effects = Soothsayer.get_event_effects(fitted_model)
    %{"sale_0" => 45.2}

    iex> model = Soothsayer.new(%{events: %{"promo" => %{lower_window: -1, upper_window: 1}}})
    iex> fitted_model = Soothsayer.fit(model, data, events: events_df)
    iex> effects = Soothsayer.get_event_effects(fitted_model)
    %{"promo_-1" => 12.5, "promo_0" => 50.0, "promo_+1" => 8.3}

# `new`

```elixir
@spec new(map()) :: Soothsayer.Model.t()
```

Creates a new Soothsayer model with the given configuration.

## Parameters

  * `config` - A map containing the model configuration. Defaults to an empty map.

## Returns

  A new `Soothsayer.Model` struct.

## Examples

    iex> Soothsayer.new()
    %Soothsayer.Model{config: %{trend: %{enabled: true}, seasonality: %{yearly: %{enabled: true, fourier_terms: 6}, weekly: %{enabled: true, fourier_terms: 3}}, epochs: 100, learning_rate: 0.01}, network: %Axon.Node{}, params: nil}

    iex> Soothsayer.new(%{epochs: 200, learning_rate: 0.005})
    %Soothsayer.Model{config: %{trend: %{enabled: true}, seasonality: %{yearly: %{enabled: true, fourier_terms: 6}, weekly: %{enabled: true, fourier_terms: 3}}, epochs: 200, learning_rate: 0.005}, network: %Axon.Node{}, params: nil}

# `predict`

```elixir
@spec predict(Soothsayer.Model.t(), Explorer.Series.t(), keyword()) :: Nx.Tensor.t()
```

Makes predictions using a fitted Soothsayer model.

## Parameters

  * `model` - A fitted `Soothsayer.Model` struct.
  * `x` - An `Explorer.Series` containing the dates for which to make predictions.
  * `opts` - Optional keyword list:
    - `:events` - An `Explorer.DataFrame` with "event" and "ds" columns.

## Returns

  An `Nx.Tensor` containing the predicted values.

## Examples

    iex> fitted_model = Soothsayer.fit(model, training_data)
    iex> future_dates = Explorer.Series.from_list([~D[2023-01-01], ~D[2023-01-02], ~D[2023-01-03]])
    iex> predictions = Soothsayer.predict(fitted_model, future_dates)
    #Nx.Tensor<
      f32[3][1]
      [
        [1.5],
        [2.3],
        [3.1]
      ]
    >

# `predict_components`

```elixir
@spec predict_components(Soothsayer.Model.t(), Explorer.Series.t(), keyword()) :: %{
  combined: Nx.Tensor.t(),
  trend: Nx.Tensor.t(),
  yearly_seasonality: Nx.Tensor.t(),
  weekly_seasonality: Nx.Tensor.t()
}
```

Makes predictions and returns the individual components (trend, seasonality) using a fitted Soothsayer model.

## Parameters

  * `model` - A fitted `Soothsayer.Model` struct.
  * `x` - An `Explorer.Series` containing the dates for which to make predictions.
  * `opts` - Optional keyword list:
    - `:events` - An `Explorer.DataFrame` with "event" and "ds" columns.

## Returns

  A map containing the predicted values for each component (trend, yearly seasonality, weekly seasonality, events) and the combined prediction.

## Examples

    iex> fitted_model = Soothsayer.fit(model, training_data)
    iex> future_dates = Explorer.Series.from_list([~D[2023-01-01], ~D[2023-01-02], ~D[2023-01-03]])
    iex> predictions = Soothsayer.predict_components(fitted_model, future_dates)
    %{
      combined: #Nx.Tensor<...>,
      trend: #Nx.Tensor<...>,
      yearly_seasonality: #Nx.Tensor<...>,
      weekly_seasonality: #Nx.Tensor<...>
    }

---

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