Additive Effects and Events

Abacus supports advanced additive components through mu_effects and dated event surfaces.

These are extension points rather than the default modelling path, but they are part of the retained public API.

MuEffect protocol surface

Import path:

from abacus.mmm.additive_effect import MuEffect

MuEffect is the abstract base class for additive components appended to mmm.mu_effects.

Required methods:

Method Purpose
create_data(mmm) Register any required pm.Data inputs
create_effect(mmm) Return the additive contribution tensor
set_data(mmm, model, X) Update the effect for new prediction data

Custom effects should inherit from MuEffect so they can participate in model serialization logic.

Built-in additive effect classes

Import path:

from abacus.mmm.additive_effect import (
    EventAdditiveEffect,
    FourierEffect,
    LinearTrendEffect,
)

Built-in types:

Type Purpose
FourierEffect Wrap a FourierBase component as a MuEffect
LinearTrendEffect Wrap a LinearTrend component as a MuEffect
EventAdditiveEffect Turn dated events into additive model effects

Typical usage:

from abacus.mmm import WeeklyFourier
from abacus.mmm.additive_effect import FourierEffect

mmm.mu_effects.append(
    FourierEffect(fourier=WeeklyFourier(n_order=2, prefix="weekly"))
)

Event surfaces

Import path:

from abacus.mmm.events import (
    AsymmetricGaussianBasis,
    EventEffect,
    GaussianBasis,
    HalfGaussianBasis,
)

Main public event types:

Type Purpose
EventEffect Event effect specification combining a basis and effect size prior
GaussianBasis Symmetric Gaussian event basis
HalfGaussianBasis One-sided Gaussian event basis
AsymmetricGaussianBasis Gaussian basis with different pre and post widths

You can use EventEffect either:

  • directly with PanelMMM.add_events(...), or
  • indirectly through EventAdditiveEffect

Example: direct event attachment

from pymc_extras.prior import Prior

from abacus.mmm.events import EventEffect, GaussianBasis

effect = EventEffect(
    basis=GaussianBasis(),
    effect_size=Prior("Normal", mu=0, sigma=1, dims="promo"),
    dims=("promo",),
)

mmm.add_events(df_events=df_events, prefix="promo", effect=effect)

Serialisation note

FourierEffect and LinearTrendEffect participate in the PanelMMM round-trip path.

EventAdditiveEffect does not currently round-trip through PanelMMM.load(...), because the original event DataFrame is not serialised.