sampleroptions

Create Markov chain Monte Carlo (MCMC) sampler options

collapse all in page

Syntax

options = sampleroptions

options = sampleroptions(Name,Value)

Description

options= sampleroptionscreates 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 (customblmmodel object).

example

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

Create and Adjust Default Sampler Options

Open Live Script

假设你计划估计,模拟或佛recast 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指定了片取样器,其典型的宽度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 acustomblmmodel, and then specify sampler options structureoptionsby using the'Options'name-value pair argument ofestimate,simulate, orforecast.

To specify a different MCMC sampler, create a new sampler options structure.

Specify HMC Sampler and Tuning Parameter Values

Open Live Script

假设你计划估计,模拟或佛recast 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

optionsis 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, exceptVerbosityLevel.

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 acustomblmmodel, and then specify sampler options structureoptionsby using the'Options'name-value pair argument ofestimate,simulate, orforecast.

Input Arguments

collapse all

Name-Value Arguments

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, whereNameis the argument name andValueis 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 encloseNamein quotes.

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

Choose Sampler

collapse 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

collapse 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.numPredictorsis the number of predictor variables (columns in the predictor data), andinterceptis1when the model contains an intercept, and0otherwise. The first element ofWidthcorresponds to the model intercept, if one exists in the model. The order of the nextnumPredictorselements corresponds to the order of the predictor variables in the predictor data. The last element corresponds to the model variance.

IfWidthis a scalar, then MATLAB^®appliesWidthto allintercept+numPredictors+1marginal distributions.
IfWidthis a numeric vector, then MATLAB applies the first element to the intercept (if one exists), the nextnumPredictorselements to the regression coefficients corresponding to the predictor variables inX, and the last element to the disturbance variance.
If the sample size (number of rows in the predictor data) is less than100, thenWidthis10by default.
If the sample size is at least 100, then, by default, MATLAB setsWidthto the vector of corresponding posterior standard deviations, assuming a diffuse prior model (diffuseblm).

MATLAB dispatchesWidthto theslicesamplefunction. For more details, seeslicesample.

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

`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'`	Multivariatetdistribution. 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,ScaleMatrixis the posterior covariance matrix of the regression coefficients (Beta) and the model variance (Sigma2) assuming the diffuse model.

Example:“ScaleMatrix”,眼睛(拦截+ 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', thensampleroptionsignoresDegreeOfFreedom.

Example:'DegreeOfFreedom',3

Data Types:double

HMC Sampler Options

collapse 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