MediaVariable

class pymc_marketing.mmm.optimization_variables.MediaVariable(name, mask, num_periods, adstock_periods, channel_scales, dtype, scales_dims=('channel',), date_dim='date', budget_distribution_over_period_tensor=None, cost_per_unit_tensor=None, carry_in_values=None, flat_dim='budgets_flat')

The media-budget decision variable.

Owns the forward map from flat monetary budgets to the model’s channel data tensor: scatter through the optimization mask, spread over num_periods (uniformly or via a fixed temporal distribution), divide by channel_scales, convert monetary units via cost_per_unit, and zero-pad adstock_periods for carry-over, and the inverse map from a flat solution back to a labelled monetary DataArray.

Parameters:

namestr

Name of the model’s channel data variable.

maskDataArray

Boolean mask over the budget dims selecting cells to optimize, already reindexed and transposed to the model’s coordinate and dimension order. That alignment is load-bearing: the mask is consumed positionally by the forward map (scatter into the model’s tensor layout) and supplies the labels for the inverse map, so a mask in a different coordinate order would silently attribute each value to the wrong cell.

num_periodsint

Number of periods budget is allocated over.

adstock_periodsint

Number of zero-padded carry-over periods appended after the allocation window.

channel_scalesfloat or np.ndarray

Per-channel scale factors converting monetary budgets to model units.

dtypestr

dtype of the model’s channel data variable. Must be a float dtype.

date_dimstr

Name of the date dimension.

budget_distribution_over_period_tensorXTensorVariable or None

Pre-processed masked temporal distribution factors with dims (date_dim, flat_dim), or None for uniform spread.

cost_per_unit_tensorXTensorVariable or None

Pre-processed cost-per-unit tensor with dims (date_dim, *mask.dims), or None for no conversion.

flat_dimstr

Name of the flat dimension of the decision vector.

Methods

MediaVariable.__init__(name, mask, ...[, ...])
MediaVariable.budget_contribution(z)	Media spends its whole slice, already in monetary units.
MediaVariable.default_bounds(total_budget)	Default [0, total_budget] bounds per optimized cell.
MediaVariable.default_x0(total_budget)	Spread the total budget uniformly over the optimized cells.
MediaVariable.from_model(model, name, *, ...)	Build a monetary variable by reading a named node's dims off a model.
MediaVariable.pack(da)	Flatten a labelled allocation into this variable's flat-vector order.
MediaVariable.scattered(z)	Scatter the flat slice into the full budget-dims tensor.
MediaVariable.to_model(z)	Build the channel-data substitution tensor from the flat slice.
MediaVariable.unpack(x)	Scatter a flat solution back into a labelled monetary DataArray.

Attributes

shape	Shape of the full (unmasked) budget tensor.
size	Number of optimized budget cells.
name
dims
coords
flat_dim