BudgetOptimizer

pydantic model pymc_marketing.mmm.budget_optimizer.BudgetOptimizer

A class for optimizing budget allocation in a marketing mix model.

The goal of this optimization is to maximize the total expected response by allocating the given budget across different marketing channels. The optimization is performed using the Sequential Least Squares Quadratic Programming (SLSQP) method, which is a gradient-based optimization algorithm suitable for solving constrained optimization problems.

For more information on the SLSQP algorithm, refer to the documentation: https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html

Parameters:

num_periodsint

Number of time units at the desired time granularity to allocate budget for.

modelMMMModel

The marketing mix model to optimize.

response_variablestr, optional

The response variable to optimize. Default is "total_media_contribution_original_scale".

utility_functionUtilityFunctionType, optional

The utility function to maximize. Default is the mean of the response distribution.

budgets_to_optimizexarray.DataArray, optional

Mask defining a subset of budgets to optimize. Non-optimized budgets remain fixed at 0.

custom_constraintsSequence[Constraint], optional

Custom constraints for the optimizer.

default_constraintsbool, optional

Whether to add a default sum constraint on the total budget. Default is True.

budget_distribution_over_periodxarray.DataArray, optional

Fixed temporal distribution of each budget cell across periods. Must have dims ("date", *budget_dims) where the "date" dim has length num_periods. Values must sum to 1 along the "date" dim for every combination of the remaining dims (i.e., budget_distribution_over_period.sum(dim="date") must be all ones). Each value is the fraction of that cell’s total budget assigned to the corresponding period — e.g. fractions [0.4, 0.3, 0.2, 0.1] along "date" mean 40 % of the budget in period 0, 30 % in period 1, and so on. If None, budget is distributed uniformly (1 / num_periods per period).

Methods

BudgetOptimizer.__init__(**data)	Create a new model by parsing and validating input data from keyword arguments.
BudgetOptimizer.allocate_budget(total_budget)	Allocate the budget based on total_budget, optional budget_bounds, and custom constraints.
BudgetOptimizer.extract_response_distribution(...)	Extract the response distribution graph, conditioned on posterior parameters.
BudgetOptimizer.set_constraints(constraints)	Set constraints for the optimizer.

field budget_distribution_over_period: DataArray | None = None

Fixed temporal distribution of each budget cell across periods. Must have dims ('date', *budget_dims) where ‘date’ has length num_periods. Values must sum to 1 along ‘date’ for every combination of the remaining dims. If None, budget is distributed uniformly (1/num_periods per period).

field budgets_to_optimize: DataArray | None = None

Mask defining a subset of budgets to optimize. Non-optimized budgets remain fixed at 0.

field compile_kwargs: dict | None = None

Keyword arguments for the model compilation. Especially useful to pass compilation mode

field cost_per_unit: DataArray | None = None

Cost per unit conversion factors for converting budgets from monetary units (dollars) to original units (impressions, clicks). Must have dims (date, *budget_dims) where date has length num_periods. If None, budgets are assumed to already be in the model’s native units (no conversion applied).

field custom_constraints: Sequence[Constraint] = ()

Custom constraints for the optimizer.

field default_constraints: bool = True

Whether to add a default sum constraint on the total budget.

field mmm_model: Annotated[OptimizerCompatibleModelWrapper, InstanceOf()] [Required] (alias 'model')

The marketing mix model to optimize.

field num_periods: int [Required]

Number of time units at the desired time granularity to allocate budget for.

Constraints:

• gt = 0

field response_variable: str = 'total_media_contribution_original_scale'

The response variable to optimize.

field utility_function: Callable[[XTensorVariable, XTensorVariable], float] = <function average_response>

Utility function to maximize.