statset

Create statistics options structure

Syntax

statset()

statset(statfun)

statset(___)

statset(Name=Value)

statset(oldopts,newopts)

statset(oldopts,Name=Value)

Description

statset() displays all fields of a statistics options structure and their possible values.

statset(statfun) displays the fields and default values used by the function or object specified by statfun.

statset(___) returns a statistics options structure using any of the previous input argument combinations.

statset(Name=Value) specifies the field values of the options structure using one or more name-value arguments. For example, you can specify the maximum number of objective function evaluations and the weight function for robust fitting.

statset(oldopts,newopts) returns a copy of newopts with the empty fields changed to the values in oldopts.

statset(oldopts,Name=Value) returns a copy of oldopts with field values changed to those specified by the name-value arguments.

Examples

Display Values of Fields

Display all fields of a statistics options structure and their possible values.

statset()

                Display: [ {off} | final | iter ]
            MaxFunEvals: [ positive integer ]
                MaxIter: [ positive integer ]
                 TolBnd: [ positive scalar ]
                 TolFun: [ positive scalar ]
             TolTypeFun: ['abs' |'rel']
                   TolX: [ positive scalar ]
               TolTypeX: ['abs' |'rel']
                GradObj: [ {off} | on ]
               Jacobian: [ {off} | on ]
              DerivStep: [ positive scalar or vector ]
            FunValCheck: [ off | {on} ]
           RobustWgtFun: [ {[]} | bisquare | andrews | cauchy | fair | huber | logistic | talwar | welsch | function handle ]
                   Tune: [ positive scalar ]
            UseParallel: [ {false} | true ]
          UseSubstreams: [ {false} | true ]
                Streams: [ {} | RandStream or cell array ]
              OutputFcn: [ {[]} | function handle or cell array ]

The output shows the fields and their possible values. You can use the output as a reference when creating a statistics options structure.

Create Default Options Structure for Statistics Function

Create an options structure containing the default options for the fitglm function.

options = statset("fitglm")

options = struct with fields:
          Display: 'off'
      MaxFunEvals: []
          MaxIter: 100
           TolBnd: []
           TolFun: []
       TolTypeFun: []
             TolX: 1.0000e-06
         TolTypeX: []
          GradObj: []
         Jacobian: []
        DerivStep: []
      FunValCheck: []
           Robust: []
     RobustWgtFun: []
           WgtFun: []
             Tune: []
      UseParallel: []
    UseSubstreams: []
          Streams: {}
        OutputFcn: []

The output shows that the default options for fitglm include values for the display, maximum number of iterations, and parameter termination tolerance. You can pass options to other functions that accept statistics options structures.

Create Custom Options Structure

Create a custom options structure by using name-value arguments to specify individual field values.

options = statset(FunValCheck="on",TolX=1e-8)

options = struct with fields:
          Display: []
      MaxFunEvals: []
          MaxIter: []
           TolBnd: []
           TolFun: []
       TolTypeFun: []
             TolX: 1.0000e-08
         TolTypeX: []
          GradObj: []
         Jacobian: []
        DerivStep: []
      FunValCheck: 'on'
           Robust: []
     RobustWgtFun: []
           WgtFun: []
             Tune: []
      UseParallel: []
    UseSubstreams: []
          Streams: {}
        OutputFcn: []

You can pass options to an eligible statistics function to set the parameter termination tolerance to 1e-8 and check for invalid values.

Modify Default Options

Create a statistics options structure that contains the default options for the function nbinfit. Then modify the structure by specifying field values using name-value arguments.

oldopts = statset("nbinfit")

oldopts = struct with fields:
          Display: 'off'
      MaxFunEvals: 400
          MaxIter: 200
           TolBnd: 1.0000e-06
           TolFun: 1.0000e-06
       TolTypeFun: []
             TolX: 1.0000e-06
         TolTypeX: []
          GradObj: []
         Jacobian: []
        DerivStep: []
      FunValCheck: []
           Robust: []
     RobustWgtFun: []
           WgtFun: []
             Tune: []
      UseParallel: []
    UseSubstreams: []
          Streams: {}
        OutputFcn: []

