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 of budget_bounds, total_budget and result.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) + 1 per 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 as elasticity keys are, and leaves the labels it does not name unscheduled. A DataArray carries a "bracket" dim (BRACKET) and a subset of the budget dims; nan pads a cell with fewer brackets and may only trail, and a cell whose multipliers are all nan is 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 as rate_multipliers. Default (): no breakpoint on any cell, whatever form rate_multipliers takes. A DataArray without the bracket dim is one breakpoint per cell, so a committed plan can be passed as it is; it names no label that a rate_multipliers DataArray leaves 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. Default 1e-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_unit keeps 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 is cost_per_unit times that average, so the card is [1.0, 8 / 5.5] with cost_per_unit = 5.5 / 5.

  • Fitted on delivery units, a window cost_per_unit: a multiplier of 1 is cost_per_unit, so the card is [1.0, 8 / 5.5] with cost_per_unit = 5.5.

  • Fitted on delivery units, no window cost_per_unit: money reaches the model as units, and the optimizer warns. Pass cost_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_price and implied_delivery are in the units cost_per_unit defines: 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_bounds pins, so a bound and a breakpoint meant to coincide are the same float. Under a budget_distribution_over_period the committed tranche takes the plan’s time shape: the breakpoint of period \(t\) is the breakpoint times num_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 a DataArray over 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_budget blends each breakpoint inside the bounds over knot_width for 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_curvature is False, so a schedule needs no assume_delivery_units and 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_price is 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, and delivery_reports() its prices, on the schedule exactly as allocate_budget prices its result. The deprecated BudgetOptimizerWrapper.sample_response_distribution takes neither a price_response nor a cost_per_unit.

Examples

A committed baseline on a spend-fitted model, held by budget_bounds while 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 dims order: where the resolved map would bend money.

TieredPriceResponse.dict(*[, include, ...])

TieredPriceResponse.from_orm(obj)

TieredPriceResponse.json(*[, include, ...])

TieredPriceResponse.model_parametrized_name(params)

Compute the class name for parametrizations of generic classes.

TieredPriceResponse.parse_file(path, *[, ...])

TieredPriceResponse.parse_obj(obj)

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.update_forward_refs(...)

TieredPriceResponse.validate(value)

Attributes

TieredPriceResponse.adds_curvature

A schedule of rates that are new relative to the fit adds no curvature the fit already holds.

TieredPriceResponse.attests_delivery_units

The user attests that the fitted data are in delivery units (or constant-price spend).

TieredPriceResponse.model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

TieredPriceResponse.needs_derived_reference

True when the declaration supplies no reference level, so a curved cell can only take a derived one.

TieredPriceResponse.breakpoints

TieredPriceResponse.rate_multipliers

TieredPriceResponse.reference_rate

TieredPriceResponse.rate_tolerance

TieredPriceResponse.knot_width