BudgetOptimizerWrapper.optimize_budget#

BudgetOptimizerWrapper.optimize_budget(budget, budget_bounds=None, response_variable=None, utility_function=<function average_response>, constraints=(), budgets_to_optimize=None, budget_distribution_over_period=None, cost_per_unit=None, callback=False, **allocate_budget_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, optional

Response variable to optimize. Defaults to "total_media_contribution_original_scale", which is built from the channel contribution alone. Pass "total_response_original_scale" for a model with mu_effects, whose contributions the default cannot see; leaving this unset on such a model warns.

utility_functionUtilityFunctionType

Utility function to maximize.

constraintsSequence[Constraint], optional

Constraints for the optimizer. Each element must be a Constraint. If empty (the default, ()), a default sum-equals-total-budget constraint is added automatically. If non-empty, the caller is in charge: no default is added. Pass build_default_sum_constraint() explicitly to keep the sum constraint alongside custom ones.

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 track optimization progress; when True the returned result’s callback_info attribute holds per-iteration information.

**allocate_budget_kwargs

Additional arguments for allocate_budget().

Returns:
BudgetOptimizationResult

Result object with budgets, scipy_result, optimized_vars and callback_info attributes. Iterating it yields (budgets, scipy_result), so two-element unpacking keeps working.