Package 'uGMAR'

uGMAR: Estimate Univariate Gaussian and Student's t Mixture Autoregressive Models

Description

uGMAR is a package for estimating univariate Gaussian mixture autoregressive (GMAR), Student's t mixture autoregressive (StMAR), and Gaussian and Student's t mixture autoregressive (G-StMAR) models. In addition to unconstrained and constrained estimation, uGMAR provides tools for quantile residual based model diagnostics, forecasting, simulation, and more.

The readme file or the vignette is a good place to start.

Author(s)

Maintainer: Savi Virolainen [email protected]

See Also

Useful links:

• Report bugs at https://github.com/saviviro/uGMAR/issues

---

Add data to object of class 'gsmar' defining a GMAR, StMAR, or G-StMAR model

Description

add_data adds or updates data to object of class 'gsmar' that defines a GMAR, StMAR, or G-StMAR model. Also calculates empirical mixing weights, conditional moments, and quantile residuals accordingly.

Usage

add_data(
  data,
  gsmar,
  calc_qresiduals = TRUE,
  calc_cond_moments = TRUE,
  calc_std_errors = FALSE,
  custom_h = NULL
)

Arguments

data	a numeric vector or class 'ts' object containing the data. NA values are not supported.
gsmar	a class 'gsmar' object, typically generated by fitGSMAR or GSMAR.
calc_qresiduals	should quantile residuals be calculated? Default is TRUE iff the model contains data.
calc_cond_moments	should conditional means and variances be calculated? Default is TRUE iff the model contains data.
calc_std_errors	should approximate standard errors be calculated?
custom_h	A numeric vector with same the length as the parameter vector: i:th element of custom_h is the difference used in central difference approximation for partial differentials of the log-likelihood function for the i:th parameter. If NULL (default), then the difference used for differentiating overly large degrees of freedom parameters is adjusted to avoid numerical problems, and the difference is 6e-6 for the other parameters.

Value

Returns an object of class 'gsmar' defining the GMAR, StMAR, or G-StMAR model with the data added to the model. If the object already contained data, the data will be updated. Does not modify the 'gsmar' object given as argument!

References

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

See Also

fitGSMAR, GSMAR, iterate_more, get_gradient, get_regime_means, swap_parametrization, stmar_to_gstmar

Examples

# G-StMAR model without data
params42gs <- c(0.04, 1.34, -0.59, 0.54, -0.36, 0.01, 0.06, 1.28, -0.36,
                0.2, -0.15, 0.04, 0.19, 9.75)
gstmar42 <- GSMAR(p=4, M=c(1, 1), params=params42gs, model="G-StMAR")
gstmar42

# Add data to the model
gstmar42 <- add_data(data=M10Y1Y, gsmar=gstmar42)
gstmar42

---

Construct a GSMAR model based on results from an arbitrary estimation round of fitGSMAR

Description

alt_gsmar constructs a GSMAR model based on results from an arbitrary estimation round of fitGSMAR.

Usage

alt_gsmar(
  gsmar,
  which_round = 1,
  which_largest,
  calc_qresiduals = TRUE,
  calc_cond_moments = TRUE,
  calc_std_errors = TRUE,
  custom_h = NULL
)

Arguments

gsmar	a class 'gsmar' object, typically generated by fitGSMAR or GSMAR.
which_round	based on which estimation round should the model be constructed? An integer value in 1,...,ncalls.
which_largest	based on estimation round with which largest log-likelihood should the model be constructed? An integer value in 1,...,ncalls. For example, which_largest=2 would take the second largest log-likelihood and construct the model based on the corresponding estimates. If specified, then which_round is ignored.
calc_qresiduals	should quantile residuals be calculated? Default is TRUE iff the model contains data.
calc_cond_moments	should conditional means and variances be calculated? Default is TRUE iff the model contains data.
calc_std_errors	should approximate standard errors be calculated?
custom_h	A numeric vector with same the length as the parameter vector: i:th element of custom_h is the difference used in central difference approximation for partial differentials of the log-likelihood function for the i:th parameter. If NULL (default), then the difference used for differentiating overly large degrees of freedom parameters is adjusted to avoid numerical problems, and the difference is 6e-6 for the other parameters.

Details

It's sometimes useful to examine other estimates than the one with the highest log-likelihood value. This function is just a simple wrapper to GSMAR that picks the correct estimates from an object returned by fitGSMAR.

In addition to the S3 methods listed under the topic "Methods (by generic)", the predict and simulate methods are also available for the class 'gsmar' objects (see ?predict.gsmar and ?simulate.gsmar).

Value

Returns an object of class 'gsmar' defining the specified GMAR, StMAR, or G-StMAR model. If data is supplied, the returned object contains (by default) empirical mixing weights, some conditional and unconditional moments, and quantile residuals. Note that the first p observations are taken as the initial values so the mixing weights, conditional moments, and quantile residuals start from the p+1:th observation (interpreted as t=1).

References

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

See Also

fitGSMAR, GSMAR, iterate_more, get_gradient, get_regime_means, swap_parametrization, stmar_to_gstmar

Examples

# These are long running examples that take approximately ...
 fit42t <- fitGSMAR(data=M10Y1Y, p=4, M=2, model="StMAR", ncalls=2,
                    seeds=c(1, 6))
 fit42t # Bad estimate in the boundary of the stationarity region!

 # So we build a model based on the next-best local maximum point:
 fit42t_alt <- alt_gsmar(fit42t, which_largest=2)
 fit42t_alt # Overly large degrees of freedom paramter estimate

 # Switch to the appropriate G-StMAR model:
 fit42gs <- stmar_to_gstmar(fit42t_alt)
 fit42gs

---

Calculate gradient or Hessian matrix

Description

calc_gradient or calc_hessian calculates the gradient or Hessian matrix of the given function at the given point using central difference numerical approximation. get_gradient (and get_foc) or get_hessian calculates the gradient or Hessian matrix of the log-likelihood function at the parameter values of a class 'gsmar' object. get_soc returns eigenvalues of the Hessian matrix.

Usage

calc_gradient(x, fn, h = 6e-06, varying_h = NULL, ...)

calc_hessian(x, fn, h = 6e-06, varying_h = NULL, ...)

get_gradient(gsmar, custom_h = NULL)

get_foc(gsmar, custom_h = NULL)

get_hessian(gsmar, custom_h = NULL)

get_soc(gsmar, custom_h = NULL)

Arguments

x	a numeric vector specifying the point at which the gradient or Hessian should be evaluated.
fn	a function that takes in the argument x as the first argument.
h	the difference used to approximate the derivatives.
varying_h	a numeric vector with the same length as x specifying the difference h for each dimension separately. If NULL (default), then the difference given as parameter h will be used for all dimensions.
...	other arguments passed to fn.
gsmar	a class 'gsmar' object, typically generated by fitGSMAR or GSMAR.
custom_h	same as varying_h but if NULL (default), then the difference h used for differentiating overly large degrees of freedom parameters is adjusted to avoid numerical problems, and the difference is 6e-6 for the other parameters.

Details

In particular, the functions get_foc and get_soc can be used to check whether the found estimates denote a (local) maximum point, a saddle point, or something else.

Value

The gradient functions return numerical approximation of the gradient, and the Hessian functions return numerical approximation of the Hessian. get_soc returns eigenvalues of the Hessian matrix, get_foc is the same as get_gradient but named conveniently.

Warning

No argument checks!

See Also

profile_logliks

Examples

# Simple function
foo <- function(x) x^2 + x
calc_gradient(x=1, fn=foo)
calc_gradient(x=-0.5, fn=foo)
calc_hessian(x=2, fn=foo)

# More complicated function
foo <- function(x, a, b) a*x[1]^2 - b*x[2]^2
calc_gradient(x=c(1, 2), fn=foo, a=0.3, b=0.1)
calc_hessian(x=c(1, 2), fn=foo, a=0.3, b=0.1)

