Use cases¶

Each use case below starts from an item that is ready to use. This item is a Guided template that an analyst can run from a spreadsheet, or a gallery workflow that automates the full analysis. Each use case also has a built-in model. A data scientist can configure, extend or replace this model in a spec. All use cases share the platform: sandboxed runs, the scorecard, governance policies, the explorers, endpoints, snippets, webhooks and embeds.

Use case	Start from	Model	The question it answers
Budget planning	Guided Geo marketing mix, or the `mmm_governed` workflow	`mmm.bayesian` (or `mmm.frequentist`), on mmm-framework	What does each channel bring in, and where must the next euro go?
Effect of a campaign	Guided Effect of a campaign or Geo-lift test, or the `geo_lift_mmm` workflow	`causal.impact`, `causal.synthetic_control` or `causal.did`	Did the campaign work, how large was the effect, and how sure are we?
Governed forecasting pipeline	The `ts_readiness_arimax` workflow, scheduled	`ts.sarimax` (ARIMAX), checked against naive forecasts	Can we publish this forecast each Monday? Can we prove that it is better than a naive forecast?
Macro and VAR analysis	The `var_vecm_cointegration` workflow	`ts.vecm` or `ts.var` (also `ts.varmax`, `ts.dynamic_factor`)	Do these series move together, and what happens to one when another is shocked?
Weekly forecasting	Guided Weekly forecast	`ts.hsgp_trend`	What will this series do over the next weeks, and how sure are we?
Store demand	Guided Demand by store	`tabular.regressor` (xgboost, quantiles)	How much will each store sell, including a store that opens next month?
Customer choice	Guided Customer choice	`choice.multinomial_logit`	Which product does a shopper pick, and how does a price change shift that?
Image classification	`mapi datasets upload-images`, or Folder of images in the web app	`dl.cnn_classifier`, `dl.finetune_classifier`, `tabular.image_logistic` or `sklearn.multiclass_classifier`	Which class is in each image, and how sure is the model?
Science models	A pymc-challenges tutorial, then a science recipe (for example `sci_spatial_ladder`)	15 `sci.*` models, for example `sci.areal_bym2`, `sci.heat_plate` and `sci.network_latent_space`	What does the model of a research notebook tell, and can the analysis repeat with the same checks?

Marketing-mix budget planning¶

The question. Media spend goes to TV, search and social in some markets. What did each channel add to revenue? What does each euro return now? How do we divide the budget of the next quarter?

The data. One row for each week and market: revenue, spend for each channel, and optional controls (for example, price or distribution). Two years of weekly data is a good start. The platform recognises MFF long tables and Meridian-shaped tables directly.

What you get.

Contribution and ROI for each channel and market with 90% ranges, response curves, and a decomposition of revenue into baseline and channels.
Beliefs as ROI or share ranges, and lift tests as calibration. A sandbox translates them into model priors, with a preview in business units.
What-if sliders whose ranges stay joint when some channels move. "Run exact", counterfactuals with a channel set to off, and forecasts.
Budget plans from the model (POST …:optimize, mmm-framework planning). A plan gives the allocation in your bounds, the uplift and the probability that it helps. It also gives the stability of each move and the efficient frontier. A planning tool can call an endpoint for the plan.
Proof before the plan. The default marketing-mix policy fits the model again on shuffled sales and with fake noise channels. It checks the effect signs and the holdout error, and records the evidence. The mmm_governed workflow does all of this in one run: collinearity check, fit, policy, report and evidence pack.
More shapes of the problem (v0.12). mmm.nested measures effects that go through an intermediate measure, for example visits or awareness. mmm.multivariate measures the effects on two or more related products, with halo or cannibalization effects. mmm.bayesian can have channel effects that change over time, and counts or shares as the result. The nested and the multivariate models have Guided templates.
Charts for the marketing team: ROI with mROAS, adstock decay, the contribution waterfall, spend share against effect share, and lift tests next to the estimates of the model.
A record of each fit. Each MMM fit logs its ROI, mROI and contribution share for each channel. You can compare the fits on the compare page.

Start here. Your first MMM in Guided mode → Priors, lift tests and the scorecard → Optimise a budget. Writing your own MMM spec: the marketing-mix guide and mmm-framework on the platform.

Effect of a campaign or a geo-lift test¶

The question. A campaign, a launch or a price change started on a known date. Did it change the result? How large was the effect, and how sure are we? If the campaign ran in some markets only, what does the test tell the marketing mix?

The data. One of these:

One series with a date column, and optional control series that the change did not affect. Start a minimum of 3 periods before the change. Two years is better.
The same number for many markets. The campaign ran in some markets only.
The same number for many units. Some units got the change, and some units never got it.

What you get.

The actual values against a prediction of the values without the change, with a 90% band. The effect in each period, the cumulative effect, the relative effect and the probability that the effect is more than zero.
causal.pre_fit: the fit before the change. Before the change, the actual values must be in the band of the prediction.
For a geo-lift test, the weights of the other markets (causal.donor_weights). The report of the Geo-lift test template has a card that makes the lift-test entry for your marketing mix. The geo_lift_mmm workflow does the test, makes the lift test and fits mmm.bayesian with it.
For difference-in-differences, an event study with one coefficient for each period before and after the change.

