Run the model

When you run the model, you add your model specification, and then run the commands to sample the prior distribution and the posterior distribution.

Markov Chain Monte Carlo (MCMC) algorithms are used to sample from the posterior distribution. Meridian uses the No-U-Turn sampling method with step size and kernel adaptation.

To run the model:

1. Add your model specification.

   Example:

    model_spec = spec.ModelSpec(
        prior=prior_distribution.PriorDistribution(),
        media_effects_dist='log_normal',
        hill_before_adstock=False,
        max_lag=8,
        unique_sigma_for_each_geo=False,
        media_prior_type='roi',
        roi_calibration_period=None,
        rf_prior_type='coefficient',
        rf_roi_calibration_period=None,
        organic_media_prior_type='contribution',
        organic_rf_prior_type='contribution',
        non_media_treatments_prior_type='contribution',
        knots=None,
        baseline_geo=None,
        holdout_id=None,
        control_population_scaling_id=None,
        adstock_decay_spec='geometric',
        enable_aks=False,
    )
    ```
   

2. Run the following commands to sample from the prior and posterior distribution. Configure the parameters as needed:

   mmm = model.Meridian(input_data=data, model_spec=model_spec)
   mmm.sample_prior(500)
   mmm.sample_posterior(n_chains=7, n_adapt=1000, n_burnin=500, n_keep=1000)
   

   Parameter	Description
   n_chains	The number of chains to be sampled in parallel. To reduce memory consumption, you can use a list of integers to allow for sequential MCMC sampling calls. Given a list, each element in the sequence corresponds to the n_chains argument for a call to windowed_adaptive_nuts.
   n_adapt	The number of MCMC draws per chain, during which step size and kernel are adapted. These draws are always excluded.
   n_burnin	An additional number of MCMC draws, per chain, to be excluded after the step size and kernel are fixed. These additional draws may be needed to ensure that all chains reach the stationary distribution after adaptation is completed, but in practice we often find that the chains reach the stationary distribution during adaptation and that n_burnin=0 is sufficient.
   n_keep	The number of MCMC draws, per chain, to keep for the model analysis and results.

3. (Optional) Thin the posterior distribution for faster iterations.

   To accelerate downstream tasks during iterative workflows (such as generating preliminary model-result reports or evaluating multiple budget optimization scenarios), you can downsample the posterior draws using posterior_thinning(). This selects a chain-preserving subset of posterior draws across each MCMC chain using systematic sampling to minimize autocorrelation:

   # Recommended: 15% sampling rate balances fast iteration with
   # near-approximate inference
   mmm.posterior_thinning(sampling_rate=0.15, preserve_original=True)
   
   # Alternatively, specify the exact number of draws to keep per chain
   # mmm.posterior_thinning(n_draws=150, preserve_original=True)
   

   If preserve_original=True is set, you can restore the full posterior at any time before final delivery:

   mmm.restore_full_posterior()
   

   Parameter	Description
   sampling_rate	The fraction of draws to keep per chain in (0, 1]. Recommended: 0.15 (15%) for exploratory workflows. Exactly one of sampling_rate or n_draws must be specified.
   n_draws	The number of draws to keep per chain in [1, original_n_draws]. Exactly one of sampling_rate or n_draws must be specified.
   method	The draw selection method. Supports ThinningMethod.SYSTEMATIC (default).
   seed	An optional integer random seed for reproducible draw selection.
   preserve_original	A boolean flag (default True). If True, saves a copy of the full posterior so restore_full_posterior() can restore it.

Next, run modeling diagnostics to assess convergence, check the distributions, and assess the model fit.