# GMAR model
params12 <- c(1.70, 0.85, 0.30, 4.12, 0.73, 1.98, 0.63)
gmar12 <- GSMAR(data=simudata, p=1, M=2, params=params12, model="GMAR")
get_gradient(gmar12)
get_foc(gmar12)
get_hessian(gmar12)
get_soc(gmar12)

---

Conditional mean or variance plot for GMAR, StMAR, and G-StMAR models

Description

cond_moment_plot plots the one-step in-sample conditional means/variances of the model along with the time series contained in the model (e.g. the time series the model was fitted to). Also plots the regimewise conditional means/variances multiplied with the mixing weights.

Usage

cond_moment_plot(gsmar, which_moment = c("mean", "variance"))

Arguments

gsmar	a class 'gsmar' object, typically generated by fitGSMAR or GSMAR.
which_moment	should conditional means or variances be plotted?

Details

The conditional mean plot works best if the data contains positive values only.

Value

cond_moment_plot only plots to a graphical device and does not return anything. Numerical values of the conditional means/variances can be extracted from the model with the dollar sign.

References

• Galbraith, R., Galbraith, J. 1974. On the inverses of some patterned matrices arising in the theory of stationary time series. Journal of Applied Probability 11, 63-71.

• Kalliovirta L. (2012) Misspecification tests based on quantile residuals. The Econometrics Journal, 15, 358-393.

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

See Also

profile_logliks, diagnostic_plot, fitGSMAR, GSMAR, quantile_residual_tests, quantile_residual_plot

Examples

# GMAR model
params12 <- c(1.70, 0.85, 0.30, 4.12, 0.73, 1.98, 0.63)
gmar12 <- GSMAR(data=simudata, p=1, M=2, params=params12, model="GMAR")
cond_moment_plot(gmar12, which_moment="mean")
cond_moment_plot(gmar12, which_moment="variance")

# G-StMAR model
params42gs <- c(0.04, 1.34, -0.59, 0.54, -0.36, 0.01, 0.06, 1.28, -0.36,
                0.2, -0.15, 0.04, 0.19, 9.75)
gstmar42 <- GSMAR(data=M10Y1Y, p=4, M=c(1, 1), params=params42gs,
                  model="G-StMAR")
cond_moment_plot(gstmar42, which_moment="mean")
cond_moment_plot(gstmar42, which_moment="variance")

---

Calculate conditional moments of GMAR, StMAR, or G-StMAR model

Description

cond_moments calculates the regime specific conditional means and variances and total conditional means and variances of the specified GMAR, StMAR or G-StMAR model.

Usage

cond_moments(
  data,
  p,
  M,
  params,
  model = c("GMAR", "StMAR", "G-StMAR"),
  restricted = FALSE,
  constraints = NULL,
  parametrization = c("intercept", "mean"),
  to_return = c("regime_cmeans", "regime_cvars", "total_cmeans", "total_cvars")
)

Arguments

data	a numeric vector or class 'ts' object containing the data. NA values are not supported.
p	a positive integer specifying the autoregressive order of the model.
M	For GMAR and StMAR models: a positive integer specifying the number of mixture components. For G-StMAR models: a size (2x1) integer vector specifying the number of GMAR type components M1 in the first element and StMAR type components M2 in the second element. The total number of mixture components is M=M1+M2.
params	a real valued parameter vector specifying the model. For non-restricted models: Size $(M(p+3)+M-M1-1x1)$ vector $\theta$$=$($\upsilon_{1}$$,...,$$\upsilon_{M}$, $\alpha_{1},...,\alpha_{M-1},$$\nu$) where $\upsilon_{m}$$=(\phi_{m,0},$$\phi_{m}$$,$$\sigma_{m}^2)$ $\phi_{m}$$=(\phi_{m,1},...,\phi_{m,p}), m=1,...,M$ $\nu$$=(\nu_{M1+1},...,\nu_{M})$ $M1$ is the number of GMAR type regimes. In the GMAR model, $M1=M$ and the parameter $\nu$ dropped. In the StMAR model, $M1=0$. If the model imposes linear constraints on the autoregressive parameters: Replace the vectors $\phi_{m}$ with the vectors $\psi_{m}$ that satisfy $\phi_{m}$$=$$C_{m}\psi_{m}$ (see the argument constraints). For restricted models: Size $(3M+M-M1+p-1x1)$ vector $\theta$$=(\phi_{1,0},...,\phi_{M,0},$$\phi$$,$ $\sigma_{1}^2,...,\sigma_{M}^2,$$\alpha_{1},...,\alpha_{M-1},$$\nu$), where $\phi$=$(\phi_{1},...,\phi_{p})$ contains the AR coefficients, which are common for all regimes. If the model imposes linear constraints on the autoregressive parameters: Replace the vector $\phi$ with the vector $\psi$ that satisfies $\phi$$=$$C\psi$ (see the argument constraints). Symbol $\phi$ denotes an AR coefficient, $\sigma^2$ a variance, $\alpha$ a mixing weight, and $\nu$ a degrees of freedom parameter. If parametrization=="mean", just replace each intercept term $\phi_{m,0}$ with the regimewise mean $\mu_m = \phi_{m,0}/(1-\sum\phi_{i,m})$. In the G-StMAR model, the first M1 components are GMAR type and the rest M2 components are StMAR type. Note that in the case M=1, the mixing weight parameters $\alpha$ are dropped, and in the case of StMAR or G-StMAR model, the degrees of freedom parameters $\nu$ have to be larger than $2$.
model	is "GMAR", "StMAR", or "G-StMAR" model considered? In the G-StMAR model, the first M1 components are GMAR type and the rest M2 components are StMAR type.
restricted	a logical argument stating whether the AR coefficients $\phi_{m,1},...,\phi_{m,p}$ are restricted to be the same for all regimes.
constraints	specifies linear constraints imposed to each regime's autoregressive parameters separately. For non-restricted models: a list of size $(pxq_{m})$ constraint matrices $C_{m}$ of full column rank satisfying $\phi_{m}$$=$$C_{m}\psi_{m}$ for all $m=1,...,M$, where $\phi_{m}$$=(\phi_{m,1},...,\phi_{m,p})$ and $\psi_{m}$$=(\psi_{m,1},...,\psi_{m,q_{m}})$. For restricted models: a size $(pxq)$ constraint matrix $C$ of full column rank satisfying $\phi$$=$$C\psi$, where $\phi$$=(\phi_{1},...,\phi_{p})$ and $\psi$$=\psi_{1},...,\psi_{q}$. The symbol $\phi$ denotes an AR coefficient. Note that regardless of any constraints, the autoregressive order is always p for all regimes. Ignore or set to NULL if applying linear constraints is not desired.
parametrization	is the model parametrized with the "intercepts" $\phi_{m,0}$ or "means" $\mu_{m} = \phi_{m,0}/(1-\sum\phi_{i,m})$?
to_return	calculate regimewise conditional means (regime_cmeans), regimewise conditional variances (regime_cvars), total conditional means (total_cmeans), or total conditional variances (total_cvars)?

Value

Note that the first p observations are taken as the initial values so the conditional moments start form the p+1:th observation (interpreted as t=1).

if to_return=="regime_cmeans":

a size ((n_obs-p)xM) matrix containing the regime specific conditional means.

if to_return=="regime_cvars":

a size ((n_obs-p)xM) matrix containing the regime specific conditional variances.

if to_return=="total_cmeans":

a size ((n_obs-p)x1) vector containing the total conditional means.

if to_return=="total_cvars":

a size ((n_obs-p)x1) vector containing the total conditional variances.

References

• Galbraith, R., Galbraith, J. 1974. On the inverses of some patterned matrices arising in the theory of stationary time series. Journal of Applied Probability 11, 63-71.

• Kalliovirta L. (2012) Misspecification tests based on quantile residuals. The Econometrics Journal, 15, 358-393.

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

See Also

