Main Content

sampleroptions

Create Markov chain Monte Carlo (MCMC) sampler options

collapse all in page

Syntax

options = sampleroptions
options = sampleroptions(Name,Value)

Description

options = sampleroptions creates a sampler options structure with default options for the MCMC sampler used to draw from the posterior distribution of a Bayesian linear regression model with a custom joint prior distribution (customblm model object).

example

options = sampleroptions(Name,Value) uses additional options specified by one or more 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.

example

Examples

collapse all

Open Live Script

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.

Open Live Script

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.

Input Arguments

collapse all

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Sampler','hmc','VerbosityLevel',1 specifies the HMC sampler and displays details of the step size tuning during simulation.

Choose Sampler

collapse all

MCMC sampler, specified as the comma-separated pair consisting of 'Sampler' and a value in this table.

ValueDescription
'slice'Slice sampler
'metropolis'Random walk Metropolis sampler
'hmc'Hamiltonian Monte Carlo (HMC) sampler

Example: 'Sampler','hmc'

Data Types: char | string

Slice Sampler Options

collapse all

Typical 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]

Random Walk Metropolis Sampler Options

collapse all

Proposal distribution, specified as the comma-separated pair consisting of 'Distribution' and a value in this table.

ValueDescription
'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

Proposal 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

Proposal 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

HMC Sampler Options

collapse all

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

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

Number 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

Target 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

Maximum 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

Verbosity 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

Verbose 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

Output Arguments

collapse all

Sampler 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.

Version History

Introduced in R2017b

See Also

| |

Topics