garchset.m

灰色控制 灰色控制 matlab

function options = garchset(varargin)
%GARCHSET Create/alter GARCH Toolbox specification structure.
%   GARCHSET provides the main user-interface for specifying GARCH Toolbox
%   parameters, and is the preferred method for creating and modifying GARCH 
%   model specification structures. 
%
%   Spec = garchset('Parameter1', Value1 , 'Parameter2' , Value2 , ...) 
%   Spec = garchset(OldSpec , 'Parameter1' , Value1 , ...)
%   Spec = garchset
%   garchset
%
%   The first calling syntax creates a GARCH specification structure Spec in
%   which the input argument list is specified as parameter/value pairs. The 
%   Parameter portion of the pair must be recognized as a valid field of the 
%   output structure Spec; the Value portion of the pair is then assigned to
%   it's paired Parameter field such that the named parameters have the specified 
%   values. It is sufficient to type only the leading characters that uniquely 
%   identify a parameter. Case is ignored for parameter names. Valid parameters 
%   fields are listed below.
%
%   The second calling syntax modifies an existing GARCH specification 
%   structure, OldSpec, by changing the named parameters to the specified values.
%   
%   The third calling syntax (with no input arguments) creates a specification 
%   structure Spec with all fields set to the default settings.
%
%   The fourth calling syntax (with no input arguments and no output arguments) 
%   displays all parameter field names and default values where appropriate.
%
% Inputs:
%   Parameter - String representing a valid parameter field of the output 
%     structure Spec (see below).
%
%   Value - The value assigned to the corresponding Parameter. 
%
%   OldSpec - An existing Spec specification structure to be changed,
%     probably created from a previous call to GARCHSET.
%
% Output:
%   Spec - The first three calling syntaxes return a structure encapsulating 
%     the style, orders, and coefficients (if specified) of the conditional mean
%     and variance specifications of a GARCH model. It also encapsulates the 
%     parameters associated with the function FMINCON of the MATLAB Optimization
%     Toolbox. Type "help fmincon" or "help optimset" for additional details.
%
% Examples:
%   spec = garchset('P',1,'Q',1)     % Create a GARCH(P=1,Q=1) model.
%   spec = garchset(spec,'Q',2)      % Change it to a GARCH(P=1,Q=2) model.
% 
% GARCHSET Parameters:
%      Comment - Summary comment. [ string | {model summary string} ]
%            R - Conditional mean model order of an ARMA(R,M) model.
%                [ non-negative integer scalar | {0} ]
%            M - Conditional mean model order of an ARMA(R,M) model.
%                [ non-negative integer scalar | {0} ]
%            P - Conditional variance model order of an GARCH(P,Q) model.
%                [ non-negative integer scalar | {0} ]
%            Q - Conditional variance model order of an GARCH(P,Q) model.
%                [ non-negative integer scalar | {0} ]
% Distribution - Conditional distribution of innovations.
%                [ string | {'Gaussian'} ]
%            C - Conditional mean constant. [ scalar coefficient ]
%           AR - Conditional mean auto-regressive coefficients. 
%                [ vector of R coefficients of lagged returns]
%           MA - Conditional mean moving average coefficients. 
%                [ vector of M coefficients of lagged innovations]
%      Regress - Conditional mean regression coefficients.
%                [ vector of coefficients ]
%            K - Conditional variance constant. [ positive scalar coefficient ]
%        GARCH - Conditional variance coefficients for lagged variances.
%                [ vector of P non-negative coefficients ]
%         ARCH - Conditional variance coefficients for lagged squared residuals. 
%                [ vector of Q non-negative coefficients ]
%         FixC - Equality constraint indicator for C coefficient of the 
%                conditional mean. [ Boolean scalar | {0} ]
%        FixAR - Equality constraint indicator for AR coefficients of the 
%                conditional mean. [ Boolean vector | {zeros} ]
%        FixMA - Equality constraint indicator for MA coefficients of the 
%                conditional mean. [ Boolean vector | {zeros} ]
%   FixRegress - Equality constraint indicator for REGRESS coefficients of the 
%                conditional mean. [ Boolean vector | {zeros} ]
%         FixK - Equality constraint indicator for K coefficient of the 
%                conditional variance. [ Boolean scalar | {0} ]
%     FixGARCH - Equality constraint indicator for GARCH coefficients of the 
%                conditional variance. [ Boolean vector | {zeros} ]
%      FixARCH - Equality constraint indicator for ARCH coefficients of the 
%                conditional variance. [ Boolean vector | {zeros} ]
%      Display - Optimization iteration display flag. [ string | 'off' | {'on'}]
%  MaxFunEvals - Maximum number of objective function evaluations allowed.
%                [ positive integer]
%      MaxIter - Maximum number of iterations allowed. 
%                [ positive integer | {400}]
%       TolCon - Termination tolerance on the constraint violation.
%                [ positive scalar | {1e-006}]
%       TolFun - Termination tolerance on the objective function value.
%                [ positive scalar | {1e-006}]
%         TolX - Termination tolerance on parameter estimates. 
%                [ positive scalar | {1e-006}]
%
% See also GARCHGET, GARCHFIT, GARCHSIM, GARCHPRED, OPTIMSET.

