sdo.SampleOptions

Parameter sampling options for sdo.sample

Description

Specify method options for using sdo.sample to generate parameter samples for sensitivity analysis. Use sdo.SampleOptions for taking samples from probability distributions defined in a sdo.ParameterSpace object. To specify options for taking samples across a grid of parameter values defined by a sdo.GriddedSpace object, use sdo.GriddingOptions.

Creation

Syntax

opt = sdo.SampleOptions

Description

opt = sdo.SampleOptions creates an options set for sampling parameter spaces and assigns default values to its properties. Use dot notation to modify the property values.

Properties

Method — Sampling method

'random' (default) | 'lhs' | 'sobol' | 'halton' | 'copula'

Sampling method, specified as one of the following values:

• 'random' — Random samples are drawn from the probability distributions specified for the parameters.

• 'lhs' — Latin hypercube samples are drawn from the probability distributions specified for the parameters. Use this option for a more systematic space-filling approach than random sampling.

• 'sobol' — Sobol quasirandom sequences are drawn from the probability distributions specified for the parameters. Use this option for highly systematic space filling. Because the Sobol method is deterministic, if you want slightly different sequences, modify the MethodOptions property. For more information, see Generating Quasi-Random Numbers (Statistics and Machine Learning Toolbox).

  Using the Sobol method requires Statistics and Machine Learning Toolbox™ software.

• 'halton' — Halton quasirandom sequences are drawn from the probability distributions specified for the parameters. Like the Sobol method, you can use the Halton method for highly systematic space filling. However, the Sobol method gives more systematic space filling if you have many parameters in your parameter set. Because the Halton method is deterministic, if you want slightly different sequences, set the MethodOptions property. For more information, see Generating Quasi-Random Numbers (Statistics and Machine Learning Toolbox).

  Using the Halton method requires Statistics and Machine Learning Toolbox software.

• 'copula' — Random samples are drawn from a copula. Use this option to impose correlations between the parameters using copulas. You specify the copula family and correlation type in the MethodOptions property. You must also specify the value of the RankCorrelation property of the sdo.ParameterSpace object that you use for sampling.

  Using the copula method requires Statistics and Machine Learning Toolbox software.

For all methods except 'copula', if you specify a value for the RankCorrelation property of the sdo.ParameterSpace object that you use for sampling, the software uses the Iman-Conover method to impose the parameter correlations.

For more information about the sampling methods, see Generate Parameter Samples for Sensitivity Analysis.

MethodOptions — Additional options for sampling method

[] (default) | method-specific option set

Additional options for the sampling method, specified as a method-specific options set. When you set Method to 'sobol', 'halton', or 'copula', the software automatically sets MethodOptions to an appropriate options set. You can then use dot notation to further adjust the method-specific options.

Method is 'sobol'

The Sobol method is deterministic. If you want to generate slightly different sequences, modify the default values in opt.MethodOptions and resample. For the Sobol method, opt.MethodOptions includes the following options:

• Skip — Number of initial points to ignore in a Sobol sequence of points, specified as a non-negative integer. The default value is 1.

• Leap — Number of points to ignore between selected points in a Sobol sequence, specified as a non-negative integer. The default value is 0.

• ScrambleMethod — Shuffling of the Sobol sequence points, specified as a structure with following fields:

  • Type — Name of the scramble method, specified as 'MatousekAffineOwen' (Matousek-Affine-Owen scrambling algorithm [1]). Sobol sets with scrambling are not deterministic. Successive runs using this algorithm generate different points. To always generate the same Sobol sequence points, reset the random number generator each time using the rng command.

  • Options — Specify as an empty cell array.

  For example, specify ScrambleMethod as struct('Type','MatousekAffineOwen',Options',{{}}).

  If you do not want to scramble the sequence, specify ScrambleMethod as [].

  The default value for ScrambleMethod is 0x0 struct.

• PointOrder — Order in which the Sobol sequence points are produced, specified as one of the following:

  • 'standard' — Points produced match the original Sobol sequence implementation.

  • 'graycode' — Sobol sequence is generated using an implementation that uses the Gray code of the index instead of the index itself.

  The default value for PointOrder is 'standard'.

The Sobol method is used for highly systematic space filling. However, some combinations of the MethodOptions values may result in sequence points that are clustered and not space-filling. After you have generated the samples using sdo.sample, view the generated samples with sdo.scatterPlot to ensure that they are space-filling.

Method is 'halton'

The Halton method is deterministic. If you want to generate slightly different sequences, modify the default values in opt.MethodOptions and resample. For the Halton method, opt.MethodOptions includes the following options:

• Skip — Number of initial points to ignore in a Halton sequence of points, specified as a non-negative integer. The default value is 1.

• Leap — Number of points to ignore between selected points in a Halton sequence, specified as a non-negative integer. The default value is 0.

• ScrambleMethod — Shuffling of the Halton sequence points, specified as a structure with following fields:

  • Type — Name of the scramble method, specified as 'RR2' (reverse-radix algorithm [2]).

  • Options — Specify as an empty cell array.

  For example, specify ScrambleMethod as struct('Type','RR2',Options',{{}}).

  If you do not want to scramble the sequence, specify ScrambleMethod as [].

  The default value for ScrambleMethod is 0x0 struct.

The Halton method is used for highly systematic space filling. However, some combinations of the MethodOptions values may result in sequence points that are clustered and not space filling. After you have generated the samples using sdo.sample, view the generated samples with sdo.scatterPlot to ensure that they are space filling.

Method is 'copula'

For the copula method, opt.MethodOptions includes the following options:

• Family — Copula family, specified as one of the following values:

  • 'Gaussian' — Gaussian copula

  • 't' — t copula

  The default value is 'Gaussian'.

• Type — Rank correlation type, specified as one of the following values:

  • 'Spearman' — Spearman’s rank correlation

  • 'Kendall' — Kendall’s rank correlation

  The default value is 'Spearman'.

• DOF — Degrees of freedom of t copula, specified as a positive number.

  For a Gaussian copula, specify DOF as []. Specification of DOF is required for a t copula.

Examples

Specify Random Sampling Method

opt = sdo.SampleOptions

opt = 
  SampleOptions with properties:

           Method: 'random'
    MethodOptions: [0x0 struct]

Specify Latin Hypercube Sampling Method

opt = sdo.SampleOptions;
opt.Method = 'lhs';

Specify Sobol Sampling method

Create a default option set.

opt = sdo.SampleOptions;

Specify the sampling method as Sobol.

opt.Method = 'sobol';

Specify a scrambling method.

opt.MethodOptions.ScrambleMethod = struct('Type','MatousekAffineOwen','Options',{{}});

Specify Copula-Based Sampling Method

opt = sdo.SampleOptions;
opt.Method = 'copula';
opt.MethodOptions.Family = 't';
opt.MethodOptions.DOF = 2;

References

[1] Matoušek, Jiřı́. "On the L2-Discrepancy for Anchored Boxes." Journal of Complexity 14, no. 4 (December 1998): 527–56.

[2] Kocis, Ladislav, and William J. Whiten. "Computational Investigations of Low-Discrepancy Sequences." ACM Transactions on Mathematical Software 23, no. 2 (June 1997): 266–94. https://doi.org/10.1145/264029.264064.

Version History

Introduced in R2014a