meridian.analysis.optimizer.OptimizationGrid

Optimization grid information.

meridian.analysis.optimizer.OptimizationGrid(
    _grid_dataset: xr.Dataset,
    historical_spend: np.ndarray,
    use_kpi: bool,
    use_posterior: bool,
    use_optimal_frequency: bool,
    start_date: meridian.data.time_coordinates.Date,
    end_date: meridian.data.time_coordinates.Date,
    gtol: float,
    round_factor: int,
    optimal_frequency: (np.ndarray | None),
    selected_geos: (Sequence[str] | None),
    selected_times: (Sequence[str] | Sequence[bool] | None),
    max_frequency: (float | None) = None
)

historical_spend ndarray of shape (n_paid_channels,) containing aggregated historical spend allocation for spend for all media and RF channels.
use_kpi Whether using generic KPI or revenue.
use_posterior Whether posterior distributions were used, or prior.
use_optimal_frequency Whether optimal frequency was used.
max_frequency The maximum frequency for reach and frequency channels.
start_date The start date of the optimization period.
end_date The end date of the optimization period.
gtol Float indicating the acceptable relative error for the budget used in the grid setup. The budget is rounded by 10*n, where n is the smallest integer such that (budget - rounded_budget) is less than or equal to (budget * gtol).
round_factor The round factor used for the optimization grid.
optimal_frequency Optional ndarray of shape (n_paid_channels,), containing the optimal frequency per channel. Value is None if the model does not contain reach and frequency data, or if the model does contain reach and frequency data, but historical frequency is used for the optimization scenario.
selected_geos The geo coordinates from the model used in this grid.
selected_times The time coordinates from the model used in this grid. If new data with modified time coordinates is used for optimization, this is a list of booleans indicating which time coordinates are selected. Otherwise, this is a list of strings indicating the time coordinates used in this grid.
channels The spend channels in the grid.
grid_dataset Dataset holding the grid information used for optimization.

The dataset contains the following:

  • Coordinates: grid_spend_index, channel
  • Data variables: spend_grid, incremental_outcome_grid
  • Attributes: spend_step_size
incremental_outcome_grid The incremental outcome grid.
spend_grid The spend grid.
spend_step_size The spend step size.

Methods

check_optimization_bounds

View source

check_optimization_bounds(
    lower_bound: np.ndarray, upper_bound: np.ndarray
) -> None

Checks if the spend grid fits within the optimization bounds.

Args
lower_bound np.ndarray of shape (n_channels,) containing the lower bound for each channel. Must be in the same order as self.channels.
upper_bound np.ndarray of shape (n_channels,) containing the upper bound for each channel. Must be in the same order as self.channels.

Raises
ValueError If the spend grid does not fit within the optimization bounds.

optimize

View source

optimize(
    scenario: (meridian.analysis.optimizer.FixedBudgetScenario | meridian.analysis.optimizer.FlexibleBudgetScenario),
    pct_of_spend: (Sequence[float] | None) = None,
    spend_constraint_lower: (_SpendConstraint | None) = None,
    spend_constraint_upper: (_SpendConstraint | None) = None
) -> xr.Dataset

Finds the optimal budget allocation that maximizes outcome.

Args
scenario The optimization scenario with corresponding parameters.
pct_of_spend Numeric list of size channels containing the percentage allocation for spend for all channels. The values must be between 0-1, summing to 1. By default, the historical allocation is used. Budget and allocation are used in conjunction to determine the non-optimized media-level spend, which is used to calculate the non-optimized performance metrics (for example, ROI) and construct the feasible range of media-level spend with the spend constraints.
spend_constraint_lower Numeric list of size channels or float (same constraint for all channels) indicating the lower bound of media-level spend. If given as a channel-indexed array, the order must match channels. The lower bound of media-level spend is (1 - spend_constraint_lower) * budget * allocation). The value must be between 0-1. Defaults to 0.3 for fixed budget and 1 for flexible.
spend_constraint_upper Numeric list of size channels or float (same constraint for all channels) indicating the upper bound of media-level spend. If given as a channel-indexed array, the order must match channels. The upper bound of media-level spend is (1 + spend_constraint_upper) * budget * allocation). Defaults to 0.3 for fixed budget and 1 for flexible.

Returns
An xarray Dataset with channel as the coordinate and the following data
variables * optimized: media spend that maximizes incremental outcome based on spend constraints for all media and RF channels. * non_optimized: rounded channel-level spend.

Raises
A warning if the budget's rounding should be different from the grid's round factor.'.
ValueError If spend allocation is not within the grid coverage.

trim_grids

View source

trim_grids(
    spend_bound_lower: np.ndarray, spend_bound_upper: np.ndarray
) -> tuple[xr.DataArray, xr.DataArray]

Trims the grids based on a more restricted spend bound.

Args
spend_bound_lower The lower bound of spend for each channel. Must be in the same order as self.channels.
spend_bound_upper The upper bound of spend for each channel. Must be in the same order as self.channels.

Returns
updated_spend The updated spend grid with only valid spend values.
updated_incremental_outcome The updated incremental outcome grid containing only the corresponding incremental outcome values for the updated spend grid.

__eq__

__eq__(
    other
)

Return self==value.

max_frequency None