\HeaderA{GarchModelling}{Univariate GARCH Time Series Modelling}{GarchModelling}
\aliasA{fGARCH-class}{GarchModelling}{fGARCH.Rdash.class}
\aliasA{fitted.fGARCH}{GarchModelling}{fitted.fGARCH}
\aliasA{garchFit}{GarchModelling}{garchFit}
\aliasA{garchKappa}{GarchModelling}{garchKappa}
\aliasA{garchSim}{GarchModelling}{garchSim}
\aliasA{garchSpec}{GarchModelling}{garchSpec}
\aliasA{garchSpec-class}{GarchModelling}{garchSpec.Rdash.class}
\aliasA{plot.fGARCH}{GarchModelling}{plot.fGARCH}
\aliasA{predict.fGARCH}{GarchModelling}{predict.fGARCH}
\aliasA{print.fGARCH}{GarchModelling}{print.fGARCH}
\aliasA{print.garchSpec}{GarchModelling}{print.garchSpec}
\aliasA{residuals.fGARCH}{GarchModelling}{residuals.fGARCH}
\aliasA{summary.fGARCH}{GarchModelling}{summary.fGARCH}
\keyword{models}{GarchModelling}
\begin{Description}\relax
A collection and description of functions to 
simulate artificial ARCH time series processes, 
to fit the parameters of univariate time series 
to ARCH models, to perform a diagnostic analysis of 
the fit, and to predict future values of the time 
series.
\\

The family of GARCH time series models includes the following 
processes:

\Tabular{ll}{
\code{garch} & generalized AR conditional heteroskedastic models, \\
\code{aparch} & asymmetric power GARCH models.}

Included functions are:

\Tabular{ll}{
\code{garchSpec} & Specifies a GARCH model, \\
\code{garchSim} & simulates a GARCH process, \\
\code{garchFit} & fits parameters of a GARCH model, \\
\code{garchKappa} & computes ARCH expectation value.}

Included methods are:

\Tabular{ll}{
\code{print} & Prints results from a GARCH fit, \\
\code{summary} & creates a summary report from a GARCH fit, \\
\code{plot} & creates diagnostic plots for a fitted GARCH process, \\
\code{residuals} & returns residuals for a GARCH model, \\
\code{fitted} & returns fitted values for a GARCH model, \\
\code{predict} & predicts mean and variance from a GARCH model.}

\bold{Note:} This collection is still under a complete
reconstruction.
\end{Description}
\begin{Usage}
\begin{verbatim}
garchSpec(model = list(omega = 1.0e-6, alpha = 0.1, beta = 0.8), 
    presample = NULL, cond.dist = c("rnorm", "rged", "rstd", "rsnorm", 
    "rsged", "rsstd"), rseed = NULL)
## S3 method for class 'garchSpec':
print(x, ...)

garchSim(model = list(omega = 1.0e-6, alpha = 0.1, beta = 0.8), n = 100, 
    n.start = 100, presample = NULL, cond.dist = c("rnorm", "rged", "rstd", 
    "rsnorm", "rsged", "rsstd"), rseed = NULL)
    
garchFit(formula.mean = ~arma(0, 0), formula.var = ~garch(1, 1), 
    series = x, init.rec = c("mci", "uev"), delta = 2, skew = 1, shape = 4,
    cond.dist = c("dnorm", "dsnorm", "dged", "dsged", "dstd", "dsstd"), 
    include.mean = TRUE, include.delta = NULL, include.skew = NULL,
    include.shape = NULL, leverage = NULL, trace = TRUE,  
    algorithm = c("sqp", "nlminb", "lbfgsb", "nlminb+nm", "lbfgsb+nm"), 
    control = list(), title = NULL, description = NULL, ...)
    
garchKappa(cond.dist = c("dnorm", "dged", "dstd", "dsnorm", "dsged", "dsstd"), 
    gamma = 0, delta = 2, skew = NA, shape = NA)

## S3 method for class 'fGARCH':
print(x, ...)
## S3 method for class 'fGARCH':
summary(object, ...)
## S3 method for class 'fGARCH':
plot(x, which = "ask", ...)
## S3 method for class 'fGARCH':
residuals(object, ...)
## S3 method for class 'fGARCH':
fitted(object, ...)
## S3 method for class 'fGARCH':
predict(object, n.ahead = 10, trace = FALSE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{algorithm}] [garchFit] - \\
a string parameter that determines the algorithm used for maximum 
likelihood estimation. Allowed values are \code{"sqp"}, 
\code{"nlminb"}, and \code{"bfgs"} where the first is the default
setting.

\item[\code{cond.dist}] [garchSpec, garchSim, garchFit] - \\
a character string naming the desired conditional distribution.
Valid values are \code{"dnorm"}, \code{"dged"}, \code{"dstd"}, 
\code{"dsnorm"}, \code{"dsged"}, \code{"dsstd"}. The default value 
is the normal distribution.

