BudgetOptimizerWrapper.optimize_budget#

BudgetOptimizerWrapper.optimize_budget(budget, budget_bounds=None, response_variable='total_media_contribution_original_scale', utility_function=<function average_response>, constraints=(), default_constraints=True, budgets_to_optimize=None, budget_distribution_over_period=None, cost_per_unit=None, callback=False, **minimize_kwargs)[source]#

Optimize the budget allocation for the model.

Parameters:

budgetfloat | int

Total budget to allocate.

budget_boundsxr.DataArray | None

Budget bounds per channel.

response_variablestr

Response variable to optimize.

utility_functionUtilityFunctionType

Utility function to maximize.

constraintsSequence[Constraint]

Custom constraints for the optimizer. Each element must be an instance of Constraint.

default_constraintsbool

Whether to add default constraints.

budgets_to_optimizexr.DataArray | None

Mask defining which budgets to optimize.

budget_distribution_over_periodxr.DataArray | 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 (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. If None, budget is distributed uniformly (1 / num_periods per period).

cost_per_unitpd.DataFrame or xr.DataArray or None, optional

Cost per unit conversion factors for the optimization period. Converts budgets from monetary units (e.g., dollars) to the model’s native channel units (e.g., impressions).

pd.DataFrame: Wide-format with a "date" column matching the optimization window dates, plus one column per channel. Missing channels default to 1.0 (no conversion).
xr.DataArray: Must have dims ("date", *budget_dims) where date has length num_periods.

If None, no conversion is applied (budgets are assumed to be in the model’s native units).

This is independent of the historical cost_per_unit.

callbackbool

Whether to return callback information tracking optimization progress.

**minimize_kwargs

Additional arguments for the optimizer.

Returns:

tuple: Optimal budgets and optimization result. If callback=True, also returns a list of dictionaries with optimization information at each iteration.