RippleMethoddemo mode

How Ripple works

The model makes the numbers. The agent explains them. The web gives context. This page shows the model, and the evidence that it is right where it claims to be, and wrong where it says so.

The model

One row of data is one week × city × customer segment. Everything the simulator shows comes from this equation and its posterior.

yc,s,t∼NegBin(μc,s,t, ϕ)y_{c,s,t} \sim \mathrm{NegBin}(\mu_{c,s,t},\, \phi)
log⁡μc,s,t=log⁡sharec,s+accity+asseg+eslog⁡pp0+bspromo promo+bfeat feature+bdip promot−1+season(t)\log \mu_{c,s,t} = \log \mathrm{share}_{c,s} + a^{\mathrm{city}}_c + a^{\mathrm{seg}}_s + e_s \log\tfrac{p}{p_0} + b^{\mathrm{promo}}_s\,\mathrm{promo} + b^{\mathrm{feat}}\,\mathrm{feature} + b^{\mathrm{dip}}\,\mathrm{promo}_{t-1} + \mathrm{season}(t)
accity=g0+Xc⋅g+τcity zc,zc∼N(0,1)a^{\mathrm{city}}_c = g_0 + X_c \cdot g + \tau_{\mathrm{city}}\, z_c, \qquad z_c \sim \mathcal{N}(0,1)
es∼N(μe,σe),μe∼N(−1.5,0.5),σe∼HalfNormal(0.5)e_s \sim \mathcal{N}(\mu_e, \sigma_e), \quad \mu_e \sim \mathcal{N}(-1.5, 0.5), \quad \sigma_e \sim \mathrm{HalfNormal}(0.5)

Why each part is there

Every term earns its place by preventing a specific wrong answer.

PartWhy it is thereWhat breaks without it
Negative BinomialWeekly unit counts are overdispersed: the variance is much larger than the mean.A Poisson model calls normal week-to-week variation a surprise, and every interval is far too narrow.
Log-log price termThe coefficient on log price is the elasticity: a 1% price rise changes demand by that many percent.A linear price term means nothing at a different price level and can predict negative demand.
Elasticity per segment, partially pooledStudents and retirees do not respond to price alike. Pooling lets a thin segment borrow strength.Pooled: every offer looks the same for everyone. Unpooled: a small segment is driven by noise.
Promo deal-signal liftBeing on promotion lifts demand beyond the price cut itself.The price term alone understates a promotion, then overstates the discount needed next time.
Post-promo dipA promotion pulls purchases forward from the following week.Promotions look better than they are, because borrowed sales are never paid back.
City effect on traitsA city with no history still gets a forecast, with honest uncertainty from tau.New-city questions become unanswerable.
Customer-mix offsetVolume scales with who lives there, so a different mix needs no refit.A student-heavy city is forecast as if it had the average mix.
Fourier seasonalityYearly shape with few enough parameters to extrapolate.Season is confounded with the promotion calendar and the promo lift absorbs it.

Trust checks