Other moment functions: get_regime_autocovs(), get_regime_means(), get_regime_vars(), uncond_moments()

Examples

# GMAR model, regimewise conditional means and variances
params12 <- c(1.70, 0.85, 0.30, 4.12, 0.73, 1.98, 0.63)
cond_moments(simudata, p=1, M=2, params=params12, model="GMAR",
             to_return="regime_cmeans")
cond_moments(simudata, p=1, M=2, params=params12, model="GMAR",
             to_return="regime_cvars")

# G-StMAR-model, total conditional means and variances
params42gs <- c(0.04, 1.34, -0.59, 0.54, -0.36, 0.01, 0.06, 1.28, -0.36,
                0.2, -0.15, 0.04, 0.19, 9.75)
cond_moments(M10Y1Y, p=4, M=c(1, 1), params=params42gs, model="G-StMAR",
             to_return="total_cmeans")
cond_moments(M10Y1Y, p=4, M=c(1, 1), params=params42gs, model="G-StMAR",
             to_return="total_cvars")

---

DEPRECATED, USE cond_moment_plot INSTEAD! Conditional mean or variance plot for GMAR, StMAR, and G-StMAR models

Description

condmomentPlot plots the one-step in-sample conditional means/variances of the model along with the time series contained in the model (e.g. the time series the model was fitted to). Also plots the regimewise conditional means/variances multiplied with the mixing weights. DEPRECATED, USE cond_moment_plot INSTEAD!

Usage

condmomentPlot(gsmar, which_moment = c("mean", "variance"))

Arguments

gsmar	a class 'gsmar' object, typically generated by fitGSMAR or GSMAR.
which_moment	should conditional means or variances be plotted?

Details

DEPRECATED, USE cond_moment_plot INSTEAD!

Value

cond_moment_plot only plots to a graphical device and does not return anything. Numerical values of the conditional means/variances can be extracted from the model with the dollar sign.

References

• Galbraith, R., Galbraith, J. 1974. On the inverses of some patterned matrices arising in the theory of stationary time series. Journal of Applied Probability 11, 63-71.

• Kalliovirta L. (2012) Misspecification tests based on quantile residuals. The Econometrics Journal, 15, 358-393.

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

See Also

profile_logliks, diagnostic_plot, fitGSMAR, GSMAR, quantile_residual_tests, quantileResidualPlot

---

DEPRECATED, USE cond_moments INSTEAD! Calculate conditional moments of GMAR, StMAR, or G-StMAR model

Description

condMoments calculates the regime specific conditional means and variances and total conditional means and variances of the specified GMAR, StMAR or G-StMAR model. DEPRECATED, USE cond_moments INSTEAD!

Usage

condMoments(
  data,
  p,
  M,
  params,
  model = c("GMAR", "StMAR", "G-StMAR"),
  restricted = FALSE,
  constraints = NULL,
  parametrization = c("intercept", "mean"),
  to_return = c("regime_cmeans", "regime_cvars", "total_cmeans", "total_cvars")
)

Arguments

data	a numeric vector or class 'ts' object containing the data. NA values are not supported.
p	a positive integer specifying the autoregressive order of the model.
M	For GMAR and StMAR models: a positive integer specifying the number of mixture components. For G-StMAR models: a size (2x1) integer vector specifying the number of GMAR type components M1 in the first element and StMAR type components M2 in the second element. The total number of mixture components is M=M1+M2.
params	a real valued parameter vector specifying the model. For non-restricted models: Size $(M(p+3)+M-M1-1x1)$ vector $\theta$$=$($\upsilon_{1}$$,...,$$\upsilon_{M}$, $\alpha_{1},...,\alpha_{M-1},$$\nu$) where $\upsilon_{m}$$=(\phi_{m,0},$$\phi_{m}$$,$$\sigma_{m}^2)$ $\phi_{m}$$=(\phi_{m,1},...,\phi_{m,p}), m=1,...,M$ $\nu$$=(\nu_{M1+1},...,\nu_{M})$ $M1$ is the number of GMAR type regimes. In the GMAR model, $M1=M$ and the parameter $\nu$ dropped. In the StMAR model, $M1=0$. If the model imposes linear constraints on the autoregressive parameters: Replace the vectors $\phi_{m}$ with the vectors $\psi_{m}$ that satisfy $\phi_{m}$$=$$C_{m}\psi_{m}$ (see the argument constraints). For restricted models: Size $(3M+M-M1+p-1x1)$ vector $\theta$$=(\phi_{1,0},...,\phi_{M,0},$$\phi$$,$ $\sigma_{1}^2,...,\sigma_{M}^2,$$\alpha_{1},...,\alpha_{M-1},$$\nu$), where $\phi$=$(\phi_{1},...,\phi_{p})$ contains the AR coefficients, which are common for all regimes. If the model imposes linear constraints on the autoregressive parameters: Replace the vector $\phi$ with the vector $\psi$ that satisfies $\phi$$=$$C\psi$ (see the argument constraints). Symbol $\phi$ denotes an AR coefficient, $\sigma^2$ a variance, $\alpha$ a mixing weight, and $\nu$ a degrees of freedom parameter. If parametrization=="mean", just replace each intercept term $\phi_{m,0}$ with the regimewise mean $\mu_m = \phi_{m,0}/(1-\sum\phi_{i,m})$. In the G-StMAR model, the first M1 components are GMAR type and the rest M2 components are StMAR type. Note that in the case M=1, the mixing weight parameters $\alpha$ are dropped, and in the case of StMAR or G-StMAR model, the degrees of freedom parameters $\nu$ have to be larger than $2$.
model	is "GMAR", "StMAR", or "G-StMAR" model considered? In the G-StMAR model, the first M1 components are GMAR type and the rest M2 components are StMAR type.
restricted	a logical argument stating whether the AR coefficients $\phi_{m,1},...,\phi_{m,p}$ are restricted to be the same for all regimes.
constraints	specifies linear constraints imposed to each regime's autoregressive parameters separately. For non-restricted models: a list of size $(pxq_{m})$ constraint matrices $C_{m}$ of full column rank satisfying $\phi_{m}$$=$$C_{m}\psi_{m}$ for all $m=1,...,M$, where $\phi_{m}$$=(\phi_{m,1},...,\phi_{m,p})$ and $\psi_{m}$$=(\psi_{m,1},...,\psi_{m,q_{m}})$. For restricted models: a size $(pxq)$ constraint matrix $C$ of full column rank satisfying $\phi$$=$$C\psi$, where $\phi$$=(\phi_{1},...,\phi_{p})$ and $\psi$$=\psi_{1},...,\psi_{q}$. The symbol $\phi$ denotes an AR coefficient. Note that regardless of any constraints, the autoregressive order is always p for all regimes. Ignore or set to NULL if applying linear constraints is not desired.
parametrization	is the model parametrized with the "intercepts" $\phi_{m,0}$ or "means" $\mu_{m} = \phi_{m,0}/(1-\sum\phi_{i,m})$?
to_return	calculate regimewise conditional means (regime_cmeans), regimewise conditional variances (regime_cvars), total conditional means (total_cmeans), or total conditional variances (total_cvars)?

Value

Note that the first p observations are taken as the initial values so the conditional moments start form the p+1:th observation (interpreted as t=1).

if to_return=="regime_cmeans":

a size ((n_obs-p)xM) matrix containing the regime specific conditional means.

if to_return=="regime_cvars":

a size ((n_obs-p)xM) matrix containing the regime specific conditional variances.

if to_return=="total_cmeans":

a size ((n_obs-p)x1) vector containing the total conditional means.

if to_return=="total_cvars":

a size ((n_obs-p)x1) vector containing the total conditional variances.

References

• Galbraith, R., Galbraith, J. 1974. On the inverses of some patterned matrices arising in the theory of stationary time series. Journal of Applied Probability 11, 63-71.

• Kalliovirta L. (2012) Misspecification tests based on quantile residuals. The Econometrics Journal, 15, 358-393.

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

