Soothsayer.Events (Soothsayer v0.6.1)

View Source

Event component for Soothsayer models.

Handles network building and feature engineering for events (holidays, promotions, etc.). Each event becomes binary features indicating whether the event occurs on a given date.

Summary

Functions

build_component(input, arg2)

Builds the events component layer.

build_features(dates, events_df, events_config)

Builds event features tensor from dates and events DataFrame.

build_network_input(arg1)

Creates the Axon input node for the events component.

feature_names(events_config)

Returns list of feature names for all configured events.

get_effects(model)

Extracts the learned event coefficients from a fitted model.

n_features(events_config)

Computes total number of event features based on config.

Functions

build_component(input, arg2)

@spec build_component(Axon.t() | nil, map()) :: Axon.t()

Builds the events component layer.

Parameters

Returns

An Axon dense layer when events are configured, Axon.constant(0) otherwise.

build_features(dates, events_df, events_config)

@spec build_features(Explorer.Series.t(), Explorer.DataFrame.t(), map()) ::
  Nx.Tensor.t() | nil

Builds event features tensor from dates and events DataFrame.

For each date, creates binary features indicating whether each event (with its window offsets) occurs on that date.

Parameters

  • dates - An Explorer Series of dates.
  • events_df - A DataFrame with "event" and "ds" columns.
  • events_config - Map of event configurations.

Returns

A tensor of shape {n_dates, n_event_features} with 1.0 where events occur and 0.0 otherwise.

Examples

iex> dates = Explorer.Series.from_list([~D[2023-01-01], ~D[2023-01-02]])
iex> events_df = Explorer.DataFrame.new(%{"event" => ["sale"], "ds" => [~D[2023-01-02]]})
iex> config = %{"sale" => %{lower_window: 0, upper_window: 0}}
iex> Events.build_features(dates, events_df, config)
#Nx.Tensor<
  f32[2][1]
  [
    [0.0],
    [1.0]
  ]
>

build_network_input(arg1)

@spec build_network_input(map()) :: Axon.t() | nil

Creates the Axon input node for the events component.

Parameters

  • config - Model configuration map with optional :events key.

Returns

An Axon input node when events are configured, nil otherwise.

feature_names(events_config)

@spec feature_names(map()) :: [String.t()]

Returns list of feature names for all configured events.

Names are formatted as "event_name_offset" where offset indicates the window position relative to the event date.

Examples

iex> Events.feature_names(%{})
[]

iex> Events.feature_names(%{"sale" => %{lower_window: 0, upper_window: 0}})
["sale_0"]

iex> Events.feature_names(%{"bf" => %{lower_window: -1, upper_window: 1}})
["bf_-1", "bf_0", "bf_+1"]

get_effects(model)

@spec get_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.

Parameters

Returns

A map of feature names to coefficient values.

Examples

iex> effects = Events.get_effects(fitted_model)
%{"sale_0" => 45.2, "promo_-1" => 12.5}

n_features(events_config)

@spec n_features(map()) :: non_neg_integer()

Computes total number of event features based on config.

Each event with window [lower_window, upper_window] creates |lower_window| + 1 + upper_window features.

Examples

iex> Events.n_features(%{})
0

iex> Events.n_features(%{"sale" => %{lower_window: 0, upper_window: 0}})
1

iex> Events.n_features(%{"black_friday" => %{lower_window: -2, upper_window: 1}})
4