mcmctoolbox is a popular, open-source MATLAB package developed by Marko Laine for fitting statistical and differential equation models using Markov Chain Monte Carlo (MCMC) methods. It is highly regarded for implementing Adaptive Metropolis (AM), Delayed Rejection (DR), and Delayed Rejection Adaptive Metropolis (DRAM) sampling algorithms. Key Components to Configure
Before running a simulation, the toolbox requires you to set up four specific MATLAB structures: Typical Variables / Parameters data Holds your empirical data matrices. Time points, observed variables. model Defines the likelihood function and physical equations. ssfun (sum-of-squares function), initial error variance ( σ2sigma squared options Controls how the MCMC chain samples space.
nsimu (number of iterations), adaptint (adaptation interval). params Specifies the parameter properties and constraints. Initial guesses, parameter names, upper/lower bounds. Step-by-Step Guide to Using mcmctoolbox Step 1: Initialize Your Empirical Data
Organize your observed data into a structure so that your model function can easily read it.
data.xdata = [0, 1, 2, 3, 4, 5]‘; % Independent variable (e.g., Time) data.ydata = [1.0, 2.1, 3.8, 8.3, 15.2, 31.1]’; % Observed dependent variable Use code with caution. Step 2: Define the Sum-of-Squares Function (ssfun)
Instead of coding a complex log-likelihood function from scratch, mcmctoolbox evaluates goodness-of-fit using a sum-of-squares function. Create a local helper function or separate file that returns the squared residuals between your model’s predictions and your actual data:
% theta: current proposed parameter values % data: the data structure defined in Step 1 function ss = my_residual_ssfun(theta, data) % A simple exponential growth model prediction: y = theta(1)exp(theta(2) * x) ymodel = theta(1) * exp(theta(2) * data.xdata); % Calculate the sum of squared differences ss = sum((data.ydata - ymodel).^2); end Use code with caution. Step 3: Configure Parameters and Run Options
Define your model boundaries and how long you want the algorithm to run. Pack the params cell array in this order: { ‘name’, initial_guess, min_bound, max_bound }.
% Parameter properties params = { {‘theta1’, 1.0, 0, 10} % Name, initial guess, min, max {‘theta2’, 0.5, 0, 2} }; % Model options model.ssfun = @my_residual_ssfun; % Direct link to your function model.sigma2 = 0.1; % Initial error variance guess % MCMC sampler settings options.nsimu = 10000; % Number of iterations (chain length) options.updatesigma = 1; % Automatically update error variance options.method = ‘dram’; % Options: ‘metropolis’, ‘am’, ‘dr’, ‘dram’ Use code with caution. Step 4: Execute the Sampler
Pass all four configured components into the primary simulation function, mcmcrun.
[results, chain, s2chain, sschain] = mcmcrun(model, data, params, options); Use code with caution.
results: A structure containing data statistics and configuration summaries. chain: The simulated parameter trajectories ( s2chain: The evolution of the residual error variance ( σ2sigma squared Step 5: Diagnose and Visualize Results
The toolbox features built-in plotting utilities to evaluate whether your chains have properly converged:
Trace Plots: Track parameter paths across iterations to check for mixing behavior. mcmcplot(chain, [], results, ‘trace’); Use code with caution.
Density/Histogram Plots: Display the computed posterior distribution profiles for each model variable. mcmcplot(chain, [], results, ‘density’); Use code with caution.
Pairwise Correlations: Generate a scatter matrix to identify structural dependencies between parameters. mcmcplot(chain, [], results, ‘pairs’); Use code with caution.
Print Summary: Output parameter means, standard deviations, and MCMC rejection rates to the command window. chainstats(chain, results); Use code with caution. Pro-Tip: Handling Differential Equations (ODEs)
If your model relies on differential equations, your ssfun will need to invoke MATLAB’s ODE solvers (such as ode45). Inside the function, pass the proposed theta to the solver, sample the trajectory at your specific data.xdata intervals, and calculate the sum of squares against data.ydata.