---

Quantile residual based diagnostic plots for GMAR, StMAR, and G-StMAR models

Description

diagnostic_plot plots quantile residual time series, normal QQ-plot, autocorrelation function, and squared quantile residual autocorrelation function. There is an option to also plot the individual statistics associated with the quantile residual tests (for autocorrelation and conditional heteroskedasticity) divided by their approximate standard errors with their approximate 95% critical bounds (see Kalliovirta 2012, Section 3).

Usage

diagnostic_plot(gsmar, nlags = 20, nsimu = 1, plot_indstats = FALSE)

Arguments

gsmar	a class 'gsmar' object, typically generated by fitGSMAR or GSMAR.
nlags	a positive integer specifying how many lags should be calculated for the autocorrelation and conditional heteroscedasticity statistics.
nsimu	a positive integer specifying to how many simulated values from the process the covariance matrix "Omega" (used to compute the tests) should be based on. Larger number of simulations may result more reliable tests but takes longer to compute. If smaller than data size, then "Omega" will be based on the given data. Ignored if plot_indstats==FALSE.
plot_indstats	set TRUE if the individual statistics discussed in Kalliovirta (2012) should be plotted with their approximate 95% critical bounds (this may take some time).

Details

Sometimes the individual statistics are not plotted because it was not (numerically) possible to calculate all the required statistics. This may suggest that the model is misspecified.

The dashed lines plotted with autocorrelation functions (for quantile residuals and their squares) are plus-minus $1.96*T^{-1/2}$ where $T$ is the sample size (minus the $p$ initial values for conditional models).

Value

diagnostic_plot only plots to a graphical device and does not return anything. Use the function quantile_residual_tests in order to obtain the individual statistics.

Suggested packages

Install the suggested package "gsl" for faster evaluations in the cases of StMAR and G-StMAR models. For large StMAR and G-StMAR models with large data the calculations to obtain the individual statistics may take a significantly long time without the package "gsl".

References

• Galbraith, R., Galbraith, J. 1974. On the inverses of some patterned matrices arising in the theory of stationary time series. Journal of Applied Probability 11, 63-71.

• Kalliovirta L. (2012) Misspecification tests based on quantile residuals. The Econometrics Journal, 15, 358-393.

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

See Also

profile_logliks, get_foc, fitGSMAR, cond_moment_plot, quantile_residual_tests, quantile_residual_plot, simulate.gsmar, LR_test, Wald_test

Examples

## The below examples the approximately 30 seconds to run.

# G-StMAR model with one GMAR type and one StMAR type regime
fit42gs <- fitGSMAR(M10Y1Y, p=4, M=c(1, 1), model="G-StMAR",
                    ncalls=1, seeds=4)
diagnostic_plot(fit42gs)

# Restricted StMAR model: plot also the individual statistics with
# their approximate critical bounds using the given data (and not
# simulation procedure)
fit42tr <- fitGSMAR(M10Y1Y, p=4, M=2, model="StMAR", restricted=TRUE,
                    ncalls=1, seeds=1)
diagnostic_plot(fit42tr, nlags=10, nsimu=1, plot_indstats=TRUE)

# GMAR model, plot 30 lags.
fit12 <- fitGSMAR(data=simudata, p=1, M=2, model="GMAR", ncalls=1, seeds=1)
diagnostic_plot(fit12, nlags=30)

---

DEPRECATED, USE diagnostic_plot INSTEAD! Quantile residual based diagnostic plots for GMAR, StMAR, and G-StMAR models

Description

diagnosticPlot plots quantile residual time series, normal QQ-plot, autocorrelation function, and squared quantile residual autocorrelation function. There is an option to also plot the individual statistics associated with the quantile residual tests (for autocorrelation and conditional heteroskedasticity) divided by their approximate standard errors with their approximate 95% critical bounds (see Kalliovirta 2012, Section 3). DEPRECATED, USE diagnostic_plot INSTEAD!

Usage

diagnosticPlot(gsmar, nlags = 20, nsimu = 1, plot_indstats = FALSE)

Arguments

gsmar	a class 'gsmar' object, typically generated by fitGSMAR or GSMAR.
nlags	a positive integer specifying how many lags should be calculated for the autocorrelation and conditional heteroscedasticity statistics.
nsimu	a positive integer specifying to how many simulated values from the process the covariance matrix "Omega" (used to compute the tests) should be based on. Larger number of simulations may result more reliable tests but takes longer to compute. If smaller than data size, then "Omega" will be based on the given data. Ignored if plot_indstats==FALSE.
plot_indstats	set TRUE if the individual statistics discussed in Kalliovirta (2012) should be plotted with their approximate 95% critical bounds (this may take some time).

Details

DEPRECATED, USE diagnostic_plot INSTEAD!

Sometimes the individual statistics are not plotted because it was not (numerically) possible to calculate all the required statistics. This may suggest that the model is misspecified.

The dashed lines plotted with autocorrelation functions (for quantile residuals and their squares) are plus-minus $1.96*T^{-1/2}$ where $T$ is the sample size (minus the $p$ initial values for conditional models).

Value

diagnostic_plot only plots to a graphical device and does not return anything. Use the function quantile_residual_tests in order to obtain the individual statistics.

Suggested packages

Install the suggested package "gsl" for faster evaluations in the cases of StMAR and G-StMAR models. For large StMAR and G-StMAR models with large data the calculations to obtain the individual statistics may take a significantly long time without the package "gsl".

References

• Galbraith, R., Galbraith, J. 1974. On the inverses of some patterned matrices arising in the theory of stationary time series. Journal of Applied Probability 11, 63-71.

• Kalliovirta L. (2012) Misspecification tests based on quantile residuals. The Econometrics Journal, 15, 358-393.

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

See Also

profile_logliks, get_foc, fitGSMAR, cond_moment_plot, quantile_residual_tests, quantile_residual_plot, simulate.gsmar, LR_test, Wald_test

---

Estimate Gaussian or Student's t Mixture Autoregressive model

Description

fitGSMAR estimates GMAR, StMAR, or G-StMAR model in two phases. In the first phase, a genetic algorithm is employed to find starting values for a gradient based method. In the second phase, the gradient based variable metric algorithm is utilized to accurately converge to a local maximum or a saddle point near each starting value. Parallel computing is used to conduct multiple rounds of estimations in parallel.

Usage

fitGSMAR(
  data,
  p,
  M,
  model = c("GMAR", "StMAR", "G-StMAR"),
  restricted = FALSE,
  constraints = NULL,
  conditional = TRUE,
  parametrization = c("intercept", "mean"),
  ncalls = round(10 + 9 * log(sum(M))),
  ncores = 2,
  maxit = 500,
  seeds = NULL,
  print_res = TRUE,
  filter_estimates = TRUE,
  ...
)

Arguments

