@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)

@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: %{}}

@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]>}
}

@spec get_event_effects(Soothsayer.Model.t()) :: %{required(String.t()) => 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}

@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}

@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]
  ]
>

@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<...>
}