Model artifacts (closes gap 2)
Every model is stored in one envelope with a tier, a representation and, new in this draft, a dependence declaration that says whether its uncertainty is joint across channels and parameters. Operations that need joint uncertainty still run on artifacts that cannot supply it, under a stated dependence assumption and a range wide enough to cover it.¶
Tiers¶
| Tier | What we hold | Typical source | Can support |
|---|---|---|---|
| A: Full model¶ | Structure, posterior or fitted parameters, input contract, code | in-house frameworks, modeling-api, PyMC-Marketing, Meridian | Everything, including refit and per-draw portfolio maths |
| B: Curve parameters¶ | Curve family and parameters per media line, with uncertainty; adstock settings | Robyn exports, vendors sharing parameters | Scoring, marginal returns, optimisation; portfolio maths only with joint draws |
| C: Spend table¶ | Predicted response on a declared spend grid | Black-box vendors | Scoring and optimisation by interpolation inside the grid |
| D: Summary numbers¶ | ROI or mROI at current spend | Decks, older reports | Rough local estimates, always labelled |
| X: Hosted model¶ | An endpoint we query but cannot inspect | Vendor or R models behind an API | What its metadata endpoint declares |
Envelope fields. ID, revision (incremented only when content changes, and so a new content hash), lifecycle state (changes without a new revision), content hash, parents, owner, access; tier; applies_to (media, geos, KPI, dates); estimand (section 5) for every output; input contract with dim policies; representation; dependence; capabilities (section 8); valid-from and valid-to (half-open, RFC 3339 instants, section 4); audit level and trust; licence limits on vendor outputs.¶
The CloudEvents artifactversion attribute carries revision. A scenario is stale only against a newer revision, never against a state change.¶
Payload format. Tier A posteriors use the ArviZ InferenceData group layout (posterior, sample_stats, log_likelihood, observed_data) in zarr, plus a JSON sidecar validated by the UMP JSON Schema that carries estimand, units, dependence and lineage. A modeling-api bundle (zarr DataTree plus manifest) is a conforming Tier A payload. Every derived output from one bundle uses the same bundle-wide thinning index, so contributions, curves and predictions stay jointly consistent.¶
Representations. draws, quantiles, interval, point, moments, and moments_cov (mean vector with covariance, new because modeling-api’s moments holds only mean and sd). Summary and aggregation permissions follow modeling-api’s rules as normative text: quantiles and intervals cannot be summed, draws aggregate per draw, points aggregate only with a flag.¶
Dependence declaration¶
- If the channels move independently: errors partly cancel, so the range is narrow
- If they move together (perfectly correlated): errors add up, so the range is wide
- Range computed from the declared dependence
- Band imputed from the test library
Illustrative bands. No values are implied.
Fall back
per_channel: each channel has its own range, but they are not aligned. Nobody knows whether one channel's good weeks are another's. UMP still adds them up. It takes the median under independence and sets the total's range to the envelope between independent and perfectly correlated channels, labelled G-DEP-01.
Portfolio maths (for example a total with a range, the chance of beating a plan, expected regret, EVOI) needs this joint picture. That is why the dependence declaration exists.
| Value | Meaning | Portfolio operations |
|---|---|---|
joint_draws¶ | Draws aligned across all channels and parameters | Run as is |
joint_gaussian¶ | moments_cov across channels | Run, labelled Gaussian approximation |
declared_assumption¶ | Per-channel uncertainty plus a named copula or independence assumption | Run under the declared assumption, labelled |
per_channel¶ | Draws or summaries per channel, not aligned | Fall back (G-DEP-01). Independent coupling: an independent uniform random permutation of each channel’s draws, with a recorded seed. Comonotone coupling: each channel’s draws sorted by value. The point is the median under the independent coupling. For sums, means, CVaR and monotone functions of sums, the interval is the union of the two couplings’ intervals. It is labelled DEPENDENCE_ASSUMED with envelope_kind: bound. For quantile-type outputs (p10), non-monotone outputs (probability of beating a plan, expected regret) and EVOI, the union is reported as a range across the two couplings, labelled DEPENDENCE_ASSUMED with envelope_kind: range. Such a range MUST NOT be described as a bound. |
none¶ | Point values only | Fall back: uncertainty imputed from the test library (G-UNC-01), then as per_channel |
Portfolio operations are: optimisation with uncertainty in the objective (p10, cvar), probability of beating a plan, expected regret, EVOI, sums across channels with intervals, and carryover-floor calculations that need joint saturation and adstock parameters. In one illustrative case, two equally plausible posterior draws give duration floors of 11 and 16 weeks.¶
Tier B requirements. Curve family from a closed list (Hill, logistic, power, negative exponential; others by extension); parameters per draw or with covariance; adstock form and parameters; any input scaling used at fit.¶
Tier C requirements. No external standard exists, so UMP defines one, using modeling-api’s response_curves layout (contribution(sample, channel, multiplier[, geo]) plus spend at each grid point) as the normative shape. A submission MUST declare:¶
- the grid, at least 21 points from zero to 2.5 times current spend (proposed), and the maximum spend the model saw;¶
- time aggregation (per week, per flight, annual) and whether values are steady-state or single-period;¶
- adstock treatment (included, excluded or unknown);¶
- currency, units and cost basis;¶
- the estimand, including baseline;¶
- an uncertainty band as draws or quantiles, or
none, which sets trust to the lowest level; UMP then imputes a band from the test library’s spread for that channel family and labels it.¶
Scoring outside the grid is extrapolation and carries a warning (G-SCN-03).¶