oldopts is a statistics options structure that contains the default values for the nbinfit function. Note that the default value for TolX is 1e-6.

Create a copy of oldopts and specify 1e-8 for TolX.

opts = statset(oldopts,TolX=1e-8)

opts = struct with fields:
          Display: 'off'
      MaxFunEvals: 400
          MaxIter: 200
           TolBnd: 1.0000e-06
           TolFun: 1.0000e-06
       TolTypeFun: []
             TolX: 1.0000e-08
         TolTypeX: []
          GradObj: []
         Jacobian: []
        DerivStep: []
      FunValCheck: []
           Robust: []
     RobustWgtFun: []
           WgtFun: []
             Tune: []
      UseParallel: []
    UseSubstreams: []
          Streams: {}
        OutputFcn: []

The output shows that the fields in opts have the same values as the fields in oldopts, with the exception of TolX.

Input Arguments

statfun — Statistics function

character vector | string scalar

Statistics function, specified as a character vector or string scalar, as follows:

• Name of a function or object shown in the table below.

  bootci	bootstrp	candexch
  copulafit	cordexch	crossval
  coxphfit	daugment	dcovary
  evfit	factoran	fitcox
  fitglm	fitglme	fitlme
  fitlmematrix	fitnlm	fitrgp
  gamfit	GeneralizedLinearMixedModel	gevfit
  glmfit	gmdistribution	gpfit
  kmeans	kmedoids	lasso
  lassoglm	LinearMixedModel	lognfit
  mdscale	mlecov	mvncdf
  mvtcdf	nbinfit	nlmefitsa
  nlinfit	nnmf	normfit
  pca	plsregress	ppca
  rocmetrics	rowexch	sequentialfs
  TreeBagger	tsne	wblfit

  When you specify one of these function names, statset returns the default options for the function.

• "mlecustom" — Specifies options for the mle function when you specify a custom probability distribution.

• "parallel" — Specifies options for functions that support parallelization.

Example: "bootci"

Data Types: char | string

oldopts — Old options

options structure

Old options, specified as a statistics options structure.

Data Types: struct

newopts — New options

options structure

New options, specified as a statistics options structure.

Data Types: string

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.

Example: statset(MaxFunEvals=200,TolBnd=1e-6,TolX=1e-6) specifies the maximum number of objective function evaluations as 200, and specifies both the parameter bound tolerance and parameter termination tolerance as 1e-6.

DerivStep — Relative difference

positive scalar (default) | vector of positive scalars

Relative difference for finite difference calculations, specified as a positive scalar or a vector of positive scalars. If DerivStep is a vector of positive scalars, it must be the same size as the vector of parameters estimated by the function using the options structure.

Example: DerivStep=0.1

Data Types: single | double

Display — Option to display algorithm information

"off" | "final" | "iter"

Option to display algorithm information, specified as one of the following:

• "off" — Display no information.

• "final" — Display the final output.

• "iter" — Display iterative output to the command window for some functions, and display the final output otherwise.

Example: Display="iter"

Data Types: char | string

FunValCheck — Flag to check for invalid values

"off" | "on"

Flag to check for invalid values returned by the objective function, specified as "off" or "on". Examples of invalid values include NaN and Inf.

Example: FunValCheck="on"

Data Types: char | string

GradObj — Flag to return gradient

"off" | "on"

Flag to return a gradient vector as an additional output of the objective function, specified as "off" or "on".

Example: GradObj="on"

Data Types: char | string

Jacobian — Flag to return Jacobian

"off" | "on"

Flag to return a Jacobian as an additional output of the objective function, specified as "off" or "on".

Example: Jacobian="on"

Data Types: char | string

MaxFunEvals — Maximum number of objective function evaluations

positive integer

Maximum number of objective function evaluations, specified as a positive integer.

