Create environment for mc-fitting

Creates an environment for mc-fitting. These functions are transitory, hence the strange names.

Usage

mC.ss(spec, ...)

xx.ss(period, type.eigval, n.root, eigabs, eigsign, co_r, co_arg, 
      init = NULL, len.block = NULL, mo.col, generators = NULL)

Arguments

spec: a model, an object of class mcSpec.
...: further arguments to be passed on to xx.ss.
period: the number of seasons.
type.eigval: types of the eigenvalues, a character vector with elements "r" or "cp", see Details.
n.root: number of roots. Currently the dimension of the matrix is set to this.
eigabs: The absolute values/moduli of the eigenvalues, numeric vector.
eigsign: The signs/moduli of the eigenvalues.
co_r: similar to eigabs but for the co parameters.
co_arg: similar to eigsign but for the co parameters.
init: initial values, see Details.
len.block: lengths of Jordan blocks.
mo.col: last non-zero column in the top of the matrix.
generators: ~~ TODO: describe this argument. ~~

Details

mC.ss takes the specification of the model as an object of class mcSpec and calls xx.ss.

Basically, the value returned by these functions is an extended model specification together with an environment which can be used for fitting the model, exploring the results and trying various things. This may be used for getting better understanding of the model and the optimisation routines.

The result of both functions is a list, containing several functions and an environment. The environment (element env) is the most important element since it allows access to everything in the model environment. The function elements of the list are simply a convenience.

Several functions in env are available for fitting the model. Currently these are minim, minimBB and minimBBlu. The first argument of all these functions is a time series to which the model is to be fitted. By default, a conditional likelihood is being optimised. To base the optimisation on conditional sum of squares, set argument CONDLIK to FALSE. The remaining arguments in a call to any of the above functions are passed on to the corresponding optimisation routine (whose help page should be consulted for details).

minim uses the core R function optim. minimBB and minimBBlu use BBoptim from package BB. They result is a list, as returned by the corresponding optimisation function with the optimal parameters in element par. The elements of this vector are named to help somewhat in its interpretation but complete information about the fitted model can be obtained from the environment.

Firstly, at the end of the optimisation, the optimal parameters and other information are stored in env. If the same call (maybe with modified instructions for the optimisation) is repeated, these parameters will be used as initial values for a new optimisation run. This may be useful, for example, if the previous run didn't converge.

Secondly, properties of the fitted model and more useful representations can be obtained using functions in the environment or the convinience functions in the list returned by xx.ss.

optparam2mcparam converts a vector of parameters into the more familiar filter representation, where the i-th row contains the coefficients for the i-th season. This function takes one argument the vector of parameters, e.g. the one returned by the fitting functions. It updates a number of variables in env, computes the filter representation of the model and stores it in wrkmodel. It returns NULL. This function may be used for exploratory purposes or to set new values for the parameters, e.g. to be used as starting values for a new optimisation run.

mcparam2optparam does the opposite. It converts the current model in env to a vector of parameter. This function does not have arguments.

mclik computes the value of the conditional likelihood for given parameters. Its first argument is a time series, the second is a vector of parameters and the third is a vector of innovations. Only the first argument is compulsory. If param is not supplied, the current parameters in env are used. Otherwise, they are updated with the new parameters and then used. The innovations default to the zero vector. mcss is similar but computes the conditional sum of squares.

Argument init can be used to provide initial values. If it is missing or NULL, random initial values are generated for the free parameters. init may also be a numeric vector suitable for the call optparam2mcparam(init), see above. This vector would typically come from a previous optimisation run.

init may also be a list with elements "eigabs", "eigsign", "co_r", "co_abs". These components have the same meaning as the corresponding arguments of xx.ss.

TODO: more is needed here!

Value

A list with the following components:

fmcss: a function to compute the sum of squares for a model.
fparamvec: a function to convert mc-parameters to optimisation parameters.
fmcparam: a function to convert optimisation parameters to mc-parameters.
env: an object of class environment

References

Boshnakov GN, Iqelan BM (2009). “Generation of time series models with given spectral properties.” J. Time Series Anal., 30(3), 349--368. ISSN 0143-9782, doi: 10.1111/j.1467-9892.2009.00617.x .

Author

Georgi N. Boshnakov

Examples

# test0 roots
spec.coz2 <- mcompanion::mcSpec(dim = 5, mo = 4, root1 = c(1,1), order = rep(2,4))
spec.coz2
#> An object of class "mcSpec"
#> Slot "dim":
#> [1] 5
#> 
#> Slot "mo":
#> [1] 4
#> 
#> Slot "ev.type":
#> [1] "r" "r" "r" "r" "r"
#> 
#> Slot "co.type":
#> character(0)
#> 
#> Slot "order":
#> [1] 2 2 2 2
#> 
#> Slot "n.root":
#> [1] 2
#> 
#> Slot "ev.abs":
#> [1] 1 1 0 0 0
#> 
#> Slot "ev.arg":
#> [1] 0 0 0 0 0
#> 
#> Slot "block.length":
#> [1] 1 1 1 1 1
#> 
#> Slot "co.abs":
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]   NA   NA    0    0    0
#> [2,]   NA   NA    1    0    0
#> [3,]   NA   NA    0    1    0
#> [4,]   NA   NA    0    0    1
#> 
#> Slot "co.arg":
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]   NA   NA    0    0    0
#> [2,]   NA   NA    0    0    0
#> [3,]   NA   NA    0    0    0
#> [4,]   NA   NA    0    0    0
#> 
#> Slot "mo.col":
#> [1] 2
#> 
#> Slot "F0bot":
#> NULL
#> 
xxcoz2a <- mC.ss(spec.coz2)

## test0 roots
spec.coz4 <- mcompanion::mcSpec(dim = 5, mo = 4, root1 = c(1,1), order = rep(3,4))
xxcoz4a <- mC.ss(spec.coz4)