% Copyright 1999-2002 The MathWorks, Inc.   
% $Revision: 1.13 $  $Date: 2002/03/11 19:37:14 $
  

%
% Print out possible values of properties.
%

if (nargin == 0) & (nargout == 0)
   fprintf('\n');

   fprintf('      Comment: [ String ]\n\n');

   fprintf('            R: [ non-negative integer scalar | {0} ]\n');
   fprintf('            M: [ non-negative integer scalar | {0} ]\n\n');
   fprintf('            P: [ non-negative integer scalar | {0} ]\n');
   fprintf('            Q: [ non-negative integer scalar | {0} ]\n\n');

   fprintf(' Distribution: [ string | {''Gaussian''} ]\n\n');
   fprintf('            C: [ scalar coefficient ]\n\');
   fprintf('           AR: [ vector of coefficients ]\n');
   fprintf('           MA: [ vector of coefficients ]\n');
   fprintf('      Regress: [ vector of coefficients ]\n\n');

   fprintf('            K: [ positive scalar coefficient ]\n');
   fprintf('        GARCH: [ vector of non-negative coefficients ]\n');
   fprintf('         ARCH: [ vector of non-negative coefficients ]\n\n');

   fprintf('         FixC: [ Boolean scalar | {0} ]\n');
   fprintf('        FixAR: [ Boolean vector | {zeros} ]\n');
   fprintf('        FixMA: [ Boolean vector | {zeros} ]\n');
   fprintf('   FixRegress: [ Boolean vector | {zeros} ]\n\n');

   fprintf('         FixK: [ Boolean scalar | {0} ]\n');
   fprintf('     FixGARCH: [ Boolean vector | {zeros} ]\n');
   fprintf('      FixARCH: [ Boolean vector | {zeros} ]\n\n');

   fprintf('      Display: [ string | ''off'' | {''on''}]\n');
   fprintf('  MaxFunEvals: [ positive integer ]\n');
   fprintf('      MaxIter: [ positive integer | {400}]\n');
   fprintf('       TolFun: [ positive scalar | {1e-006} ]\n');
   fprintf('       TolCon: [ positive scalar | {1e-006} ]\n');
   fprintf('         TolX: [ positive scalar | {1e-006} ]\n\n');

   return;
end

%
% The template no longer supports the OLDOPTS structure updated by a NEWOPTS
% structure, as OPTIMSET did. Thus, if any input beyond the first is a 
% structure, then flag an error.
%

for i = 2:nargin
   if isstruct(varargin{i})
      error(' Only the first input may be structure.');
   end
end

Names = [
   'Comment     '
   'R           '
   'M           '
   'P           '
   'Q           '
   'Distribution'
   'C           '
   'AR          '
   'MA          '
   'Regress     '
   'K           '
   'GARCH       '
   'ARCH        '
   'FixC        '
   'FixAR       '
   'FixMA       '
   'FixRegress  '
   'FixK        '
   'FixGARCH    '
   'FixARCH     '
   'Display     '
   'MaxFunEvals '
   'MaxIter     '
   'TolFun      '
   'TolCon      '
   'TolX        '
];


[m , n] = size(Names);
names   = lower(Names);

% Combine all leading options structures o1, o2, ... in optimset(o1,o2,...).

options = [];
for j = 1:m
   eval(['options.' Names(j,:) '= [];']);
end

if nargin == 0           %  Return an empty OPTIONS structure.
   options               =  rmfield(options , {'MaxFunEvals' 'MaxIter' 'TolFun' 'TolCon' 'TolX'});
   options.Optimization  =  optimset('fmincon');
   options.Optimization  =  optimset(options.Optimization , 'Display'     , 'iter');
   options.Optimization  =  optimset(options.Optimization , 'Diagnostics' , 'on');
   options.Optimization  =  optimset(options.Optimization , 'LargeScale'  , 'off');
   options               =  garchset(options , 'P' , 1 , 'Q' , 1);
   return
end

%
% Allow for the case when the first input is an existing OPTIONS structure
% to update. In this case, retain the sub-structure parameters associated
% with the optimization function FMINCON.
%

if isfield(varargin{1} , 'Optimization')
   argSave  =  varargin{1}.Optimization;
else
   argSave  =  [];
end


i = 1;
while i <= nargin
   arg = varargin{i};
   if isstr(arg)                         % arg is an option name
      break;
   end
   if ~isempty(arg)                      % [] is a valid options argument
      if ~isa(arg,'struct')
         error(sprintf(['Expected argument %d to be a string parameter name ' ...
               'or an options structure\ncreated with GARCHSET.'], i));
      end
      for j = 1:m
         if any(strcmp(fieldnames(arg),deblank(Names(j,:))))
            eval(['val = arg.' Names(j,:) ';']);
         else
            val = [];
         end
         if ~isempty(val)
            eval(['options.' Names(j,:) '= val;']);
         end
      end
   end
   i = i + 1;
end

% A finite state machine to parse name-value pairs.
if rem(nargin-i+1,2) ~= 0
   error('Arguments must occur in name-value pairs.');
end
expectval = 0;                          % start expecting a name, not a value
while i <= nargin
   arg = varargin{i};
   
   if ~expectval
      if ~isstr(arg)
         error(sprintf('Expected argument %d to be a string parameter name.', i));
      end
      
      lowArg = lower(arg);
      j = strmatch(lowArg,names);
      if isempty(j)                       % if no matches
         error(sprintf('Unrecognized parameter name ''%s''.', arg));
      elseif length(j) > 1                % if more than one match
         % Check for any exact matches (in case any names are subsets of others)
         k = strmatch(lowArg,names,'exact');
         if length(k) == 1
            j = k;
         else
            msg = sprintf('Ambiguous parameter name ''%s'' ', arg);
            msg = [msg '(' deblank(Names(j(1),:))];
            for k = j(2:length(j))'
               msg = [msg ', ' deblank(Names(k,:))];
            end
            msg = sprintf('%s).', msg);
            error(msg);
         end
      end
      expectval = 1;                      % we expect a value next
      
   else
      eval(['options.' Names(j,:) '= arg;']);
      expectval = 0;
      
   end
   i = i + 1;
end

if expectval
   error(sprintf('Expected value for parameter ''%s''.', arg));
end

%
%         * * * * *  Error/consistency checks & default setting.  * * * * * 
%

%
% Check Auto-Regressive & Moving-Average specifications. 
%
% Note: The AR & MA coefficients are SPECIFIED as a user would read
%       them from a difference equation written in recursive form. 
%       However, when TESTING for AR stationarity and MA invertibility, 
%       a polynomial is formed whose roots are the eigenvalues. The AR/MA
%       process is stationary/invertible only if ALL eigenvalues lie inside
%       the unit circle. 
%
% Example: Consider the ARMA(2,2) model with difference equation 
%
%       y(t) = 0.6y(t-1) + 0.2y(t-1) + e(t) - 0.6e(t-1) + 0.08e(t-2)
%
%       The AR coefficient vector would be entered as [ 0.6  0.20].
%       The MA coefficient vector would be entered as [-0.6  0.08].
%
%       The AR polynomial equation is 
%
%              (z^2 - 0.6z - 0.20) = 0 
%
%       with roots (eigenvalues) z = (0.84 , -0.24) (see Hamilton, page 13).
%
%       The MA polynomial equation is 
%
%              (z^2 - 0.6z + 0.08) = 0
%
%       with roots (eigenvalues) z = (0.4 , 0.2) (see Hamilton, page 31).
%       
%       Thus, the AR coefficients are negated when determining the 
%       roots of the AR polynomial.
%

errorCode  =  errorCheck(options.R , -options.AR , [1 2 4 5 6 9]);

switch errorCode(1)
   case {1 , 2 , 4}
      error(' Auto-regressive order ''R'' must be a non-negative, integer, scalar.');
   case 5
      error(' Auto-regressive coefficients ''AR'' must be a vector.');
   case 6
      error(' Roots of ''AR'' polynomial must lie outside unit circle.');
   case 9
      error(' Length of ''AR'' vector must equal auto-regressive order ''R''.');
   otherwise
      if ~isempty(options.AR)
         options.AR  =  options.AR(:)';
         if isempty(options.R) , options.R  = length(options.AR); end
      end
end

%
% Check Moving-Average specification.
%

errorCode  =  errorCheck(options.M , options.MA , [1 2 4 5 6 9]);

switch errorCode(1)
   case {1 , 2 , 4}
      error(' Moving-average order ''M'' must be a non-negative, integer, scalar.');
   case 5
      error(' Moving-average coefficients ''MA'' must be a vector.');
   case 6
      error(' Roots of ''MA'' polynomial must lie outside unit circle.');
   case 9
      error(' Length of ''MA'' vector must equal moving-average order ''M''.');
   otherwise
      if ~isempty(options.MA)
         options.MA  =  options.MA(:)'; 
         if isempty(options.M) , options.M  = length(options.MA); end
      end
end

%
% Check GARCH parameter specification.
%

errorCode  =  errorCheck(options.P , options.GARCH , [1 2 4 5 7 8 9]);

switch errorCode(1)
   case {1 , 2 , 4}
      error(' GARCH model order ''P'' must be a non-negative, integer, scalar.');
   case 5
      error(' GARCH coefficients ''GARCH'' must be a vector.');
   case 7
      error(' GARCH coefficients ''GARCH'' must be non-negative.');
   case 8
      error(' Sum of GARCH coefficients must be < 1.')
   case 9
      error(' Length of ''GARCH'' coefficient vector must equal model order ''P''.');
   otherwise
      if ~isempty(options.GARCH)
         options.GARCH  =  options.GARCH(:)'; 
         if isempty(options.P) , options.P  = length(options.GARCH); end
      end
end

%
% Check ARCH parameter specification.
%

errorCode  =  errorCheck(options.Q , options.ARCH , [1 2 4 5 7 8 9]);

switch errorCode(1)
   case {1 , 2 , 4}
      error(' ARCH model order ''Q'' must be a non-negative, integer, scalar.');
   case 5
      error(' ARCH coefficients ''ARCH'' must be a vector.');
   case 7
      error(' ARCH coefficients ''ARCH'' must be non-negative.');
   case 8
      error(' Sum of ARCH coefficients must be < 1.')
   case 9
      error(' Length of ''ARCH'' coefficient vector must equal model order ''Q''.');
   otherwise
      if ~isempty(options.ARCH)
         options.ARCH  =  options.ARCH(:)';
         if isempty(options.Q) , options.Q  = length(options.ARCH); end
      end
end

%
% Check combined ARCH/GARCH parameters.
%

errorCode  =  errorCheck([] , [options.ARCH(:) ; options.GARCH(:)] , 8);

if errorCode == 8
   error(' Sum of ARCH + GARCH coefficients must be < 1.')
end

%
% Check constant associated with the conditional variance model specification.
%

errorCode  =  errorCheck(options.K , [] , [3 4]);

switch errorCode(1)
   case {3 , 4} , error(' Variance model constant ''K'' must be a positive scalar.')
end

%
% Check constant associated with the conditional mean model specification.
%

errorCode  =  errorCheck(options.C , [] , 4);

if errorCode == 4
   error(' Mean model constant ''C'' must be a scalar.')