Example: MaxFunEvals=200

Data Types: single | double

MaxIter — Maximum number of iterations

positive integer

Maximum number of iterations, specified as a positive integer.

Example: MaxIter=100

Data Types: single | double

OutputFcn — Output function

function handle | cell array of function handles

Output function, specified as a function handle or cell array of function handles.

Example: OutputFcn=@myfun

Data Types: cell | function_handle

RobustWgtFun — Weight function for robust fitting

character vector | string scalar

Weight function for robust fitting, specified as a character vector or string scalar for one of the following function names.

Weight Function	Equation	Default Tuning Constant
"andrews"	w = (abs(r)<pi) .* sin(r) ./ r	1.339
"bisquare" (default)	w = (abs(r)<1) .* (1 - r.^2).^2	4.685
"cauchy"	w = 1 ./ (1 + r.^2)	2.385
"fair"	w = 1 ./ (1 + abs(r))	1.400
"huber"	w = 1 ./ max(1, abs(r))	1.345
"logistic"	w = tanh(r) ./ r	1.205
"talwar"	w = 1 * (abs(r)<1)	2.795
"welsch"	w = exp(-(r.^2))	2.985

Example: RobustWgtFun="logistic"

Data Types: char | string

Streams — Random number stream

RandStream object | cell array of RandStream objects

Random number stream, specified as a RandStream object or cell array of RandStream objects.

If UseSubstreams is true, then Streams cannot be a cell array of RandStream objects. If UseSubstreams is false and UseParallel is true, then Streams must be empty or have the same length as the number of processors in the calculation. The number of processors is a scalar or is equal to the size of the parallel pool (if one is open).

TolBnd — Parameter bound tolerance

positive scalar

Parameter bound tolerance, specified as a positive scalar.

Example: TolBnd=1e-6

Data Types: single | double

TolFun — Objective function termination tolerance

positive scalar

Objective function termination tolerance, specified as a positive scalar.

Example: TolFun=1.5

Data Types: single | double

TolTypeFun — Type of objective function termination tolerance

"abs" | "rel"

Type of objective function termination tolerance, specified as "abs" or "rel". When TolTypeFun is "abs", TolFun is an absolute tolerance. When TolTypeFun is "rel", TolFun is a relative tolerance.

Example: TolTypeFun="rel"

Data Types: char | string

TolX — Parameter termination tolerance

positive scalar

Parameter termination tolerance, specified as a positive scalar.

Example: TolX=1e-6

Data Types: single | double

TolTypeX — Type of parameter termination tolerance

"abs" | "rel"

Type of parameter termination tolerance, specified as "abs" or "rel". When TolTypeX is "abs", TolX is an absolute tolerance. When TolTypeX is "rel", TolX is a relative tolerance.

Example: TolTypeX="rel"

Data Types: char | string

Tune — Tuning constant for robust fitting

positive scalar

Tuning constant for robust fitting, specified as a positive scalar. The default value of Tune depends on the weight function specified by RobustWgtFun.

Example: Tune=1.5

Data Types: single | double

UseParallel — Flag to use parallel computing

false or 0 | true or 1

Flag to use parallel computing functionality (requires Parallel Computing Toolbox™), specified as a numeric or logical 0 (false) or 1 (true). To use parallel computing when UseParallel is true, Parallel Computing Toolbox must be installed and a parallel pool must be open.

Example: UseParallel=true

Data Types: logical

UseSubstreams — Flag to use substreams

false or 0 | true or 1

Flag for the random number generator to use substreams, specified as a numeric or logical 0 (false) or 1 (true).

When UseSubstreams is true, functions using the options output use the Substream property of the RandStream object. You can specify the RandStream object by using the Streams name-value argument.

Using substreams helps to generate reproducible random number streams in parallel and serial mode computations. For more information, see Reproducibility in Parallel Statistical Computations.

Example: UseSubstreams=true

Data Types: logical

Version History

Introduced before R2006a