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

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.

# `build_component`

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

Builds the events component layer.

## Parameters

  * `input` - Axon input node from `build_network_input/1`.
  * `config` - Model configuration map.

## Returns

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

# `build_features`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

## Parameters

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

## 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`

```elixir
@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

---

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