IncrementalitySpec

class pymc_marketing.mmm.additive_effect.IncrementalitySpec(**data)

Declaration that an effect may take part in incrementality analysis.

Returned by MuEffect.incrementality_spec(). Only effects whose contribution depends on channel_data need one: a spend counterfactual cannot reach any other effect, so those are part of the baseline and are left alone.

Nothing has to be filled in. An empty IncrementalitySpec() opts the effect in and lets Incrementality work the rest out from the graph: the date-indexed pm.Data the effect reads is discovered by traversal, and how far in time the effect carries a change in spend is measured by perturbing one date and watching where the contribution moves. The fields below override that measurement when a caller would rather state the answer than have it derived.

Parameters:

additional_carryover_lagsint, optional

Number of periods beyond the model’s own adstock.l_max over which a change in spend at time t can still move this effect’s contribution. For an effect that chains a second adstock behind the model’s – as a funnel mediator does, with upper_transform feeding demand_transform – it is the l_max of that second adstock. Left at None it is measured. A declared value is allowed to be larger than the measured reach (a wider window only costs compute) but a smaller one is rejected, since it would silently truncate the mediated tail and understate the increment.

evaluation_mode{“auto”, “window”, “full”}, default=”auto”

How much of the date axis the effect needs to see to be evaluated correctly. "window" is the cheap case: the effect propagates spend forward over a bounded number of periods, so a counterfactual can be evaluated on a window around each period. "full" is required by an effect that reads the whole series at once – anything with a reduction over date, such as a normalisation by x.mean("date") – because such an effect takes a different value on a truncated axis. "auto" measures which of the two applies.

Examples

Opt in and let everything be measured:

class FunnelEffect(DataVarMuEffect):
    def incrementality_spec(self) -> IncrementalitySpec:
        return IncrementalitySpec()

Declare the carryover instead, for a funnel whose mediator applies a second adstock of l_max=8:

class FunnelEffect(DataVarMuEffect):
    def incrementality_spec(self) -> IncrementalitySpec:
        return IncrementalitySpec(
            additional_carryover_lags=self.demand_transform.adstock.l_max
        )

Methods

IncrementalitySpec.__init__(**data)	Create a new model by parsing and validating input data from keyword arguments.
IncrementalitySpec.construct([_fields_set])
IncrementalitySpec.copy(*[, include, ...])	Returns a copy of the model.
IncrementalitySpec.dict(*[, include, ...])
IncrementalitySpec.from_orm(obj)
IncrementalitySpec.json(*[, include, ...])
IncrementalitySpec.model_parametrized_name(params)	Compute the class name for parametrizations of generic classes.
IncrementalitySpec.parse_file(path, *[, ...])
IncrementalitySpec.parse_obj(obj)
IncrementalitySpec.parse_raw(b, *[, ...])
IncrementalitySpec.schema([by_alias, ...])
IncrementalitySpec.schema_json(*[, ...])
IncrementalitySpec.update_forward_refs(**localns)
IncrementalitySpec.validate(value)

Attributes

model_computed_fields
model_config	Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
model_extra	Get extra fields set during validation.
model_fields
model_fields_set	Returns the set of fields that have been explicitly set on this model instance.
additional_carryover_lags
evaluation_mode