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

This fragment assumes an unbuilt PanelMMM named mmm, configured for a single time series with its required adstock and saturation objects, and valid training data X and y. See Quickstart: Python API for model and data setup. Attach the event before any call that builds the graph. The event table needs name, start_date and end_date columns.

import pandas as pd
from pymc_extras.prior import Prior

from abacus.mmm.events import EventEffect, GaussianBasis

df_events = pd.DataFrame({
    "name": ["Promotion"],
    "start_date": ["2025-02-10"],
    "end_date": ["2025-02-16"],
})
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)
mmm.build_model(X, y)

Fit with mmm.fit(X, y) using the same training data and your configured sampler settings. For panel models, the event effect dimensions must also include the model’s panel dimensions. Event components do not constitute experimental calibration; use Calibration for that separate task.

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.