Documentation

This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

sampleroptions

Create Markov chain Monte Carlo (MCMC) sampler options

Syntax

``options = sampleroptions``
``options = sampleroptions(Name,Value)``

Description

example

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

Examples

collapse all

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

Input Arguments

collapse all

Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

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.