LeverVariable

class pymc_marketing.mmm.optimization_variables.LeverVariable(name, dim, coords, bounds, initial_value, flat_dim='budgets_flat')

A non-media decision variable: one pm.Data node in native units.

Where MediaVariable converts monetary budgets into channel data, a lever is optimized directly in whatever units the model already uses for it (a discount fraction, a price index), so the forward map is the identity up to relabelling the flat dimension.

A lever only moves if the optimizer’s response_variable can reach it. The default total_media_contribution_original_scale is built from the channel contribution alone, so a lever acting through a MuEffect is invisible to it; score against total_response_original_scale, which an MMM with mu effects registers.

Levers do not participate in the default budget-sum constraint, which sums the media tensor alone: a discount depth is not money drawn from a shared pool. To constrain one, write a custom Constraint and reach its segment of the flat vector through optimizer.optimization_variables.variable_slice(name).

Parameters:

namestr

Name of the model’s pm.Data node this lever substitutes.

dimstr

The node’s single dimension, which must not be the date dim.

coordslist

Coordinates of dim, in the model’s order.

boundsSequence[tuple] or None

Declared (low, high) bounds per entry in the lever’s native units, or None to leave it unbounded.

initial_valuenp.ndarray

The node’s current value in the model, used as the warm start. It is read once, when the optimizer is constructed, which matches the rest of the optimizer: the objective graph is built and frozen at construction too, and this node is substituted out of it entirely. Updating the pm.Data node afterwards therefore changes neither the objective nor the warm start; rebuild the optimizer to pick up a new value.

flat_dimstr

Name of the flat decision vector’s dimension.

Methods

LeverVariable.__init__(name, dim, coords, ...)
LeverVariable.budget_contribution(z)	Monetary amount this variable draws from the shared budget.
LeverVariable.default_bounds(total_budget)	Return the declared native-unit bounds, or unbounded.
LeverVariable.default_x0(total_budget)	Warm start at the lever's current model value, clipped to bounds.
LeverVariable.from_model(model, name[, ...])	Build a lever by reading a named node's dim, coords and value off a model.
LeverVariable.pack(da)	Flatten labelled lever values into flat-vector order.
LeverVariable.to_model(z)	Relabel the flat slice with the lever's own dim.
LeverVariable.unpack(x)	Label a flat solution slice with the lever's dim and coords.

Attributes

size	Number of lever entries, the length of its dim.
name
dims
coords
flat_dim