data	a numeric vector or class 'ts' object containing the data. NA values are not supported.
p	a positive integer specifying the autoregressive order of the model.
M	For GMAR and StMAR models: a positive integer specifying the number of mixture components. For G-StMAR models: a size (2x1) integer vector specifying the number of GMAR type components M1 in the first element and StMAR type components M2 in the second element. The total number of mixture components is M=M1+M2.
model	is "GMAR", "StMAR", or "G-StMAR" model considered? In the G-StMAR model, the first M1 components are GMAR type and the rest M2 components are StMAR type.
restricted	a logical argument stating whether the AR coefficients $\phi_{m,1},...,\phi_{m,p}$ are restricted to be the same for all regimes.
constraints	specifies linear constraints imposed to each regime's autoregressive parameters separately. For non-restricted models: a list of size $(pxq_{m})$ constraint matrices $C_{m}$ of full column rank satisfying $\phi_{m}$$=$$C_{m}\psi_{m}$ for all $m=1,...,M$, where $\phi_{m}$$=(\phi_{m,1},...,\phi_{m,p})$ and $\psi_{m}$$=(\psi_{m,1},...,\psi_{m,q_{m}})$. For restricted models: a size $(pxq)$ constraint matrix $C$ of full column rank satisfying $\phi$$=$$C\psi$, where $\phi$$=(\phi_{1},...,\phi_{p})$ and $\psi$$=\psi_{1},...,\psi_{q}$. The symbol $\phi$ denotes an AR coefficient. Note that regardless of any constraints, the autoregressive order is always p for all regimes. Ignore or set to NULL if applying linear constraints is not desired.
conditional	a logical argument specifying whether the conditional or exact log-likelihood function should be used.
parametrization	is the model parametrized with the "intercepts" $\phi_{m,0}$ or "means" $\mu_{m} = \phi_{m,0}/(1-\sum\phi_{i,m})$?
ncalls	a positive integer specifying how many rounds of estimation should be conducted. The estimation results may vary from round to round because of multimodality of the log-likelihood function and the randomness associated with the genetic algorithm.
ncores	the number of CPU cores to be used in the estimation process.
maxit	the maximum number of iterations for the variable metric algorithm.
seeds	a length ncalls vector containing the random number generator seed for each call to the genetic algorithm, or NULL for not initializing the seed. Exists for the purpose of creating reproducible results.
print_res	should the estimation results be printed?
filter_estimates	should likely inappropriate estimates be filtered? See details.
...	additional settings passed to the function GAfit employing the genetic algorithm.

Details

Because of complexity and multimodality of the log-likelihood function, it's not guaranteed that the estimation algorithm will end up in the global maximum point. It's often expected that most of the estimation rounds will end up in some local maximum point instead, and therefore a number of estimation rounds is required for reliable results. Because of the nature of the models, the estimation may fail particularly in the cases where the number of mixture components is chosen too large. Note that the genetic algorithm is designed to avoid solutions with mixing weights of some regimes too close to zero at almost all times ("redundant regimes") but the settings can, however, be adjusted (see ?GAfit).

If the iteration limit for the variable metric algorithm (maxit) is reached, one can continue the estimation by iterating more with the function iterate_more.

The core of the genetic algorithm is mostly based on the description by Dorsey and Mayer (1995). It utilizes a slightly modified version the individually adaptive crossover and mutation rates described by Patnaik and Srinivas (1994) and employs (50%) fitness inheritance discussed by Smith, Dike and Stegmann (1995). Large (in absolute value) but stationary AR parameter values are generated with the algorithm proposed by Monahan (1984).

The variable metric algorithm (or quasi-Newton method, Nash (1990, algorithm 21)) used in the second phase is implemented with function the optim from the package stats.

Additional Notes about the estimates:

Sometimes the found MLE is very close to the boundary of the stationarity region some regime, the related variance parameter is very small, and the associated mixing weights are "spiky". This kind of estimates often maximize the log-likelihood function for a technical reason that induces by the endogenously determined mixing weights. In such cases, it might be more appropriate to consider the next-best local maximum point of the log-likelihood function that is well inside the parameter space. Models based local-only maximum points can be built with the function alt_gsmar by adjusting the argument which_largest accordingly.

Some mixture components of the StMAR model may sometimes get very large estimates for the degrees of freedom parameters. Such parameters are weakly identified and induce various numerical problems. However, mixture components with large degree of freedom parameter estimates are similar to the mixture components of the GMAR model. It's hence advisable to further estimate a G-StMAR model by allowing the mixture components with large degrees of freedom parameter estimates to be GMAR type with the function stmar_to_gstmar.

Filtering inappropriate estimates: If filter_estimates == TRUE, the function will automatically filter out estimates that it deems "inappropriate". That is, estimates that are not likely solutions of interest. Specifically, it filters out solutions that incorporate regimes with any modulus of the roots of the AR polynomial less than $1.0015$; a variance parameter estimat near zero (less than $0.0015$); mixing weights such that they are close to zero for almost all $t$ for at least one regime; or mixing weight parameter estimate close to zero (or one). You can also set filter_estimates=FALSE and find the solutions of interest yourself by using the function alt_gsmar.

Value

Returns an object of class 'gsmar' defining the estimated GMAR, StMAR or G-StMAR model. The returned object contains estimated mixing weights, some conditional and unconditional moments, and quantile residuals. Note that the first p observations are taken as the initial values, so the mixing weights, conditional moments, and quantile residuals start from the p+1:th observation (interpreted as t=1). In addition, the returned object contains the estimates and log-likelihoods from all of the estimation rounds. See ?GSMAR for the form of the parameter vector, if needed.

S3 methods

The following S3 methods are supported for class 'gsmar' objects: print, summary, plot, predict, simulate, logLik, residuals.

References

• Dorsey R. E. and Mayer W. J. 1995. Genetic algorithms for estimation problems with multiple optima, nondifferentiability, and other irregular features. Journal of Business & Economic Statistics, 13, 53-66.

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Monahan J.F. 1984. A Note on Enforcing Stationarity in Autoregressive-Moving Average Models. Biometrica 71, 403-404.

• Nash J. 1990. Compact Numerical Methods for Computers. Linear algebra and Function Minimization. Adam Hilger.

• Patnaik L.M. and Srinivas M. 1994. Adaptive Probabilities of Crossover and Mutation in Genetic Algorithms. Transactions on Systems, Man and Cybernetics 24, 656-667.

• Smith R.E., Dike B.A., Stegmann S.A. 1995. Fitness inheritance in genetic algorithms. Proceedings of the 1995 ACM Symposium on Applied Computing, 345-350.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

See Also

GSMAR, iterate_more, , stmar_to_gstmar, add_data, profile_logliks, swap_parametrization, get_gradient, simulate.gsmar, predict.gsmar, diagnostic_plot, quantile_residual_tests, cond_moments, uncond_moments, LR_test, Wald_test

Examples

## These are long running examples that use parallel computing.
## The below examples take approximately 90 seconds to run.

## Note that the number of estimation rounds (ncalls) is relatively small
## in the below examples to reduce the time required for running the examples.
## For reliable results, a large number of estimation rounds is recommended!

# GMAR model
fit12 <- fitGSMAR(data=simudata, p=1, M=2, model="GMAR", ncalls=4, seeds=1:4)
summary(fit12)
plot(fit12)
profile_logliks(fit12)
diagnostic_plot(fit12)

# StMAR model (large estimate of the degrees of freedom)
fit42t <- fitGSMAR(data=M10Y1Y, p=4, M=2, model="StMAR", ncalls=2, seeds=c(1, 6))
summary(fit42t) # Overly large 2nd regime degrees of freedom estimate!
fit42gs <- stmar_to_gstmar(fit42t) # Switch to G-StMAR model
summary(fit42gs) # An appropriate G-StMVAR model with one G and one t regime
plot(fit42gs)

# Restricted StMAR model
fit42r <- fitGSMAR(M10Y1Y, p=4, M=2, model="StMAR", restricted=TRUE,
                   ncalls=2, seeds=1:2)
fit42r

# G-StMAR model with one GMAR type and one StMAR type regime
fit42gs <- fitGSMAR(M10Y1Y, p=4, M=c(1, 1), model="G-StMAR",
                    ncalls=1, seeds=4)
fit42gs

# The following three examples demonstrate how to apply linear constraints
# to the autoregressive (AR) parameters.

# Two-regime GMAR p=2 model with the second AR coeffiecient of
# of the second regime contrained to zero.
C22 <- list(diag(1, ncol=2, nrow=2), as.matrix(c(1, 0)))
fit22c <- fitGSMAR(M10Y1Y, p=2, M=2, constraints=C22, ncalls=1, seeds=6)
fit22c

# StMAR(3, 1) model with the second order AR coefficient constrained to zero.
C31 <- list(matrix(c(1, 0, 0, 0, 0, 1), ncol=2))
fit31tc <- fitGSMAR(M10Y1Y, p=3, M=1, model="StMAR", constraints=C31,
                    ncalls=1, seeds=1)
