Additive Effects and Events

AMMM3 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:

MethodPurpose
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:

TypePurpose
FourierEffectWrap a FourierBase component as a MuEffect
LinearTrendEffectWrap a LinearTrend component as a MuEffect
EventAdditiveEffectTurn 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:

TypePurpose
EventEffectEvent effect specification combining a basis and effect size prior
GaussianBasisSymmetric Gaussian event basis
HalfGaussianBasisOne-sided Gaussian event basis
AsymmetricGaussianBasisGaussian 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, LinearTrendEffect and EventAdditiveEffect participate in the PanelMMM round-trip path. Event payloads retain df_events and effect. Older event payloads that omit either field raise ValueError on restoration. See Save and Load.