sampleroptions

Create Markov chain Monte Carlo (MCMC) sampler options

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

Create and Adjust Default Sampler Options

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.

Specify HMC Sampler and Tuning Parameter Values

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.

Name-Value Arguments

expand all

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

expand all

`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

Slice Sampler Options

expand all

`Width` — Typical sampling-interval width
positive numeric scalar | numeric vector of positive values

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

expand all

`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 matrix
symmetric, positive definite, numeric matrix

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

`DegreeOfFreedom` — Proposal distribution degrees of freedom
`Inf` (default) | positive scalar

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

expand all

`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 size
`100` (default) | positive integer

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