sdo.SampleOptions class

Package: sdo

Parameter sampling options for sdo.sample

expand all in page

Description

Specify method options to generate parameter samples, using sdo.sample, for sensitivity analysis.

Construction

opt = sdo.SampleOptions creates an sdo.SampleOptions object and assigns default values to its properties.

Use dot notation to modify the property values. For example:

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

Properties

Method

Sampling method, specified as one of the following values:

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

    Suppose you specified 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.

  • '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.

    Suppose you specified 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.

  • 'sobol' — Sobol quasirandom sequences are drawn from the probability distributions specified for the parameters. Use this option for highly systematic space-filling. Since 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).

    Suppose you specified 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.

    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 Halton method for highly systematic space-filling. However, Sobol method gives more systematic space-filling if you have many parameters in your parameter set. Since 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).

    Suppose you specified 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.

    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.

    Requires Statistics and Machine Learning Toolbox software.

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

Default: 'random'

MethodOptions

Sample method options, specified as a structure. MethodOptions is applicable only when Method is specified as 'sobol', 'halton', or 'copula'.

  • Method is 'sobol' — Since Sobol method is deterministic, if you want to generate slightly different sequences, modify the default values in MethodOptions. Specify MethodOptions as a structure with the following fields:

    • 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'.

    Sobol method is used for a 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 to ensure that they are space-filling.

  • Method is 'halton' — Since Halton method is deterministic, if you want to generate slightly different sequences, modify the default values in MethodOptions. Specify MethodOptions as a structure with the following fields:

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

    Halton method is used for a 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 to ensure that they are space-filling.

  • Method is 'copula' — MethodOptions is a structure with the following fields:

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

      The default value is [].

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects.

Examples

collapse all

Open Live Script
opt = sdo.SampleOptions
opt = 
  SampleOptions with properties:

           Method: 'random'
    MethodOptions: [0x0 struct]
Open Live Script
opt = sdo.SampleOptions;
opt.Method = 'lhs';
Open Live Script

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',{{}});
Open Live Script
opt = sdo.SampleOptions;
opt.Method = 'copula';
opt.MethodOptions.Family = 't';
opt.MethodOptions.DOF = 2;

References

[1] Matousek, J. “On the L2-Discrepancy for Anchored Boxes.” Journal of Complexity. Vol. 14, Number 4, 1998, pp. 527–556.

[2] Kocis, L., and W. J. Whiten. “Computational Investigations of Low-Discrepancy Sequences.” ACM Transactions on Mathematical Software. Vol. 23, Number 2, 1997, pp. 266–294.

See Also

Topics

Simulink Design Optimization Documentation

Support