\item[\code{control}] [garchFit] - \\
control parameters, the same as used for the functions from
\code{nlminb}, and 'bfgs' and 'Nelder-Mead' from \code{optim}.

\item[\code{delta, include.delta}] [garchFit][kappa] - \\
the exponent \code{delta} of the variance recursion. By default,
this value will be fixed, otherwise the exponent will be estimated 
together with the other model parameters if \code{include.delta=FALSE}.

\item[\code{description}] [garchFit] - \\
a character string which allows for a brief description. 

\item[\code{formula.mean, formula.var}] [garchFit] - \\
two formula objects describing the mean and variance equation
of the ARMA-GARCH/APARCH model. By default a pure GARCH(1,1)
mode is selected, this means: \code{formula.mean=\textasciitilde{}arma(0,0)}, 
and \code{formula.var=\textasciitilde{}garch(1,1)}. To specify for example an 
APARCH(1,1) use: \code{formula.var=\textasciitilde{}apaarch(1,1)}

\item[\code{gamma}] [kappa] - \\
APARCH leverage parameter entering into the formula for calculating
the expectation value.

\item[\code{include.mean}] this flag determines if the parameter for the mean will be estimated
or not. If \code{include.mean=TRUE} this will be the case, otherwise
the parameter will be kept fixed durcing the process
of parameter optimization.

\item[\code{include.skew, include.shape}] this flag determines if the parameters for the skew and shape
of the conditional distribution will be estimated or not. If 
\code{include.skew=TRUE} and/or \code{include.shape=TRUE} this will 
be the case, otherwise the parameters will be kept fixed durcing 
the process of parameter optimization.

\item[\code{init.rec}] [garchFit] - \\
a character string indicating the method how to initialize the 
mean and varaince recursion relation. 

\item[\code{leverage}] a logical flag for APARCH models. Should the model be leveraged?
By default \code{leverage=TRUE}.

\item[\code{model}] [garchSpec, garchSim] - \\
List of GARCH model parameters: \\
\code{omega} - the constant coefficient of the variance equation; \\
\code{alpha} - the vector of autoregressive coefficients; \\
\code{beta} - the vector of variance coefficients; \\
Further Optional Values: \\
\code{mu} - the mean value; \\
\code{ar} - the autoregressive ARMA coefficients; \\
\code{ma} - the moving average ARMA coefficients; \\
\\
The default model is Bollerslev's GARCH(1,1) model.

\item[\code{n}] [garchSim] - \\
length of output series, an integer value. An integer value,
by default \code{n=100}.

\item[\code{n.ahead}] [predict] - \\ 
number of steps to be forecasted, an integer value, by default 10.

\item[\code{n.start}] [garchSim] - \\
length of "burn-in" period, by default 100.

\item[\code{object}] [predict][summary] - \\
an object of class \code{fGARCH} as returned from the function
\code{garchFit()}.

\item[\code{presample}] a numeric three column matrix with start values for the series, 
innovations, and conditional variances. For an ARMA(m,n)-GARCH(p,q)
process the number of rows must be at least max(m,n,p,q), longer 
presamples are cutted.

\item[\code{rseed}] [garchSpec][garchSpec] - \\
single integer argument, the seed for the intitialization of
the random number generator for the innovations.

\item[\code{series}] [garchFit] - \\
a numeric vector or univariate \code{timeSeries} object to be 
fitted. By default \code{series=x}.

\item[\code{skew, shape}] [garchFit][kappa] - \\
skewness and shape parameter of the conditional distribution.

\item[\code{title}] [garchFit][predict] - \\
a character string which allows for a project title.

\item[\code{trace}] [garchFit] - \\
a logical flag. Should the optimization process of fitting the
model parameters be printed? By default \code{trace=TRUE}.\\{}
[predict] - \\
a logical flag. Should the prediction process be printed? By 
default \code{trace=FALSE}.

\item[\code{which}] if \code{which} is set to \code{"ask"} the function will 
interactively ask which plot should be displayed. This is
the default value and then those plots will
be displayed for which the elements in the logical vector
\code{which} ar set to \code{TRUE}; by default all four
elements are set to \code{"all"}.

\item[\code{x}] [print][plot]  - \\
either an object of class \code{garchSpec} for printing specification
structures, or an object of class \code{fGARCH} for printing fitted
GARCH/APARCH models or plotting results from the diagnostic analysis
of fitted models.

\item[\code{...}] additional arguments to be passed.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\bold{Parameter Estimation:}
\\\\
\code{garchFit} uses the \code{nlminb()} optimizer to find the maximum
likelihood estimates.

\bold{Residuals Methods:}
\\\\
The method for the computation of the residuals may have an additional
argument named \code{standardize} which allows to standardize the 
residuals by the conditional variances.
\end{Details}
\begin{Value}
\code{garchSpec}\\
\\
returns a S4 object of class \code{fGARCH} with the following slots:

\begin{ldescription}
\item[\code{@call}] the call of the \code{garch} function.

\item[\code{@formula}] a list with two formula entries for the mean and variance 
equation.