Start here. Measure the effect of a change → Causal models and BSTS → Lift tests.

Governed forecasting pipeline¶

The question. Finance publishes a weekly demand forecast. Other teams use it for their plans. Each Monday, Finance must update it with the latest data. The person who approves it must know three things. The data chose the model. The model is better than a naive forecast on weeks that it did not see. The model does not only fit noise.

The data. One weekly KPI with a minimum of two years of history. Also drivers that you know before (prices, promotions, holidays). You upload them as a new dataset version each week.

What you get.

The ts_readiness_arimax workflow. A schedule (0 6 * * 1, Europe/Berlin) or a trigger on each new dataset version runs it:
- ADF, KPSS, Phillips-Perron and Zivot-Andrews decide the differencing.
- An information-criterion search selects the AR and MA orders.
- An expanding-window backtest scores ARIMAX against naive and seasonal-naive forecasts. It uses the same folds at 1, 4 and 8 weeks.
- The workflow keeps the model only if it is better than these forecasts.
A governance policy for forecasts that you publish: null tests, benchmarks, residual whiteness and holdout accuracy. It has the approval of a second person and require_validated_for_promotion. Thus the endpoint that the planners call can serve only a validated version. If not, it gives 409 NOT_VALIDATED.
A record of the run each week. It has the verdict of each test, each branch with the values that it read and the selected orders. It also has the backtest table, the Diebold-Mariano verdict, the governance evidence and an evidence pack for the auditor. The platform uses unchanged steps again from the cache. Thus a new run costs only what changed.

We captured the canonical run on a laptop, with a weekly KPI that wanders. All four tests say "difference once". The search selects ARIMA(1, 1, 1). On 13 held-out weeks, the model is 25% better than "same as last week". But the record also tells that the one-week advantage over naive is possibly luck. It also tells that two of twenty shuffled fits were equally good. An approval needs this type of honesty (the full output).

Start here. Workflow cookbook: readiness to ARIMAX → Validate models with governance policies → Schedules and triggers → Endpoints and webhooks.

Macro and VAR analysis¶

The question. Some series drive each other. Examples are income and consumption, the prices of close substitutes, or sales, distribution and search interest. Are the series tied together in the long run? If one series gets a shock, how do the others respond, and for how long? Does one series help to predict another?

The data. Two to five series at the same frequency, with one value for each series and period (value(series, quarter)). The ingest reads a wide sheet with the wide mapping. The best length is 50 periods or more.

What you get.

The var_vecm_cointegration workflow. A Johansen trace test decides the branch. Tied series get a cointegration-rank search and a VECM on the levels. The workflow differences the series that are not tied. AIC selects the lag order, and the workflow fits a VAR on the changes. Granger tests run on the two branches. The forecast comes from the system that the workflow fitted.
Impulse responses with bands and variance decompositions in the Model Explorer. Also the Johansen table, the speed of adjustment (alpha: how fast a gap closes), the long-run relations (beta) and Granger tables.
ts.varmax when outside drivers are important. ts.dynamic_factor for many series that move with some common factors. ts.ecm (ARDL bounds test) for one equation with long-run drivers.

We ran the workflow of the cookbook on a laptop with three simulated weekly series (160 weeks). In the data, a and b share one stochastic trend, and c wanders alone. The workflow found exactly that:

johansen  The series share at least one long-run relationship.
          (trace statistic 69.1, rank 1)
tied      took the then arm   {'nodes.johansen.rank': 1}
rank      1
vecm      model://growth/wf-macro-system-vecm@v1
granger   Past values of the driver help predict the result.
          (b -> a, lag 1, p = 0.0015)
forecast  8 weeks: dataset://growth/wf-macro-system-forecast-forecast@v1
skipped   diff, lags, var   (the VAR branch was not needed)

(This is a summary of the node results of the run. The cookbook shows the client calls that read them.)

Start here. Workflow cookbook: VAR/VECM cointegration → statsmodels time-series models → Explore a model: impulse responses.

Weekly forecasting¶

The question. What will the orders, visits, calls or sales be in the next 8 to 26 weeks? What is the range that a planner can use?

The data. One date column and one numeric column, weekly or daily. For a seasonal pattern, the history must have a minimum of two seasons.

What you get.

A forecast fan: the median and the 50% and 90% ranges, with the fitted history and the split line. Thus you can see the result of the model on the weeks that it did not see.
A holdout check: the error, and how frequently the actual values were in the 90% range.
The max_extension of the model declares how far it can forecast. The platform refuses a longer horizon with HORIZON_EXCEEDS_FIT before any compute.
A Google Sheet that gets a new forecast from the endpoint each morning.

Start here. The Guided tutorial (pick Weekly forecast) → Connect Google Sheets → Forecasting and sequential models.