fit31tc

# Such StMAR(3, 2) model that the AR coefficients are restricted to be
# the same for both regimes and the second AR coefficients are
# constrained to zero.
fit32rc <- fitGSMAR(M10Y1Y, p=3, M=2, model="StMAR", restricted=TRUE,
                    constraints=matrix(c(1, 0, 0, 0, 0, 1), ncol=2),
                    ncalls=1, seeds=1)
fit32rc

---

Genetic algorithm for preliminary estimation of GMAR, StMAR, or G-StMAR model

Description

GAfit estimates specified GMAR, StMAR, or G-StMAR model using a genetic algorithm. The employed genetic algorithm is designed to find starting values for gradient based methods.

Usage

GAfit(
  data,
  p,
  M,
  model = c("GMAR", "StMAR", "G-StMAR"),
  restricted = FALSE,
  constraints = NULL,
  parametrization = c("intercept", "mean"),
  conditional = TRUE,
  ngen = 200,
  popsize,
  smart_mu = min(100, ceiling(0.5 * ngen)),
  mu_scale,
  sigma_scale,
  initpop = NULL,
  regime_force_scale = 1,
  red_criteria = c(0.05, 0.01),
  to_return = c("alt_ind", "best_ind"),
  minval,
  seed = NULL,
  ...
)

Arguments

