function obj = procestOptions(varargin)
%PROCESTOPTIONS  Creates option set for the PROCEST command.
%
%   OPT = procestOptions returns the default options for PROCEST. 
%
%   OPT = procestOptions('Option1',Value1,'Option2',Value2,...) uses
%   name/value pairs to override the default values for 'Option1','Option2',...
%
%   The supported options are:
%
%   InitialCondition  Handling of initial conditions during estimation.
%                     One of the following:
%                        'zero': All initial conditions are taken as zero.
%                    'estimate': The necessary initial conditions are
%                                estimated from data as extra parameters.
%                    'backcast': The necessary initial conditions are
%                                estimated by a backcasting (backward
%                                filtering) process.
%                        'auto': An automatic choice among the above is made,
%                                guided by the data. Default.
%
%   DisturbanceModel  Handling of a model for the additive noise (H):
%                     y = G(s)u + H(s)e (e white noise). H(s) data is
%                     stored in the "NoiseTF" property of IDPROC in num/den
%                     form. Specify DisturbanceModel as one of the following:
%                        'none': Process model has a trivial noise component
%                                (H(s) = 1). 
%                    'estimate': Estimate H(s) using the existing
%                                value in "NoiseTF" as initial guess.
%                                Default.
%                       'ARMA1': Estimated H(s) as a first order ARMA
%                                model: (1+cs)/(1+ds)  
%                       'ARMA2': Estimated H(s) as a second order ARMA
%                                model: (1 + c1 s + c2 s^2)/(1 + d1 s + d2 s^2)
%                       'fixed': The existing value of H(s) in "NoiseTF"
%                                property of IDPROC model is retained.
%                    Note: Noise model cannot be estimated using frequency
%                    domain data.      
%
%   Focus      Choose between 1-step prediction vs. simulation error
%              minimization. Specify as one of:
%              'prediction': Focus on producing good predictors. Default.
%              'simulation': Focus on making a good fit for simulation (with
%                            the current input).
%  
%   WeightingFilter   Weighting prefilter for estimation. Specify as one of:
%                     []: No weighting prefilter applied. Default.
%              Passbands: Row vector or matrix containing frequency values
%                         that define desired passbands. For example:
%                         [wl,wh]
%                         [w1l,w1h ; w2l,w2h ; w3l,w3h ; ...]
%                         where wl and wh represent lower and upper limits
%                         of a passband. For a matrix with several rows
%                         defining frequency passbands, the algorithm uses
%                         union of frequency ranges to define the
%                         estimation passband. Passbands are expressed in
%                         rad/TimeUnit for time domain data and in
%                         frequency units of the data for frequency domain
%                         data.
%            SISO Filter: Any SISO linear filter specified as one of:
%                         * A SISO linear system.
%                         * {A,B,C,D}, which specifies the state-space
%                           matrices of a discrete-time filter.  
%                         * {numerator, denominator}, which specifies the
%                           numerator and denominator of the filter
%                           expressed as a discrete-time transfer function.
%                 Vector: For frequency-domain data only. Specify as a column
%                         vector of weights. This vector must have the same
%                         size as length of the frequency vector of the
%                         data set (= length(Data.Frequency)).
%
%   EstimateCovariance  Specify whether to estimate parameter covariance (true)
%                       or not (false). Default: true.
%
%   Display       View estimation progress ('on'/'off'/'full'). 
%                 'full' displays parameter values over iterations in
%                 addition to objective function related updates.
%                 You can terminate a running estimation by pressing the
%                 STOP button on the progress viewer window. Default: 'off'.
%   
%   InputInterSample  Intersample behavior of the input signals, which
%                     influences the estimation, simulation and prediction
%                     of continuous-time models. Specify as 'auto' (default),
%                     'zoh','foh','bl'.
%
%   InputOffset   Specifies the offset levels present in the input signals
%                 of the estimation data. Available for estimations using
%                 time-domain data only. Specify as one of the following:
%                 - 'estimate': offsets are estimated together with the
%                   parameters of the process model.
%                 - An Nu-element column vector, where Nu is the number of
%                   inputs. For estimations using multi-experiment data,
%                   specify as Nu-by-Ne matrix, where Ne is the number of
%                   experiments. The offset value InputOffset(i,j) is
%                   subtracted from the i:th input signal of the j:th
%                   experiment for estimation. You can use [] to denote no
%                   offsets.
%                 - 'auto': automatic choice between zero offsets and
%                   'estimate' depending upon the nature of data and model
%                   structure. Default. For example, estimation of a model
%                   containing an integrator using time domain data causes
%                   input offset to be estimated.
%                 - A parameter object created using IDPAR. Use the object
%                   for input offset if you want to impose constraints on
%                   how the input offsets must be estimated.
%
%                   Example: Construct an parameter object for a 2-input
%                   model estimation such that the offset in the first
%                   input signal is fixed to zero value and the offset in
%                   the second input signal must be estimated.
%                   opt = procestOptions;
%                   u0 = idpar('u0',[0; NaN]);
%                   u0.Free(1) = false;
%                   opt.InputOffset = u0;
%
%   OutputOffset  Output signal offset levels. Specify as an Ny-element
%                 column vector, where Ny is the number of outputs.
%                 For estimations using multi-experiment data, specify as
%                 Ny-by-Ne matrix, where Ne is the number of experiments.
%                 The offset value OutputOffset(i,j) is subtracted from the
%                 i:th output signal of the j:th experiment for estimation.
%                 You can use [] to denote no offsets.
%
%   OutputWeight  Weighting of prediction errors in multioutput
%                 estimations. Irrelevant is single output case. Specify as: 
%                 'noise': Optimal weighting is automatically computed as
%                          the inverse of the estimated noise variance.
%                          This amounts to minimizing det(E'*E/N) where E
%                          is the matrix of prediction errors and N is
%                          number of samples.
%                  Matrix: Use a positive semi-definite matrix of size
%                          equal to number of outputs. This amounts to
%                          minimizing trace(E'*E*W/N), where W is the
%                          specified matrix.
%                      []: Default. An automatic choice between 'noise' and
%                          eye(Ny) is made depending upon the nature of
%                          data, where Ny = number of outputs.
%
%   Regularization Options for regularized estimation of model parameters.
%                 Structure with fields:
%                 Lambda:  Constant that determines the bias vs. variance
%                          tradeoff. Specify as nonnegative scalar. Zero
%                          value means no regularization. Default: 0
%                      R:  Weighting matrix. Specify as a vector of
%                          nonnegative numbers or a square positive
%                          semi-definite matrix. The length must be equal
%                          to the number of free parameters of the model.
%                          Default is 1 which implies a value of
%                          eye(npfree), where npfree = number of free
%                          parameters.
%                Nominal:  The nominal value towards which the free parameters
%                          are pulled during estimation. Specify as "zero"
%                          (pull parameters towards zero) or "model" (pull
%                          parameters towards preexisting values in the
%                          initial model). Use "model" only when you have a
%                          well-initialized idproc model. Default: "zero"
%
%   SearchMethod  The numerical search method to be used for iterative
%                 refinement. One of:
%                    'gn': Subspace Gauss-Newton least squares search
%                    'lm': Levenberg-Marquardt least squares search
%                   'gna': Subspace Gauss-Newton search with an adaptive
%                          cut-off of singular values. 
%                  'grad': Steepest descent least squares search
%                  'auto': A combination of the above schemes is tried at
%                          each iteration and the descent direction leading
%                          to the most reduction in estimation cost is used.
%                          Default.
%             'lsqnonlin': The trust region reflective algorithm provided
%                          by the Optimization Toolbox. 
%              'fmincon':  Constrained nonlinear solvers. Use
%                          SearchOptions.Algorithm to pick a solver (default
%                          solver: 'sqp').
%
%   SearchOptions Options associated with the search algorithm. The
%                 option set is dependent on the choice of SearchMethod.
%                 Commonly used options:
%                 Tolerance: Search termination tolerance. Specify as a
%                            positive number. Default: 0.01. Not available
%                            for 'lsqnonlin', 'fmincon' (use 'FunctionTolerance' instead).
%             MaxIterations: Maximum number of iterations allowed. Default:
%                            100 for 'fmincon', 20 for others.
%         FunctionTolerance: Similar to Tolerance. Available for
%                            'lsqnonlin' (default 1e-5) and 'fmincon'
%                            (default: 1e-6).
%             StepTolerance: Termination tolerance on parameter value
%                            change. Available for 'lsqnonlin' and 'fmincon'.
%                            Default: 1e-6.
%                 Algorithm: Available for 'fmincon' only. Set to one of:
%                            - 'sqp' (default)
%                            - 'trust-region-reflective'
%                            - 'interior-point' (requires Optimization Toolbox)
%                            - 'active-set' (requires Optimization Toolbox)        
%                 Refer to the "procestOptions" documentation for
%                 information on all available search options.
%
%   Advanced      Structure with fields ErrorThreshold, MaxSize,
%                 StabilityThreshold, AutoInitThreshold. Type "doc
%                 procestOptions" for more information.                        
%
% See also PROCEST, IDFILT, IDPROC, IDPAR.

%  Author(s): Rajiv Singh
%  Copyright 2010-2017 The MathWorks, Inc.

try
   obj = initOptions(idoptions.procest,varargin);
catch E
   throw(E);
end
