Create Markov chain Monte Carlo (MCMC) sampler options
options = sampleroptions(Name,Value)Name,Value pair
arguments. For example,
'Sampler','hmc','StepSizeTuningMethod','none' specifies
sampling from the posterior using the Hamiltonian Monte Carlo sampler and no
step-size tuning method.
Suppose that you plan to estimate, simulate, or forecast a Bayesian linear regression model that has a custom joint prior distribution. In this case, MATLAB® resorts to MCMC sampling for posterior simulation and estimation. You can choose a sampler and tune its parameters using a sampler options structure.
Create a default sampler options structure.
options = sampleroptions
options = struct with fields:
Sampler: 'Slice'
Width: []
options specifies the slice sampler, and its typical width is empty. An empty width indicates usage of the default width for posterior sampling.
Specify a typical width of 10 for the slice sampler.
options.Width = 10
options = struct with fields:
Sampler: 'Slice'
Width: 10
To implement slice sampling with a sample width of 10 for posterior estimation, create a customblm model, and then specify sampler options structure options by using the 'Options' name-value pair argument of estimate, simulate, or forecast.
To specify a different MCMC sampler, create a new sampler options structure.
Suppose that you plan to estimate, simulate, or forecast a Bayesian linear regression model that has a custom joint prior distribution, and you want to implement the Hamiltonian Monte Carlo (HMC) sampler.
Create a sampler options structure that specifies sampling using the HMC sampler. Specify a verbosity level of 1.
options = sampleroptions('Sampler','hmc','VerbosityLevel',1)
options = struct with fields:
Sampler: 'HMC'
StepSizeTuningMethod: 'dual-averaging'
MassVectorTuningMethod: 'iterative-sampling'
NumStepSizeTuningIterations: 100
TargetAcceptanceRatio: 0.6500
NumStepsLimit: 2000
VerbosityLevel: 1
NumPrint: 100
options is a structure array, and a list of its fields is displayed at the command line. The fields are the tuning parameters of the sampler. All values are the defaults for the HMC sampler, except VerbosityLevel.
You can also adjust field values at the command line by using dot notation. For example, change the target acceptance ratio to 0.75.
options.TargetAcceptanceRatio = 0.75
options = struct with fields:
Sampler: 'HMC'
StepSizeTuningMethod: 'dual-averaging'
MassVectorTuningMethod: 'iterative-sampling'
NumStepSizeTuningIterations: 100
TargetAcceptanceRatio: 0.7500
NumStepsLimit: 2000
VerbosityLevel: 1
NumPrint: 100
To implement the HMC sampler, create a customblm model, and then specify sampler options structure options by using the 'Options' name-value pair argument of estimate, simulate, or forecast.
Specify optional
comma-separated pairs of Name,Value arguments. Name is
the argument name and Value is the corresponding value.
Name must appear inside quotes. You can specify several name and value
pair arguments in any order as
Name1,Value1,...,NameN,ValueN.
'Sampler','hmc','VerbosityLevel',1 specifies the HMC
sampler and displays details of the step size tuning during
simulation.'Sampler' — MCMC sampler'slice' (default) | 'metropolis' | 'hmc'MCMC sampler, specified as the comma-separated pair consisting of
'Sampler' and a value in this table.
| Value | Description |
|---|---|
'slice' | Slice sampler |
'metropolis' | Random walk Metropolis sampler |
'hmc' | Hamiltonian Monte Carlo (HMC) sampler |
Example: 'Sampler','hmc'
Data Types: char | string
'Width' — Typical sampling-interval widthTypical sampling-interval width around the current value in the
marginal distributions for the slice sampler, specified as the
comma-separated pair consisting of 'Width' and a
positive numeric scalar or an (intercept +
numPredictors + 1)-by-1
numeric vector of positive values. numPredictors is
the number of predictor variables (columns in the predictor data), and
intercept is 1 when the model
contains an intercept, and 0 otherwise. The first
element of Width corresponds to the model intercept,
if one exists in the model. The order of the next
numPredictors elements corresponds to the order
of the predictor variables in the predictor data. The last element
corresponds to the model variance.
If Width is a scalar, then MATLAB® applies Width to all
intercept +
numPredictors + 1
marginal distributions.
If Width is a numeric vector, then
MATLAB applies the first element to the intercept (if
one exists), the next numPredictors
elements to the regression coefficients corresponding to the
predictor variables in X, and the last
element to the disturbance variance.
If the sample size (number of rows in the predictor data)
is less than 100, then
Width is 10 by
default.
If the sample size is at least 100, then, by default,
MATLAB sets Width to the vector of
corresponding posterior standard deviations, assuming a
diffuse prior model (diffuseblm).
MATLAB dispatches Width to the
slicesample function. For more details, see
slicesample.
Tip
The typical width of the slice sampler does not affect convergence of the MCMC sample. However, it does affect the number of required function evaluations, that is, the efficiency of the algorithm. If the width is too small, then the algorithm can implement an excessive number of function evaluations to determine the appropriate sampling width. If the width is too large, then the algorithm might have to decrease the width to an appropriate size, which requires function evaluations.
Example: 'Width',[100*ones(3,1);10]
'Distribution' — Proposal distribution'mvn' (default) | 'mvt'Proposal distribution, specified as the comma-separated pair
consisting of 'Distribution' and a value in this
table.
| Value | Description |
|---|---|
'mvn' | Multivariate normal distribution. To tune the
sampler, specify its covariance matrix by using the
'ScaleMatrix' name-value pair
argument. |
'mvt' | Multivariate t distribution.
To tune the sampler, specify its covariance matrix
or degrees of freedom (or both) by using the
'ScaleMatrix' or 'DegreeOfFreedom' name-value pair
argument, respectively. |
Example: 'Distribution','mvt'
Data Types: string | char
'ScaleMatrix' — Proposal distribution scale matrixProposal distribution scale matrix, specified as the comma-separated
pair consisting of 'ScaleMatrix' and an
(intercept + numPredictors +
1)-by-(intercept + numPredictors + 1)
symmetric, positive definite, numeric matrix. For the meaning of the
rows and columns, see 'Width'.
By default, ScaleMatrix is the posterior covariance
matrix of the regression coefficients (Beta) and the
model variance (Sigma2) assuming the diffuse
model.
Example: 'ScaleMatrix',eye(intercept + numPredictors +
1)
Data Types: double
'DegreeOfFreedom' — Proposal distribution degrees of freedomInf (default) | positive scalarProposal distribution degrees of freedom, specified as the
comma-separated pair consisting of 'DegreeOfFreedom'
and a positive scalar. If 'Distribution' is 'mvn', then
sampleroptions ignores
DegreeOfFreedom.
Example: 'DegreeOfFreedom',3
Data Types: double
'StepSizeTuningMethod' — Method for tuning step size'dual-averaging' (default) | 'none'Method for tuning the step size, specified as the comma-separated pair
consisting of 'StepSizeTuningMethod' and
'dual-averaging' or 'none'.
For more details, see 'StepSizeTuningMethod'.
Example: 'StepSizeTuningMethod','none'
Data Types: char
'MassVectorTuningMethod' — Method for tuning mass vector'iterative-sampling' (default) | 'hessian' | 'none'Method for tuning the mass vector, specified as the comma-separated
pair consisting of 'MassVectorTuningMethod' and
'iterative-sampling',
'hessian', or 'none'. For more
details, see 'MassVectorTuningMethod'.
Example: 'MassVectorTuningMethod','hessian'
Data Types: char
'NumStepSizeTuningIterations' — Number of iterations for tuning step size100 (default) | positive integerNumber of iterations for tuning the step size, specified as the
comma-separated pair consisting of
'NumStepSizeTuningIterations' and a positive
integer. For more details, see 'NumStepSizeTuningIterations'.
Example: 'NumStepSizeTuningIterations',200
Data Types: single | double
'TargetAcceptanceRatio' — Target acceptance ratio0.65 (default) | scalar from 0 through 1Target acceptance ratio, specified as the comma-separated pair
consisting of 'TargetAcceptanceRatio' and a scalar
from 0 through 1. For more
details, see 'TargetAcceptanceRatio'.
Example: 'TargetAcceptanceRatio',0.5
Data Types: single | double
'NumStepsLimit' — Maximum number of leapfrog steps2000 (default) | positive integerMaximum number of leapfrog steps, specified as the comma-separated
pair consisting of 'NumStepsLimit' and a positive
integer. For more details, see 'NumStepsLimit'.
Example: 'NumStepsLimit',5000
Data Types: single | double
'VerbosityLevel' — Verbosity level of Command Window output0 (default) | nonnegative integerVerbosity level of Command Window output, specified as the
comma-separated pair consisting of 'VerbosityLevel'
and a nonnegative integer. For more details, see 'VerbosityLevel'.
Example: 'VerbosityLevel',1
Data Types: single | double
'NumPrint' — Verbose output frequency100 (default) | positive integerVerbose output frequency, specified as the comma-separated pair
consisting of 'NumPrint' and a positive integer. For
more details, see 'NumPrint'.
Example: 'NumPrint',10
Data Types: single | double
options — Sampler optionsSampler options for a Bayesian linear regression model with custom prior distribution, returned as a structure array. After creating a sampler options structure, you can adjust tuning parameter values, except the sampler, by using dot notation.
You have a modified version of this example. Do you want to open this example with your edits?