data	a numeric vector or class 'ts' object containing the data. NA values are not supported.
p	a positive integer specifying the autoregressive order of the model.
M	For GMAR and StMAR models: a positive integer specifying the number of mixture components. For G-StMAR models: a size (2x1) integer vector specifying the number of GMAR type components M1 in the first element and StMAR type components M2 in the second element. The total number of mixture components is M=M1+M2.
model	is "GMAR", "StMAR", or "G-StMAR" model considered? In the G-StMAR model, the first M1 components are GMAR type and the rest M2 components are StMAR type.
restricted	a logical argument stating whether the AR coefficients $\phi_{m,1},...,\phi_{m,p}$ are restricted to be the same for all regimes.
constraints	specifies linear constraints imposed to each regime's autoregressive parameters separately. For non-restricted models: a list of size $(pxq_{m})$ constraint matrices $C_{m}$ of full column rank satisfying $\phi_{m}$$=$$C_{m}\psi_{m}$ for all $m=1,...,M$, where $\phi_{m}$$=(\phi_{m,1},...,\phi_{m,p})$ and $\psi_{m}$$=(\psi_{m,1},...,\psi_{m,q_{m}})$. For restricted models: a size $(pxq)$ constraint matrix $C$ of full column rank satisfying $\phi$$=$$C\psi$, where $\phi$$=(\phi_{1},...,\phi_{p})$ and $\psi$$=\psi_{1},...,\psi_{q}$. The symbol $\phi$ denotes an AR coefficient. Note that regardless of any constraints, the autoregressive order is always p for all regimes. Ignore or set to NULL if applying linear constraints is not desired.
parametrization	is the model parametrized with the "intercepts" $\phi_{m,0}$ or "means" $\mu_{m} = \phi_{m,0}/(1-\sum\phi_{i,m})$?
conditional	a logical argument specifying whether the conditional or exact log-likelihood function should be used.
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*d where d is the number of parameters.
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 so far.
mu_scale	a real valued vector of length two specifying the mean (the first element) and standard deviation (the second element) of the normal distribution from which the $\mu_{m}$ mean-parameters are generated in random mutations in the genetic algorithm. Default is c(mean(data), sd(data)). Note that the genetic algorithm optimizes with mean-parametrization even when parametrization=="intercept", but input (in initpop) and output (return value) parameter vectors may be intercept-parametrized.
sigma_scale	a positive real number specifying the standard deviation of the (zero mean, positive only by taking absolute value) normal distribution from which the component variance parameters are generated in the random mutations in the genetic algorithm. Default is var(stats::ar(data, order.max=10)$resid, na.rm=TRUE).
initpop	a list of parameter vectors from which the initial population of the genetic algorithm will be generated from. The parameter vectors should be of form... For non-restricted models: Size $(M(p+3)+M-M1-1x1)$ vector $\theta$$=$($\upsilon_{1}$$,...,$$\upsilon_{M}$, $\alpha_{1},...,\alpha_{M-1},$$\nu$) where $\upsilon_{m}$$=(\phi_{m,0},$$\phi_{m}$$,$$\sigma_{m}^2)$ $\phi_{m}$$=(\phi_{m,1},...,\phi_{m,p}), m=1,...,M$ $\nu$$=(\nu_{M1+1},...,\nu_{M})$ $M1$ is the number of GMAR type regimes. In the GMAR model, $M1=M$ and the parameter $\nu$ dropped. In the StMAR model, $M1=0$. If the model imposes linear constraints on the autoregressive parameters: Replace the vectors $\phi_{m}$ with the vectors $\psi_{m}$ that satisfy $\phi_{m}$$=$$C_{m}\psi_{m}$ (see the argument constraints). For restricted models: Size $(3M+M-M1+p-1x1)$ vector $\theta$$=(\phi_{1,0},...,\phi_{M,0},$$\phi$$,$ $\sigma_{1}^2,...,\sigma_{M}^2,$$\alpha_{1},...,\alpha_{M-1},$$\nu$), where $\phi$=$(\phi_{1},...,\phi_{p})$ contains the AR coefficients, which are common for all regimes. If the model imposes linear constraints on the autoregressive parameters: Replace the vector $\phi$ with the vector $\psi$ that satisfies $\phi$$=$$C\psi$ (see the argument constraints). Symbol $\phi$ denotes an AR coefficient, $\sigma^2$ a variance, $\alpha$ a mixing weight, and $\nu$ a degrees of freedom parameter. If parametrization=="mean", just replace each intercept term $\phi_{m,0}$ with the regimewise mean $\mu_m = \phi_{m,0}/(1-\sum\phi_{i,m})$. In the G-StMAR model, the first M1 components are GMAR type and the rest M2 components are StMAR type. Note that in the case M=1, the mixing weight parameters $\alpha$ are dropped, and in the case of StMAR or G-StMAR model, the degrees of freedom parameters $\nu$ have to be larger than $2$. If not specified (or NULL as is default), the initial population will be drawn randomly.
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 (see red_criteria), i.e., with less "redundant regimes". 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 favoring 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 probabilities etc.
red_criteria	a length 2 numeric vector specifying the criteria that is used to determine whether a regime is redundant or not. Any regime m which satisfies sum(mixing_weights[,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).
to_return	should the genetic algorithm return the best fitting individual which has the least "redundant" regimes ("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(length(data))) + 1) - 1), and one should be very careful if adjusting this.
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 fitGSMAR, use the argument seeds instead of passing the argument seed.
...	We currently use this to catch deprecated arguments.

Details

The core of the genetic algorithm is mostly based on the description by Dorsey and Mayer (1995). It utilizes a slightly modified version of the individually adaptive crossover and mutation rates described by Patnaik and Srinivas (1994) and employs (50%) fitness inheritance discussed by Smith, Dike and Stegmann (1995). Large (in absolute value) but stationary AR parameter values are generated with the algorithm proposed by Monahan (1984).

By "redundant" or "wasted" regimes we mean regimes that have the time varying mixing weights basically at zero for all t. The model with redundant regimes would have approximately the same log-likelihood value without the redundant regimes and there is no purpose to have redundant regimes in the model.

Value

Returns estimated parameter vector with the form described in initpop.

References

• Dorsey R. E. and Mayer W. J. 1995. Genetic algorithms for estimation problems with multiple optima, nondifferentiability, and other irregular features. Journal of Business & Economic Statistics, 13, 53-66.

  • Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

  • Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

  • Monahan J.F. 1984. A Note on Enforcing Stationarity in Autoregressive-Moving Average Models. Biometrica 71, 403-404.

  • Patnaik L.M. and Srinivas M. 1994. Adaptive Probabilities of Crossover and Mutation in Genetic Algorithms. Transactions on Systems, Man and Cybernetics 24, 656-667.

  • Smith R.E., Dike B.A., Stegmann S.A. 1995. Fitness inheritance in genetic algorithms. Proceedings of the 1995 ACM Symposium on Applied Computing, 345-350.

  • Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

Examples

## These are long running examples

# Preliminary estimation of GMAR p=1, M=2, model with the genetic algorithm
# using only 100 generations (200 is recommended):
pars12_ga <- GAfit(data=simudata, p=1, M=2, model="GMAR", ngen=100, seed=1)
pars12_ga # Returns a parameter vector, not a class 'gsmar' object.

---

Calculate absolute values of the roots of the AR characteristic polynomials

Description

get_ar_roots calculates the absolute values of the roots of the AR characteristic polynomials for each mixture component.

Usage

get_ar_roots(gsmar)

Arguments

gsmar

a class 'gsmar' object, typically generated by fitGSMAR or GSMAR.

Value

Returns a list with M elements each containing the absolute values of the roots of the AR characteristic polynomial corresponding to each mixture component.

References

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

Examples

params12 <- c(1.70, 0.85, 0.30, 4.12, 0.73, 1.98, 0.63)
gmar12 <- GSMAR(data=simudata, p=1, M=2, params=params12, model="GMAR")
get_ar_roots(gmar12)

---

Calculate regime specific autocovariances $\gamma$$_{m,p}$

Description

get_regime_autocovs calculates the first p regime specific autocovariances $\gamma$$_{m,p}$ for the given GMAR, StMAR, or G-StMAR model.

Usage

get_regime_autocovs(gsmar)

Arguments

gsmar

a class 'gsmar' object, typically generated by fitGSMAR or GSMAR.

Value

Returns a size $(pxM)$ matrix containing the first p autocovariances of the components processes: i:th autocovariance in the i:th row and m:th component process in the m:th column.

References

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

• Lütkepohl H. 2005. New Introduction to Multiple Time Series Analysis. Springer.

See Also

Other moment functions: cond_moments(), get_regime_means(), get_regime_vars(), uncond_moments()

Examples

# GMAR model
params13 <- c(1.4, 0.88, 0.26, 2.46, 0.82, 0.74, 5.0, 0.68, 5.2, 0.72, 0.2)
gmar13 <- GSMAR(p=1, M=3, params=params13, model="GMAR")
get_regime_autocovs(gmar13)

# StMAR model
params12t <- c(1.38, 0.88, 0.27, 3.8, 0.74, 3.15, 0.8, 100, 3.6)
stmar12t <- GSMAR(p=1, M=2, params=params12t, model="StMAR")
get_regime_autocovs(stmar12t)

# G-StMAR model (similar to the StMAR model above)
params12gs <- c(1.38, 0.88, 0.27, 3.8, 0.74, 3.15, 0.8, 3.6)
gstmar12 <- GSMAR(p=1, M=c(1, 1), params=params12gs, model="G-StMAR")
get_regime_autocovs(gstmar12)

---

Calculate regime specific means $\mu_{m}$

Description

get_regime_means calculates the regime means $\mu_{m} = \phi_{m,0}/(1-\sum\phi_{i,m})$ for the given GMAR, StMAR, or G-StMAR model

Usage

get_regime_means(gsmar)

Arguments

gsmar

a class 'gsmar' object, typically generated by fitGSMAR or GSMAR.

Value

Returns a length M vector containing the regime mean $\mu_{m}$ in the m:th element.

References

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

See Also

cond_moments, uncond_moments, get_regime_vars, get_regime_autocovs

Other moment functions: cond_moments(), get_regime_autocovs(), get_regime_vars(), uncond_moments()

Examples

# GMAR model
params13 <- c(1.4, 0.88, 0.26, 2.46, 0.82, 0.74, 5.0, 0.68, 5.2, 0.72, 0.2)
gmar13 <- GSMAR(p=1, M=3, params=params13, model="GMAR")
get_regime_means(gmar13)

# StMAR model
params12t <- c(1.38, 0.88, 0.27, 3.8, 0.74, 3.15, 0.8, 100, 3.6)
stmar12t <- GSMAR(p=1, M=2, params=params12t, model="StMAR")
get_regime_means(stmar12t)

# G-StMAR model (similar to the StMAR model above)
params12gs <- c(1.38, 0.88, 0.27, 3.8, 0.74, 3.15, 0.8, 3.6)
gstmar12 <- GSMAR(p=1, M=c(1, 1), params=params12gs, model="G-StMAR")
get_regime_means(gstmar12)

---

Calculate regime specific variances $\gamma_{m,0}$

Description

get_regime_vars calculates the unconditional regime specific variances $\gamma_{m,0}$ for the given GMAR, StMAR, or G-StMAR model.

Usage

get_regime_vars(gsmar)

Arguments

gsmar

a class 'gsmar' object, typically generated by fitGSMAR or GSMAR.

Value

Returns a length M vector containing the unconditional variances of the components processes: m:th element for the m:th regime.

References

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

• Lütkepohl H. 2005. New Introduction to Multiple Time Series Analysis. Springer.

See Also

Other moment functions: cond_moments(), get_regime_autocovs(), get_regime_means(), uncond_moments()

Examples

# GMAR model
params13 <- c(1.4, 0.88, 0.26, 2.46, 0.82, 0.74, 5.0, 0.68, 5.2, 0.72, 0.2)
gmar13 <- GSMAR(p=1, M=3, params=params13, model="GMAR")
get_regime_vars(gmar13)

# StMAR model
params12t <- c(1.38, 0.88, 0.27, 3.8, 0.74, 3.15, 0.8, 100, 3.6)
stmar12t <- GSMAR(p=1, M=2, params=params12t, model="StMAR")
get_regime_vars(stmar12t)

# G-StMAR model (similar to the StMAR model above)
params12gs <- c(1.38, 0.88, 0.27, 3.8, 0.74, 3.15, 0.8, 3.6)
gstmar12 <- GSMAR(p=1, M=c(1, 1), params=params12gs, model="G-StMAR")
get_regime_vars(gstmar12)

---

Create object of class 'gsmar' defining a GMAR, StMAR, or G-StMAR model

Description

GSMAR creates an S3 object of class 'gsmar' that defines a GMAR, StMAR, or G-StMAR model.

Usage

GSMAR(
  data,
  p,
  M,
  params,
  model = c("GMAR", "StMAR", "G-StMAR"),
  restricted = FALSE,
  constraints = NULL,
  conditional = TRUE,
  parametrization = c("intercept", "mean"),
  calc_qresiduals,
  calc_cond_moments,
  calc_std_errors = FALSE,
  custom_h = NULL
)

## S3 method for class 'gsmar'
logLik(object, ...)

## S3 method for class 'gsmar'
residuals(object, ...)

## S3 method for class 'gsmar'
summary(object, ..., digits = 2)

## S3 method for class 'gsmar'
plot(x, ..., include_dens = TRUE)

## S3 method for class 'gsmar'
print(x, ..., digits = 2, summary_print = FALSE)

Arguments

data	a numeric vector or class 'ts' object containing the data. NA values are not supported.
p	a positive integer specifying the autoregressive order of the model.
M	For GMAR and StMAR models: a positive integer specifying the number of mixture components. For G-StMAR models: a size (2x1) integer vector specifying the number of GMAR type components M1 in the first element and StMAR type components M2 in the second element. The total number of mixture components is M=M1+M2.
params	a real valued parameter vector specifying the model. For non-restricted models: Size $(M(p+3)+M-M1-1x1)$ vector $\theta$$=$($\upsilon_{1}$$,...,$$\upsilon_{M}$, $\alpha_{1},...,\alpha_{M-1},$$\nu$) where $\upsilon_{m}$$=(\phi_{m,0},$$\phi_{m}$$,$$\sigma_{m}^2)$ $\phi_{m}$$=(\phi_{m,1},...,\phi_{m,p}), m=1,...,M$ $\nu$$=(\nu_{M1+1},...,\nu_{M})$ $M1$ is the number of GMAR type regimes. In the GMAR model, $M1=M$ and the parameter $\nu$ dropped. In the StMAR model, $M1=0$. If the model imposes linear constraints on the autoregressive parameters: Replace the vectors $\phi_{m}$ with the vectors $\psi_{m}$ that satisfy $\phi_{m}$$=$$C_{m}\psi_{m}$ (see the argument constraints). For restricted models: Size $(3M+M-M1+p-1x1)$ vector $\theta$$=(\phi_{1,0},...,\phi_{M,0},$$\phi$$,$ $\sigma_{1}^2,...,\sigma_{M}^2,$$\alpha_{1},...,\alpha_{M-1},$$\nu$), where $\phi$=$(\phi_{1},...,\phi_{p})$ contains the AR coefficients, which are common for all regimes. If the model imposes linear constraints on the autoregressive parameters: Replace the vector $\phi$ with the vector $\psi$ that satisfies $\phi$$=$$C\psi$ (see the argument constraints). Symbol $\phi$ denotes an AR coefficient, $\sigma^2$ a variance, $\alpha$ a mixing weight, and $\nu$ a degrees of freedom parameter. If parametrization=="mean", just replace each intercept term $\phi_{m,0}$ with the regimewise mean $\mu_m = \phi_{m,0}/(1-\sum\phi_{i,m})$. In the G-StMAR model, the first M1 components are GMAR type and the rest M2 components are StMAR type. Note that in the case M=1, the mixing weight parameters $\alpha$ are dropped, and in the case of StMAR or G-StMAR model, the degrees of freedom parameters $\nu$ have to be larger than $2$.
model	is "GMAR", "StMAR", or "G-StMAR" model considered? In the G-StMAR model, the first M1 components are GMAR type and the rest M2 components are StMAR type.
restricted	a logical argument stating whether the AR coefficients $\phi_{m,1},...,\phi_{m,p}$ are restricted to be the same for all regimes.
constraints	specifies linear constraints imposed to each regime's autoregressive parameters separately. For non-restricted models: a list of size $(pxq_{m})$ constraint matrices $C_{m}$ of full column rank satisfying $\phi_{m}$$=$$C_{m}\psi_{m}$ for all $m=1,...,M$, where $\phi_{m}$$=(\phi_{m,1},...,\phi_{m,p})$ and $\psi_{m}$$=(\psi_{m,1},...,\psi_{m,q_{m}})$. For restricted models: a size $(pxq)$ constraint matrix $C$ of full column rank satisfying $\phi$$=$$C\psi$, where $\phi$$=(\phi_{1},...,\phi_{p})$ and $\psi$$=\psi_{1},...,\psi_{q}$. The symbol $\phi$ denotes an AR coefficient. Note that regardless of any constraints, the autoregressive order is always p for all regimes. Ignore or set to NULL if applying linear constraints is not desired.
conditional	a logical argument specifying whether the conditional or exact log-likelihood function should be used.
parametrization	is the model parametrized with the "intercepts" $\phi_{m,0}$ or "means" $\mu_{m} = \phi_{m,0}/(1-\sum\phi_{i,m})$?
calc_qresiduals	should quantile residuals be calculated? Default is TRUE iff the model contains data.
calc_cond_moments	should conditional means and variances be calculated? Default is TRUE iff the model contains data.
calc_std_errors	should approximate standard errors be calculated?
custom_h	A numeric vector with same the length as the parameter vector: i:th element of custom_h is the difference used in central difference approximation for partial differentials of the log-likelihood function for the i:th parameter. If NULL (default), then the difference used for differentiating overly large degrees of freedom parameters is adjusted to avoid numerical problems, and the difference is 6e-6 for the other parameters.
object	object of class 'gsmar' created with fitGSMAR or GSMAR.
...	in the plot method: arguments passed to the function density which calculates the kernel density estimate of the data.
digits	number of digits to be printed (max 20)
x	object of class 'gsmar' created with fitGSMAR or GSMAR.
include_dens	Plot also kernel density estimate of the data and model implied stationary density with regimewise densities? See the details.
summary_print	if set to TRUE then the print will include approximate standard errors for the estimates, log-likelihood, information criteria values, modulus of the roots of the characteristic AR polynomials for each regime, and several unconditional moments.

Details

Models can be built without data, e.q., in order to simulate from the process, but some things such as quantile residuals and conditional moments can't be calculated without data.

If include_dens == TRUE, the kernel density estimate of the data is calculated with the function density from the package stats. By default, the default settings of that function are used, including the usage of Gaussian kernel. Use the dot parameters to adjust the settings if desired.

By the model implied stationary density we mean the stationary one-dimensional mixture density of M regimes (see KMS 2015, Theorem 1 and the discussion following it for the Gaussian case and Theorem 2 in PMS 2018 for the Student's t case). The regimewise densities (i.e. each density 1,...,M in the stationary mixture density) are multiplied with the mixing weight parameters accordingly.

In the density plot black represents the kernel density estimate of the data, grey dashed line the model implied density, and the colored dotted lines the regime wise densities.

Value

Returns an object of class 'gsmar' defining the specified GMAR, StMAR, or G-StMAR model. If data is supplied, the returned object contains (by default) empirical mixing weights, some conditional and unconditional moments, and quantile residuals. Note that the first p observations are taken as the initial values so the mixing weights, conditional moments, and quantile residuals start from the p+1:th observation (interpreted as t=1).

Functions

• logLik(gsmar): Log-likelihood method

• residuals(gsmar): residuals method to extract quantile residuals

• summary(gsmar): summary method, standard errors in brackets

• plot(gsmar): Plot method for class 'gsmar'

• print(gsmar): print method

References

• Kalliovirta L., Meitz M. and Saikkonen P. 2015. Gaussian Mixture Autoregressive model for univariate time series. Journal of Time Series Analysis, 36(2), 247-266.

• Meitz M., Preve D., Saikkonen P. 2023. A mixture autoregressive model based on Student's t-distribution. Communications in Statistics - Theory and Methods, 52(2), 499-515.

• Virolainen S. 2022. A mixture autoregressive model based on Gaussian and Student's t-distributions. Studies in Nonlinear Dynamics & Econometrics, 26(4) 559-580.

See Also

fitGSMAR, iterate_more, add_data, stmar_to_gstmar, swap_parametrization, get_gradient, simulate.gsmar, predict.gsmar, cond_moments, uncond_moments, LR_test, Wald_test

Examples

# GMAR model without data
params22 <- c(0.9, 0.4, 0.2, 0.5, 0.7, 0.5, -0.2, 0.7, 0.7)
gmar22 <- GSMAR(p=2, M=2, params=params22, model="GMAR")
gmar22

# StMAR model, without data
params12t <- c(1.38, 0.88, 0.27, 3.8, 0.74, 3.15, 0.8, 300, 3.6)
stmar12t <- GSMAR(p=1, M=2, params=params12t, model="StMAR")
stmar12t

# G-StMAR model with data
params42gs <- c(0.04, 1.34, -0.59, 0.54, -0.36, 0.01, 0.06, 1.28, -0.36,
                0.2, -0.15, 0.04, 0.19, 9.75)
gstmar42 <- GSMAR(data=M10Y1Y, p=4, M=c(1, 1), params=params42gs,
                  model="G-StMAR")
gstmar42

# Restricted G-StMAR model with data
params42gsr <- c(0.13, 0.03, 1.29, -0.4, 0.25, -0.2, 0.03, 0.05, 0.51, 2.76)
gstmar42r <- GSMAR(data=M10Y1Y, p=4, M=c(1, 1), params=params42gsr,
                   model="G-StMAR", restricted=TRUE)
gstmar42r

---