DelayedAdstock

class pymc_marketing.mmm.components.adstock.DelayedAdstock(l_max=FieldInfo(annotation=NoneType, required=True, description='Maximum lag for the adstock transformation.', metadata=[Gt(gt=0)]), normalize=FieldInfo(annotation=NoneType, required=False, default=True, description='Whether to normalize the adstock values.'), mode=FieldInfo(annotation=NoneType, required=False, default=<ConvMode.After: 'After'>, description='Convolution mode.'), priors=FieldInfo(annotation=NoneType, required=False, default=None, description='Priors for the parameters.'), prefix=FieldInfo(annotation=NoneType, required=False, default=None, description='Prefix for the parameters.'), parametrization=FieldInfo(annotation=NoneType, required=False, default=None, description='Whether to parametrize the decay by alpha or half-life.'))

Wrapper around delayed adstock function.

Calls pymc_marketing.mmm.transformers.delayed_adstock() with the wrapper’s l_max, normalize and mode settings.

The width of the response around the peak can be parametrised either by the retention rate alpha (the default) or by the half-life of the ad effect. Since the weight at lag \(\ell\) is \(\alpha^{(\ell-\theta)^2}\), a half-life \(h\) corresponds to

\[\alpha = 2^{-1 / h^{2}}, \qquad w_\ell = 2^{-\left(\frac{\ell-\theta}{h}\right)^{2}},\]

which maps any positive half-life into \((0, 1)\) and holds exactly for every l_max and either setting of normalize. Under the half-life parametrisation the trace will contain adstock_halflife instead of adstock_alpha.

Unlike GeometricAdstock, where the half-life is a decay time measured from lag zero, here it is a half-width either side of the peak at theta: the effect takes halflife periods to rise to its peak as well as to fall back from it.

The two defaults are matched, implying a median alpha of 0.207 against 0.206. The priors imply a median half-life of 0.66 periods. A custom half-life prior must have positive support and should keep its mass away from zero, where the likelihood goes numerically flat. The adstock functions guide covers both points.

Parameters:

alphatensor

Retention rate of the ad effect; must be between 0 and 1. Default prior: Prior("Beta", alpha=1, beta=3). Only used when parametrization="alpha".

halflifetensor

Number of time periods between peak effectiveness and half of it; must be positive. Because the kernel is symmetric about theta, this is both the time over which effectiveness rises from half to its peak and the time over which it decays from the peak back to half. Default prior: Prior("InverseGamma", alpha=9, beta=5.75). Only used when parametrization="halflife".

thetatensor

Delay from exposure to peak effectiveness; must be between 0 and l_max - 1. Default prior: Prior("HalfNormal", sigma=1). Used by both parametrisations, and passed to function by keyword only, so that a positional call cannot bind it to halflife by mistake.

parametrizationstr

Either "alpha" or "halflife". When left unset it is inferred from the priors, defaulting to "alpha". Passing a prior for the parameter of the other parametrisation raises a ValueError.

Examples

Parametrise the width of the response by its half-life rather than by the retention rate. For weekly data the priors below say that the effect peaks a couple of weeks after exposure and takes about three weeks to move between half and peak effectiveness:

import numpy as np
from pymc_extras.prior import Prior
from pymc_marketing.mmm import DelayedAdstock

adstock = DelayedAdstock(
    l_max=12,
    priors={
        "halflife": Prior("LogNormal", mu=np.log(3), sigma=0.3),
        "theta": Prior("HalfNormal", sigma=2),
    },
)

(Source code, png, hires.png, pdf)

Methods

DelayedAdstock.__init__([l_max, normalize, ...])
DelayedAdstock.apply(x, *[, core_dim, idx])	Call within a model context.
DelayedAdstock.from_dict(data)	Reconstruct an adstock transformation from a dict.
DelayedAdstock.function(x[, alpha, halflife])	Delayed adstock function.
DelayedAdstock.plot_curve(curve[, ...])	Plot curve HDI and samples.
DelayedAdstock.plot_curve_hdi(curve[, ...])	Plot the HDI of the curve.
DelayedAdstock.plot_curve_samples(curve[, ...])	Plot samples from the curve.
DelayedAdstock.sample_curve(parameters[, amount])	Sample the adstock transformation given parameters.
DelayedAdstock.sample_prior([coords])	Sample the priors for the transformation.
DelayedAdstock.set_dims_for_all_priors(dims)	Set the dims for all priors.
DelayedAdstock.to_dict([_orig])	Convert the adstock transformation to a dictionary.
DelayedAdstock.update_priors(priors)	Update the priors for a function after initialization.
DelayedAdstock.with_default_prior_dims(dims)	Return a copy with default prior dims (dims=None) set to dims instead.
DelayedAdstock.with_updated_priors(priors)	Return a copy with updated priors.

Attributes

combined_dims	Get the combined dims for all the parameters.
default_priors
function_priors	Get the priors for the function.
halflife_priors
model_config	Mapping from variable name to prior for the model.
prefix
priors	Get the priors for the function.
variable_mapping	Mapping from parameter name to variable name in the model.