data |
a matrix or class 'ts' object with d>1 columns. Each column is taken to represent
a univariate time series. NA values are not supported.
|
p |
a positive integer specifying the autoregressive order of the model.
|
M |
- For GMVAR and StMVAR models:
a positive integer specifying the number of mixture components.
- For G-StMVAR models:
a size (2x1) integer vector specifying the number of GMVAR type components M1
in the first element and StMVAR type components M2 in the second element. The total number of mixture components
is M=M1+M2.
|
model |
is "GMVAR", "StMVAR", or "G-StMVAR" model considered? In the G-StMVAR model, the first M1 components
are GMVAR type and the rest M2 components are StMVAR type.
|
conditional |
a logical argument specifying whether the conditional or exact log-likelihood function
|
parametrization |
"intercept" or "mean" determining whether the model is parametrized with intercept
parameters \phi_{m,0} or regime means \mu_{m}, m=1,...,M.
|
constraints |
a size (Mpd^2 x q) constraint matrix C specifying general linear constraints
to the autoregressive parameters. We consider constraints of form
(\phi_{1},...,\phi_{M}) = C \psi,
where \phi_{m} = (vec(A_{m,1}),...,vec(A_{m,p}) (pd^2 x 1), m=1,...,M,
contains the coefficient matrices and \psi (q x 1) contains the related parameters.
For example, to restrict the AR-parameters to be the same for all regimes, set C=
[I:...:I]' (Mpd^2 x pd^2) where I = diag(p*d^2).
Ignore (or set to NULL) if linear constraints should not be employed.
|
same_means |
Restrict the mean parameters of some regimes to be the same? Provide a list of numeric vectors
such that each numeric vector contains the regimes that should share the common mean parameters. For instance, if
M=3, the argument list(1, 2:3) restricts the mean parameters of the second and third regime to be
the same but the first regime has freely estimated (unconditional) mean. Ignore or set to NULL if mean parameters
should not be restricted to be the same among any regimes. This constraint is available only for mean parametrized models;
that is, when parametrization="mean".
|
weight_constraints |
a numeric vector of length M-1 specifying fixed parameter values for the mixing weight parameters
\alpha_m, \ m=1,...,M-1. Each element should be strictly between zero and one, and the sum of all the elements should
be strictly less than one.
|
structural_pars |
If NULL a reduced form model is considered. Reduced models can be used directly as recursively
identified structural models. For a structural model identified by conditional heteroskedasticity, should be a list containing
at least the first one of the following elements:
-
W - a (dxd) matrix with its entries imposing constraints on W: NA indicating that the element is
unconstrained, a positive value indicating strict positive sign constraint, a negative value indicating strict
negative sign constraint, and zero indicating that the element is constrained to zero.
-
C_lambda - a (d(M-1) x r) constraint matrix that satisfies (\lambda_{2},...,
\lambda_{M}) = C_{\lambda} \gamma where \gamma is the new (r x 1)
parameter subject to which the model is estimated (similarly to AR parameter constraints). The entries of C_lambda
must be either positive or zero. Ignore (or set to NULL) if the eigenvalues \lambda_{mi}
should not be constrained.
-
fixed_lambdas - a length d(M-1) numeric vector (\lambda_{2},...,
\lambda_{M}) with elements strictly larger than zero specifying the fixed parameter values for the
parameters \lambda_{mi} should be constrained to. This constraint is alternative C_lambda.
Ignore (or set to NULL) if the eigenvalues \lambda_{mi} should not be constrained.
See Virolainen (forthcoming) for the conditions required to identify the shocks and for the B-matrix as well (it is W times
a time-varying diagonal matrix with positive diagonal entries).
|
ngen |
a positive integer specifying the number of generations to be ran through in
the genetic algorithm.
|
popsize |
a positive even integer specifying the population size in the genetic algorithm.
Default is 10*n_params.
|
smart_mu |
a positive integer specifying the generation after which the random mutations
in the genetic algorithm are "smart". This means that mutating individuals will mostly mutate fairly
close (or partially close) to the best fitting individual (which has the least regimes with time varying
mixing weights practically at zero) so far.
|
initpop |
a list of parameter vectors from which the initial population of the genetic algorithm
will be generated from. The parameter vectors should be...
- For unconstrained models:
-
Should be size ((M(pd^2+d+d(d+1)/2+2)-M1-1)x1) and have the form
\theta = (\upsilon_{1},
...,\upsilon_{M}, \alpha_{1},...,\alpha_{M-1},\nu), where
-
\upsilon_{m} = (\phi_{m,0},\phi_{m},\sigma_{m})
-
\phi_{m} = (vec(A_{m,1}),...,vec(A_{m,p})
and \sigma_{m} = vech(\Omega_{m}), m=1,...,M,
-
\nu=(\nu_{M1+1},...,\nu_{M})
-
M1 is the number of GMVAR type regimes.
- For constrained models:
-
Should be size ((M(d+d(d+1)/2+2)+q-M1-1)x1) and have the form
\theta = (\phi_{1,0},...,\phi_{M,0},\psi,
\sigma_{1},...,\sigma_{M},\alpha_{1},...,\alpha_{M-1},\nu), where
- For same_means models:
-
Should have the form
\theta = (\mu,\psi,
\sigma_{1},...,\sigma_{M},\alpha_{1},...,\alpha_{M-1},\nu), where
-
\mu= (\mu_{1},...,\mu_{g}) where
\mu_{i} is the mean parameter for group i and
g is the number of groups.
If AR constraints are employed, \psi is as for constrained
models, and if AR constraints are not employed, \psi =
(\phi_{1},...,\phi_{M}).
- For structural models:
-
Should have the form
\theta = (\phi_{1,0},...,\phi_{M,0},\phi_{1},...,\phi_{M},
vec(W),\lambda_{2},...,\lambda_{M},\alpha_{1},...,\alpha_{M-1},\nu),
where
- If AR parameters are constrained:
Replace \phi_{1},...,
\phi_{M} with \psi (qx1) that satisfies (\phi_{1},...,
\phi_{M}) = C \psi, as above.
- If same_means:
Replace (\phi_{1,0},...,\phi_{M,0}) with (\mu_{1},...,\mu_{g}),
as above.
- If
W is constrained: Remove the zeros from vec(W) and make sure the other entries satisfy
the sign constraints.
- If
\lambda_{mi} are constrained: Replace \lambda_{2},...,\lambda_{M}
with \gamma (rx1) that satisfies (\lambda_{2},...,
\lambda_{M}) = C_{\lambda} \gamma where C_{\lambda} is a (d(M-1) x r)
constraint matrix.
Above, \phi_{m,0} is the intercept parameter, A_{m,i} denotes the ith coefficient matrix of the mth
mixture component, \Omega_{m} denotes the error term covariance matrix of the m:th mixture component, and
\alpha_{m} is the mixing weight parameter. The W and \lambda_{mi} are structural parameters replacing the
error term covariance matrices (see Virolainen, 2022). If M=1, \alpha_{m} and \lambda_{mi} are dropped.
If parametrization=="mean", just replace each \phi_{m,0} with regimewise mean \mu_{m}.
vec() is vectorization operator that stacks columns of a given matrix into a vector. vech() stacks columns
of a given matrix from the principal diagonal downwards (including elements on the diagonal) into a vector.
In the GMVAR model, M1=M and \nu is dropped from the parameter vector. In the StMVAR model,
M1=0. In the G-StMVAR model, the first M1 regimes are GMVAR type and the rest M2 regimes are
StMVAR type. In StMVAR and G-StMVAR models, the degrees of freedom parameters in \nu should
be strictly larger than two.
The notation is similar to the cited literature.
|
mu_scale |
a size (dx1) vector defining means of the normal distributions from which each
mean parameter \mu_{m} is drawn from in random mutations. Default is colMeans(data). Note that
mean-parametrization is always used for optimization in GAfit - even when parametrization=="intercept".
However, input (in initpop) and output (return value) parameter vectors can be intercept-parametrized.
|
mu_scale2 |
a size (dx1) strictly positive vector defining standard deviations of the normal
distributions from which each mean parameter \mu_{m} is drawn from in random mutations.
Default is 2*sd(data[,i]), i=1,..,d.
|
omega_scale |
a size (dx1) strictly positive vector specifying the scale and variability of the
random covariance matrices in random mutations. The covariance matrices are drawn from (scaled) Wishart
distribution. Expected values of the random covariance matrices are diag(omega_scale). Standard
deviations of the diagonal elements are sqrt(2/d)*omega_scale[i]
and for non-diagonal elements they are sqrt(1/d*omega_scale[i]*omega_scale[j]).
Note that for d>4 this scale may need to be chosen carefully. Default in GAfit is
var(stats::ar(data[,i], order.max=10)$resid, na.rm=TRUE), i=1,...,d. This argument is ignored if
structural model is considered.
|
W_scale |
a size (dx1) strictly positive vector partly specifying the scale and variability of the
random covariance matrices in random mutations. The elements of the matrix W are drawn independently
from such normal distributions that the expectation of the main diagonal elements of the first
regime's error term covariance matrix \Omega_1 = WW' is W_scale. The distribution of \Omega_1
will be in some sense like a Wishart distribution but with the columns (elements) of W obeying the given
constraints. The constraints are accounted for by setting the element to be always zero if it is subject to a zero
constraint and for sign constraints the absolute value or negative the absolute value are taken, and then the
variances of the elements of W are adjusted accordingly. This argument is ignored if reduced form model
is considered.
|
lambda_scale |
a length M - 1 vector specifying the standard deviation of the mean zero normal
distribution from which the eigenvalue \lambda_{mi} parameters are drawn from in random mutations.
As the eigenvalues should always be positive, the absolute value is taken. The elements of lambda_scale
should be strictly positive real numbers with the m-1th element giving the degrees of freedom for the mth
regime. The expected value of the main diagonal elements ij of the mth (m>1) error term covariance
matrix will be W_scale[i]*(d - n_i)^(-1)*sum(lambdas*ind_fun) where the (d x 1) vector lambdas is
drawn from the absolute value of the t-distribution, n_i is the number of zero constraints in the ith
row of W and ind_fun is an indicator function that takes the value one iff the ijth element of
W is not constrained to zero. Basically, larger lambdas (or smaller degrees of freedom) imply larger variance.
If the lambda parameters are constrained with the (d(M - 1) x r) constraint matrix C_lambda,
then provide a length r vector specifying the standard deviation of the (absolute value of the) mean zero
normal distribution each of the \gamma parameters are drawn from (the \gamma is a (r x 1) vector).
The expected value of the main diagonal elements of the covariance matrices then depend on the constraints.
This argument is ignored if M==1 or a reduced form model is considered. Default is rep(3, times=M-1)
if lambdas are not constrained and rep(3, times=r) if lambdas are constrained.
As with omega_scale and W_scale, this argument should be adjusted carefully if specified by hand. NOTE
that if lambdas are constrained in some other way than restricting some of them to be identical, this parameter
should be adjusted accordingly in order to the estimation succeed!
|
ar_scale |
a positive real number between zero and one, adjusting how large AR parameter values are typically
proposed in construction of the initial population: larger value implies larger coefficients (in absolute value).
After construction of the initial population, a new scale is drawn from (0, upper_ar_scale) uniform
distribution in each iteration. With large p or d, ar_scale is restricted from above,
see the details section.
|
upper_ar_scale |
the upper bound for ar_scale parameter (see above) in the random mutations. Setting
this too high might lead to failure in proposing new parameters that are well enough inside the parameter space,
and especially with large p one might want to try smaller upper bound (e.g., 0.5). With large p or
d, upper_ar_scale is restricted from above, see the details section.
|
ar_scale2 |
a positive real number adjusting how large AR parameter values are typically proposed in some
random mutations (if AR constraints are employed, in all random mutations): larger value implies smaller coefficients
(in absolute value). Values larger than 1 can be used if the AR coefficients are expected to be very small.
If set smaller than 1, be careful as it might lead to failure in the creation of stationary parameter candidates
|
regime_force_scale |
a non-negative real number specifying how much should natural selection favor individuals
with less regimes that have almost all mixing weights (practically) at zero. Set to zero for no favoring or large
number for heavy favoring. Without any favoring the genetic algorithm gets more often stuck in an area of the
parameter space where some regimes are wasted, but with too much favouring the best genes might never mix into
the population and the algorithm might converge poorly. Default is 1 and it gives 2x larger surviving
probability weights for individuals with no wasted regimes compared to individuals with one wasted regime.
Number 2 would give 3x larger probability weights etc.
|
red_criteria |
a length 2 numeric vector specifying the criteria that is used to determine whether a regime is
redundant (or "wasted") or not.
Any regime m which satisfies sum(mixingWeights[,m] > red_criteria[1]) < red_criteria[2]*n_obs will
be considered "redundant". One should be careful when adjusting this argument (set c(0, 0) to fully disable
the 'redundant regime' features from the algorithm).
|
pre_smart_mu_prob |
A number in [0,1] giving a probability of a "smart mutation" occuring randomly in each
iteration before the iteration given by the argument smart_mu.
|
to_return |
should the genetic algorithm return the best fitting individual which has "positive enough" mixing
weights for as many regimes as possible ("alt_ind") or the individual which has the highest log-likelihood
in general ("best_ind") but might have more wasted regimes?
|
minval |
a real number defining the minimum value of the log-likelihood function that will be considered.
Values smaller than this will be treated as they were minval and the corresponding individuals will
never survive. The default is -(10^(ceiling(log10(n_obs)) + d) - 1).
|
seed |
a single value, interpreted as an integer, or NULL, that sets seed for the random number generator in the beginning of
the function call. If calling GAfit from fitGSMVAR, use the argument seeds instead of passing the argument
seed.
|
By "redundant" or "wasted" regimes we mean regimes that have the time varying mixing weights practically at
zero for almost all t. A model including redundant regimes would have about the same log-likelihood value without
the redundant regimes and there is no purpose to have redundant regimes in a model.
Some of the AR coefficients are drawn with the algorithm by Ansley and Kohn (1986). However,
when using large ar_scale with large p or d, numerical inaccuracies caused
by the imprecision of the float-point presentation may result in errors or nonstationary AR-matrices.
Using smaller ar_scale facilitates the usage of larger p or d. Therefore, we bound
upper_ar_scale from above by 1-pd/150 when p*d>40 and by 1 otherwise.