TieredPriceResponse#
- class pymc_marketing.mmm.price_response.TieredPriceResponse(*, breakpoints=(), rate_multipliers, reference_rate=None, rate_tolerance=3.0, knot_width=0.01)[source]#
A schedule of marginal rates: each bracket of money buys units at its own price.
Money in bracket \(i\) buys units at
cost_per_unit * rate_multipliers[i], the way a tax schedule taxes each bracket of income at its own rate. The rates are marginal, not average: crossing a breakpoint reprices the money above it and leaves the money below it alone. For one cell with budget \(z\), in the units ofbudget_bounds,total_budgetandresult.budgets,\[u(z) = \frac{1}{p_0} \sum_i \frac{\min(z, B_{i+1}) - \min(z, B_i)}{r_i}, \qquad B_0 = 0,\; B_{K+1} = \infty\]with \(p_0\) the base price (
cost_per_unit, or 1) and \(r_i\) the multipliers. Delivery is increasing and piecewise linear, continuous at every breakpoint, and concave when the multipliers do not fall along the brackets. A typical schedule is a committed baseline bought at one rate and incremental money at another:breakpoints=[committed],rate_multipliers=[1.0, 1.6].- Parameters:
rate_multipliers (
Union[tuple[float,...],dict[str,tuple[float,...]],DataArray]) – One multiplier of the base price per bracket,len(breakpoints) + 1per cell. A sequence applies to every optimized cell; a bare number is a one-element sequence, a uniform price change. A dict maps labels of exactly one budget dim to a sequence, matched by string form aselasticitykeys are, and leaves the labels it does not name unscheduled. ADataArraycarries a"bracket"dim (BRACKET) and a subset of the budget dims;nanpads a cell with fewer brackets and may only trail, and a cell whose multipliers are allnanis unscheduled.breakpoints (
Union[tuple[float,...],dict[str,tuple[float,...]],DataArray]) – Where each bracket ends, in budget units, strictly ascending and non-negative, in the same form asrate_multipliers. Default(): no breakpoint on any cell, whatever formrate_multiplierstakes. ADataArraywithout the bracket dim is one breakpoint per cell, so a committed plan can be passed as it is; it names no label that arate_multipliersDataArrayleaves out, along the dims both have, since the cells of such a label would be unscheduled. A first breakpoint of exactly 0 is an empty first bracket, which is what such a plan gives a channel with no commitment. Equal adjacent multipliers make a breakpoint with no kink.reference_rate (
float|None) – The absolute rate a multiplier of 1 stands for, positive and finite, recorded so the declaration says what its multipliers are relative to. It changes no number the map computes; it is shown in the repr and in the message that refuses a multiplier too far from 1.rate_tolerance (
float) – Every multiplier must lie in[1 / rate_tolerance, rate_tolerance]. Default 3. Planning rates move by tens of percent around the base price, so a multiplier of 8 is an absolute rate typed where a ratio was meant, and one of 160 is a percentage. Raise it for a ratio that is really that large.knot_width (
float) – Half-width of the blend that replaces a breakpoint inside a solve’s bounds during the first solve, relative to the breakpoint. Default1e-2. It decides how easily that solve converges, not the plan that comes back (see Notes).
Notes
What a multiplier of 1 is.
cost_per_unitkeeps the meaning it has for the constant-price path: the level. The multipliers say how the level changes with the money spent. A rate card of 5.5 for the first bracket and 8 for the second is written:Fitted on spend, no window
cost_per_unit(a base price of 1): a multiplier of 1 is the fit window’s average rate, so the card is[5.5 / 5, 8 / 5]if that average was 5.Fitted on spend, a window
cost_per_unit: a multiplier of 1 iscost_per_unittimes that average, so the card is[1.0, 8 / 5.5]withcost_per_unit = 5.5 / 5.Fitted on delivery units, a window
cost_per_unit: a multiplier of 1 iscost_per_unit, so the card is[1.0, 8 / 5.5]withcost_per_unit = 5.5.Fitted on delivery units, no window
cost_per_unit: money reaches the model as units, and the optimizer warns. Passcost_per_unit.
On a spend-fitted model the base is the average rate of the fit window: total fitted spend over total delivered units. It is not last year’s rate and not today’s. “TV costs 10% more than last year” is
[1.1]only if the fit window is last year; with a three-year fit and 4% of yearly media inflation the multiplier is about 1.14, and the gap differs by channel. A user with no unit history cannot compute that average and is making a judgement call.implied_priceandimplied_deliveryare in the unitscost_per_unitdefines: on a spend-fitted model with no window price the price is an index against the fit’s average rate and the delivery is rate-adjusted money, not impressions.Breakpoints are in budget units, the number
budget_boundspins, so a bound and a breakpoint meant to coincide are the same float. Under abudget_distribution_over_periodthe committed tranche takes the plan’s time shape: the breakpoint of period \(t\) is the breakpoint timesnum_periods * f_t. A sequence or a dict gives the same breakpoint to every cell it reaches: on a(geo, channel)layout{"tv": [1e6]}is one million per period for TV in each geo, so a national commitment typed that way is applied once per geo. Give commitments as aDataArrayover the cells. Four limits follow from deciding one number per cell and pricing it as a multiple of one base price:Prices are per period and a commitment is usually a window total. The two agree when the commitment and the increment share one time shape, which the single decision forces; a front-loaded commitment topped up evenly is mispriced where the two overlap.
“Incremental money only from week 27” cannot be expressed. Optimize the sub-window as its own window.
Spending below the first breakpoint prices the unspent commitment as a refund at the committed rate. A commitment that cannot be cancelled is a lower bound in
budget_bounds, not a price.Every bracket follows the base price’s seasonality: a seasonal committed card and a flat open-market rate for the increment cannot both be written down.
In a solve, a cell whose best budget is a breakpoint is returned equal to it, bitwise.
allocate_budgetblends each breakpoint inside the bounds overknot_widthfor a first solve, uses that solve only to find the linear piece of the schedule each cell is on, and then solves on those pieces, where no breakpoint is left to cross, until no cell on a breakpoint would gain by leaving it. When that cannot be settled, the best plan found comes back with a warning that it was not settled on its breakpoints.A volume discount, a multiplier that falls, is accepted. Delivery is convex across that breakpoint, so a solve whose bounds contain it is refused, naming the cells: a lower bound on the breakpoint optimizes the discounted money above it and an upper bound on it the money below. Any plan can be scored.
Not gated on delivery units.
adds_curvatureisFalse, so a schedule needs noassume_delivery_unitsand works on a model fitted on spend. That holds because the rates are new relative to the fit, a new buy or a new strategy, and not because the map is piecewise linear: tiers that were already in effect during the fit window were absorbed by the saturation curve, and pricing them again double-counts them; that needs a model fitted on delivery units. More than four brackets on a cell warns that the schedule looks like a discretized price curve, which is that case.Out of scope. A tranche that is differently effective per unit.
implied_priceis the cost of a unit; its effect still comes from the fitted response curve.Scoring a plan.
evaluate_plan()gives the objective and gradient of any plan,evaluate_response_distribution()its posterior response, anddelivery_reports()its prices, on the schedule exactly asallocate_budgetprices its result. The deprecatedBudgetOptimizerWrapper.sample_response_distributiontakes neither aprice_responsenor acost_per_unit.Examples
A committed baseline on a spend-fitted model, held by
budget_boundswhile the increment is optimized at a rate 60% above the base:import xarray as xr from pymc_marketing.mmm import TieredPriceResponse committed = xr.DataArray( [40_000.0, 25_000.0], dims="channel", coords={"channel": ["tv", "radio"]} ) optimizer = mmm.budget_optimizer( start_date, end_date, price_response=TieredPriceResponse( breakpoints=committed, rate_multipliers=xr.DataArray([1.0, 1.6], dims="bracket"), ), ) bounds = xr.DataArray( [[40_000.0, 200_000.0], [25_000.0, 200_000.0]], dims=("channel", "bound"), coords={"channel": ["tv", "radio"], "bound": ["lower", "upper"]}, ) result = optimizer.allocate_budget(total_budget=90_000.0, budget_bounds=bounds) optimizer.delivery_reports(result.budgets)["channel_data"] optimizer.evaluate_plan(result.budgets)
The same schedule with the default bounds lets the commitment be cut too; a channel left on its breakpoint comes back equal to it:
result = optimizer.allocate_budget(total_budget=90_000.0) (result.budgets == committed).sel(channel="tv")
A volume discount on TV above 50,000 per period, solved with the lower bound on the breakpoint:
discount = TieredPriceResponse( breakpoints={"tv": [50_000.0]}, rate_multipliers={"tv": [1.0, 0.85]} )
Methods
TieredPriceResponse.__init__(**data)Create a new model by parsing and validating input data from keyword arguments.
TieredPriceResponse.construct([_fields_set])TieredPriceResponse.copy(*[, include, ...])Returns a copy of the model.
TieredPriceResponse.curved_cells(*, dims, ...)Boolean per cell of a layout, in
dimsorder: where the resolved map would bend money.TieredPriceResponse.dict(*[, include, ...])TieredPriceResponse.json(*[, include, ...])Compute the class name for parametrizations of generic classes.
TieredPriceResponse.parse_file(path, *[, ...])TieredPriceResponse.parse_raw(b, *[, ...])TieredPriceResponse.resolve(*, dims, coords, ...)Bind the schedule to one variable's cell layout.
TieredPriceResponse.schema([by_alias, ...])TieredPriceResponse.schema_json(*[, ...])TieredPriceResponse.validate(value)Attributes
A schedule of rates that are new relative to the fit adds no curvature the fit already holds.
The user attests that the fitted data are in delivery units (or constant-price spend).
Configuration for the model, should be a dictionary conforming to [
ConfigDict][pydantic.config.ConfigDict].True when the declaration supplies no reference level, so a curved cell can only take a derived one.