\item[\code{@model}] a list with the model parameters.

\item[\code{@presample}] a numeric matrix with presample values.

\item[\code{@distribution}] a character string with the name of the conditional distribution.

\item[\code{@call}] the call of the \code{garch} function.

\item[\code{@formula}] a list with two formula entries, one for the mean and the other
one for the variance equation.

\item[\code{@method}] a string denoting the optimization method, by default the 
returneds string is "Max Log-Likelihood Estimation".

\item[\code{@data}] a list with one entry named \code{x}, containing the data of
the time series to be estimated, the same as given by the
input argument \code{series}.

\item[\code{@fit}] a list with the results from the parameter estimation. The entries
of the list depend on the selected algorithm, see below.

\item[\code{@residuals}] a numeric vector with the residual values.

\item[\code{@fitted.values}] a numeric vector with the fitted values.

\item[\code{@cvariances}] a numeric vector with the conditional variances.

\item[\code{@title}] a title string.

\item[\code{@description}] a string with a brief description.

\item[\code{\$par}] The best set of parameters found.

\item[\code{\$value}] The value of the max log likelihood function corresponding to 
the optimal values of \code{\$par}.

\item[\code{\$counts}] A two-element integer vector giving the number of calls to
'fn' and 'gr' respectively. This excludes those calls needed
to compute the Hessian, if requested, and any calls to 'fn'
to compute a finite-difference approximation to the gradient.

\item[\code{\$convergence}] An integer code. '0' indicates successful convergence. Values 
different from zero indicate an error code. For details, please 
consult the help page of \code{optim}.

\item[\code{message}] 
\item[\code{hessian}] Only if control list argument \code{hessian} is true. A 
symmetric matrix giving an estimate of the Hessian at the 
solution found. Note that this is the Hessian of the 
unconstrained problem even if the box constraints are active.

\item[\code{\$par}] The best set of parameters found.

\item[\code{\$value}] The value of the max log likelihood function corresponding to 
the optimal values of \code{\$par}.

\end{ldescription}
\end{Value}
\begin{Note}\relax
\bold{What's next?} 
\\\\
The software will be extended to further GARCH models including 
integrated GARCH models, EGARCH models, GARCH-in-Mean models as 
well as fractionally integrated GARCH models. In the next version 
also the fixing of individual ARMA-GARCH/APARCH coefficients will 
become available. Furthermore, we will provide additional conditional 
distribution functions including for example members from the family 
of the hyperbolic distribution. Concerning performance analysis we 
plan to offer in addition several performance measures for the 
residuals like Theil's inequality coefficient, and Mincer and 
Zarnowitz's R2 coefficient. Concerning hypothesis testing we will 
add some specific tests including Engle's LM ARCH test to test 
the presence of ARCH effects, Engle and Ng's test to investigate 
possible misspecifications of the conditional variance equation, 
and Nyblom's test to check the constancy of model parameters over 
time.
\end{Note}
\begin{Author}\relax
Diethelm Wuertz for the Rmetrics \R-port,\\
R Core Team for the 'optim' \R-port,\\
Douglas Bates and Deepayan Sarkar for the 'nlminb' \R-port,\\
Bell-Labs for the underlying PORT Library,\\
Ladislav Luksan for the underlying SQP Routine, \\
Zhu, Byrd, Lu-Chen and Nocedal for the underlying L-BFGS-B Routine.
\end{Author}
\begin{References}\relax
ATT (1984);
\emph{PORT Library Documentation}, 
http://netlib.bell-labs.com/netlib/port/.

Bera A.K., Higgins M.L. (1993);
\emph{ARCH Models: Properties, Estimation and Testing},
J. Economic Surveys 7, 305--362.

Bollerslev T. (1986);
\emph{Generalized Autoregressive Conditional Heteroscedasticity},
Journal of Econometrics 31, 307--327.

Byrd R.H., Lu P., Nocedal J., Zhu C. (1995);
\emph{A Limited Memory Algorithm for Bound Constrained Optimization},
SIAM Journal of Scientific Computing 16, 1190--1208.

Engle R.F. (1982);
\emph{Autoregressive Conditional Heteroscedasticity with Estimates 
of the Variance of United Kingdom Inflation},
Econometrica 50, 987--1008.

Nash J.C. (1990);
\emph{Compact Numerical Methods for Computers},
Linear Algebra and Function Minimisation,
Adam Hilger.

Nelder J.A., Mead R. (1965);
\emph{A Simplex Algorithm for Function Minimization},
Computer Journal 7, 308--313.

Nocedal J., Wright S.J. (1999);
\emph{Numerical Optimization},
Springer, New York.
\end{References}
\begin{Examples}
\begin{ExampleCode}
## SOURCE("fSeries1.34C-GarchModelling")
## Not run: 
#   garchSpec -
#   garchSim - 
#   garchFit -

    # For examples we refer to: demo/xmpDWChapter34.R ...
## End(Not run)
\end{ExampleCode}
\end{Examples}

