sampleroptions
Create Markov chain Monte Carlo (MCMC) sampler options
Description
uses additional options specified by one or more 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.
Examples
Create and Adjust Default Sampler Options
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
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
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.
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 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® appliesWidth
to allintercept
+numPredictors
+1
marginal distributions.If
Width
is a numeric vector, then MATLAB applies the first element to the intercept (if one exists), the nextnumPredictors
elements 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 than
100
, thenWidth
is10
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 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
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
Data Types: single
| double
TargetAcceptanceRatio
— Target acceptance ratio
0.65
(default) | scalar from 0
through 1
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
NumStepsLimit
— Maximum number of leapfrog steps
2000
(default) | positive integer
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
VerbosityLevel
— Verbosity level of Command Window output
0
(default) | nonnegative integer
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
NumPrint
— Verbose output frequency
100
(default) | positive integer
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
options
— Sampler options
structure array
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
MATLAB-Befehl
Sie haben auf einen Link geklickt, der diesem MATLAB-Befehl entspricht:
Führen Sie den Befehl durch Eingabe in das MATLAB-Befehlsfenster aus. Webbrowser unterstützen keine MATLAB-Befehle.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)