Demand by store¶

The question. How many units will each store sell each week, with the prices, promotions and calendar? How many units will a store sell that the model did not see?

The data. One row for each store and week: units sold, and drivers (for example, price and a promotion flag).

What you get.

An xgboost model with calendar features. A low and a high estimate (quantiles) for each store and week, and the importance of each driver.
The platform scores new stores by declaration. The policy of the store dim tells if the platform can score a store that the model did not see, and how. The result does not depend on what the model does with an unknown category.
An endpoint that a replenishment system can call with the plan for the next week. A webhook when a new fit is ready.

Start here. The Guided tutorial (pick Demand by store) → Tabular models → Endpoints and webhooks → Receive webhooks. The xgb_store_demand conformance fixture runs the same problem end to end in some seconds.

Customer choice¶

The question. On each shopping trip, which product does a household select? How does a change in price or a promotion move the shares?

The data. One row for each trip and product: the product that the household selected, its price and its promotion, if there is one. The row identifies the household and the trip.

What you get.

A conditional logit with household effects and Bayesian-bootstrap draws.
The holdout hit rate on the last trip of each household. The scorecard compares it, in plain words, with a guess of the most popular product each time.
Price and promotion counterfactuals: how the shares move when a price changes.

Start here. The Guided tutorial (pick Customer choice) → Built-in models.

Image classification and deep learning¶

The question. Which class is in each image: a product type, a defect, a cell type or a species? How sure is the model, and which images does it get wrong?

The data. A folder of PNG, JPEG or TIFF images. The first folder of each path gives the label, or a manifest table gives the label and the split. Upload a few thousand small images as a zip (image_folder), or up to 1 000 000 images as an image collection. The client uploads only the images that the dataset does not have, and an upload that stops can continue.

What you get.

dl.cnn_classifier (a small ResNet) and dl.finetune_classifier (from pretrained weights) on JAX. The run page shows the training and validation curves while the network trains. The run logs images of the predictions and the confusion matrix. Early stopping, checkpoints and draws from a Laplace approximation or MC dropout.
tabular.image_logistic, a small Bayesian model on the main patterns of the images, with a range for each probability. dl.embed gives image features to a simple head.
Plots for classes: one-vs-rest ROC curves, the confusion matrix, the confusion over the epochs and a grid of the wrong validation images.
The Image gallery of the Data Explorer, with an even sample for each label and split.
The resource class GPU for large training runs. The GPU path is not tested yet.

Start here. Image data → Deep learning → Compare runs and use experiments.

Science models: images, fields, maps and graphs¶

The question. A research notebook fits a Bayesian model to an image, a field, a map or a graph. For example: which districts have a high risk of a disease, and does a covariate explain it? Which conductivity does a heated plate have, and which field does a new heater layout give? Which effects explain the ties of a network? The analysis must repeat, and a person who does not write PyMC code must be able to read it.

The data. The data of the notebook, as a file that you can upload. The export helper writes it:

uv run python -m mapi_plugin_science.export --list
uv run python -m mapi_plugin_science.export e18 \
    --challenges <path to pymc-challenges>/data \
    --out scotland_lip_cancer.nc --spec scotland_lip_cancer.yaml

The file keeps the schema of the model. Thus the upload gives the correct role to each variable. Without a copy of pymc-challenges, --synthetic writes data that the model simulates.

What you get.

15 science models, for example disease maps (sci.areal_bym2), a heat equation (sci.heat_plate), Turing patterns (sci.turing_pattern), STORM frames (sci.storm_localisation), the CMB sky (sci.cmb_field), networks (sci.network_latent_space), graphical models (sci.graphical_model), phylogenies (sci.phylo_regression) and angles (sci.circular_regression).
Plots for each type of data: area maps, field maps, image residuals, predictive image grids, network graphs, phylogenies, polar roses, colour swatches and power spectra.
The Model Explorer: the Fields, Plots, Parameters and Diagnostics sections. The Score page predicts and simulates new data.
Recipes that do the Bayesian workflow:
- sci_spatial_ladder, sci_network_ladder and sci_phylo_signal compare model variants by elpd_loo and stacking weights. Then they tell if an effect is clear.
- sci_calibrate_then_design predicts a new design only if the calibration passes its checks.
- bayes_workflow_audit and sci_image_model_check do the convergence, predictive, prior and recovery checks.

We did the E18 tutorial in the web app with the real data. The BYM2 map has an elpd_loo of −153.0, and the notebook gives −152.7. The effect of outdoor work stays clear. The sci_spatial_ladder recipe took 46 s and selected the ICAR model. The notebook also gives the ICAR model the best elpd_loo.

Start here. pymc-challenges in the web app → E18 Lip cancer disease map → Complex workflows → Scientific models.

Your own model¶

If none of these use cases is correct for you, write your own model. A PyMC model is one build() method, and an sklearn model is one estimator(). The platform does the coordinates, splits, replayed preprocessing, summaries, bundles, endpoints and integrations. Port a model in 15 minutes · Why modeling-api?