Fit the First-Order Discrete-Time Vector Autoregressive Model by ID

The function fits the first-order discrete-time vector autoregressive model for each unit ID.

Usage

FitDTVARIDMx(
  data,
  observed,
  id,
  alpha_fixed = FALSE,
  alpha_free = NULL,
  alpha_values = NULL,
  alpha_lbound = NULL,
  alpha_ubound = NULL,
  beta_fixed = FALSE,
  beta_free = NULL,
  beta_values = NULL,
  beta_lbound = NULL,
  beta_ubound = NULL,
  psi_diag = FALSE,
  psi_d_free = NULL,
  psi_d_values = NULL,
  psi_d_lbound = NULL,
  psi_d_ubound = NULL,
  psi_l_free = NULL,
  psi_l_values = NULL,
  psi_l_lbound = NULL,
  psi_l_ubound = NULL,
  theta_fixed = FALSE,
  theta_d_free = NULL,
  theta_d_values = NULL,
  theta_d_lbound = NULL,
  theta_d_ubound = NULL,
  mu0_fixed = TRUE,
  mu0_func = TRUE,
  mu0_free = NULL,
  mu0_values = NULL,
  mu0_lbound = NULL,
  mu0_ubound = NULL,
  sigma0_fixed = TRUE,
  sigma0_func = TRUE,
  sigma0_diag = FALSE,
  sigma0_d_free = NULL,
  sigma0_d_values = NULL,
  sigma0_d_lbound = NULL,
  sigma0_d_ubound = NULL,
  sigma0_l_free = NULL,
  sigma0_l_values = NULL,
  sigma0_l_lbound = NULL,
  sigma0_l_ubound = NULL,
  try = 1000,
  ncores = NULL,
  path = getwd(),
  prefix = "fitdtvarmxid",
  clean = TRUE,
  ...
)

Arguments

data: Data frame. A data frame object of data for potentially multiple subjects that contain a column of subject ID numbers (i.e., an ID variable), and at least one column of observed values.
observed: Character vector. A vector of character strings of the names of the observed variables in the data.
id: Character string. A character string of the name of the ID variable in the data.
alpha_fixed: Logical. If TRUE, the dynamic model intercept vector alpha is fixed. If FALSE, alpha is estimated.
alpha_free: Logical vector indicating which elements of alpha are freely estimated. If NULL, all elements are free. Ignored if alpha_fixed = TRUE.
alpha_values: Numeric vector of values for alpha. If alpha_fixed = TRUE, these are fixed values. If alpha_fixed = FALSE, these are starting values. If NULL, defaults to a vector of zeros.
alpha_lbound: Numeric vector of lower bounds for alpha. If NULL, no lower bounds are set. Ignored if alpha_fixed = TRUE.
alpha_ubound: Numeric vector of upper bounds for alpha. If NULL, no upper bounds are set. Ignored if alpha_fixed = TRUE.
beta_fixed: Logical. If TRUE, the dynamic model coefficient matrix beta is fixed. If FALSE, beta is estimated.
beta_free: Logical matrix indicating which elements of beta are freely estimated. If NULL, all elements are free. Ignored if beta_fixed = TRUE.
beta_values: Numeric matrix of values for beta. If beta_fixed = TRUE, these are fixed values. If beta_fixed = FALSE, these are starting values. If NULL, defaults to a zero matrix.
beta_lbound: Numeric matrix of lower bounds for beta. If NULL, defaults to -1.5. Ignored if beta_fixed = TRUE.
beta_ubound: Numeric matrix of upper bounds for beta. If NULL, defaults to +1.5. Ignored if beta_fixed = TRUE.
psi_diag: Logical. If TRUE, psi is diagonal. If FALSE, psi is symmetric.
psi_d_free: Logical vector indicating free/fixed status of the elements of psi_d. If NULL, all element of psi_d are free.
psi_d_values: Numeric vector with starting values for psi_d. If NULL, defaults to a vector of ones.
psi_d_lbound: Numeric vector with lower bounds for psi_d. If NULL, no lower bounds are set.
psi_d_ubound: Numeric vector with upper bounds for psi_d. If NULL, no upper bounds are set.
psi_l_free: Logical matrix indicating which strictly-lower-triangular elements of psi_l are free. Ignored if psi_diag = TRUE.
psi_l_values: Numeric matrix of starting values for the strictly-lower-triangular elements of psi_l. If NULL, defaults to a null matrix.
psi_l_lbound: Numeric matrix with lower bounds for psi_l. If NULL, no lower bounds are set.
psi_l_ubound: Numeric matrix with upper bounds for psi_l. If NULL, no upper bounds are set.
theta_fixed: Logical. If TRUE, the measurement error matrix theta is fixed to the null matrix. If FALSE, only diagonal elements are estimated (off-diagonals fixed to zero).
theta_d_free: Logical vector indicating free/fixed status of the diagonal parameters theta_d. If NULL, all element of theta_d are free.
theta_d_values: Numeric vector with starting values for theta_d. If theta_fixed = TRUE, these are fixed values. If theta_fixed = FALSE, these are starting values. If NULL, defaults to an identity matrix.
theta_d_lbound: Numeric vector with lower bounds for theta_d. If NULL, no lower bounds are set.
theta_d_ubound: Numeric vector with upper bounds for theta_d. If NULL, no upper bounds are set.
mu0_fixed: Logical. If TRUE, the initial mean vector mu0 is fixed. If FALSE, mu0 is estimated.
mu0_func: Logical. If TRUE and mu0_fixed = TRUE, mu0 is fixed to $ (I - \beta)^{-1} \alpha $.
mu0_free: Logical vector indicating which elements of mu0 are freely estimated.
mu0_values: Numeric vector of values for mu0. If mu0_fixed = TRUE, these are fixed values. If mu0_fixed = FALSE, these are starting values. If NULL, defaults to a vector of zeros.
mu0_lbound: Numeric vector of lower bounds for mu0. If NULL, no lower bounds are set. Ignored if mu0_fixed = TRUE.
mu0_ubound: Numeric vector of upper bounds for mu0. If NULL, no upper bounds are set. Ignored if mu0_fixed = TRUE.
sigma0_fixed: Logical. If TRUE, the initial covariance matrix sigma0 is fixed. If FALSE, sigma0 is estimated.
sigma0_func: Logical. If TRUE and sigma0_fixed = TRUE, sigma0 is fixed to $ (I - \beta \otimes \beta)^{-1} \mathrm{Vec}(\Psi) $.
sigma0_diag: Logical. If TRUE, sigma0 is diagonal. If FALSE, sigma0 is symmetric.
sigma0_d_free: Logical vector indicating free/fixed status of the elements of sigma0_d. If NULL, all element of sigma0_d are free.
sigma0_d_values: Numeric vector with starting values for sigma0_d. If NULL, defaults to a vector of ones.
sigma0_d_lbound: Numeric vector with lower bounds for sigma0_d. If NULL, no lower bounds are set.
sigma0_d_ubound: Numeric vector with upper bounds for sigma0_d. If NULL, no upper bounds are set.
sigma0_l_free: Logical matrix indicating which strictly-lower-triangular elements of sigma0_l are free. Ignored if sigma0_diag = TRUE.
sigma0_l_values: Numeric matrix of starting values for the strictly-lower-triangular elements of sigma0_l. If NULL, defaults to a null matrix.
sigma0_l_lbound: Numeric matrix with lower bounds for sigma0_l. If NULL, no lower bounds are set.
sigma0_l_ubound: Numeric matrix with upper bounds for sigma0_l. If NULL, no upper bounds are set.
try: Positive integer. Number of extra optimization tries.
ncores: Positive integer. Number of cores to use.
path: Path to a directory to store estimates by ID.
prefix: Character string. Prefix used for the file names for the estimates by ID.
clean: Logical. If clean = TRUE, delete intermediate files generated by the function.
...: Additional optional arguments to pass to mxTryHard.

Value

Returns an object of class dtvaridmx which is a list with the following elements:

call: Function call.
args: List of function arguments.
fun: Function used ("FitDTVARIDMx").
output: A list of fitted OpenMx models.

Details

The measurement model is given by $$ \mathbf{y}_{i, t} = \boldsymbol{\Lambda} \boldsymbol{\eta}_{i, t} + \boldsymbol{\varepsilon}_{i, t}, \quad \mathrm{with} \quad \boldsymbol{\varepsilon}_{i, t} \sim \mathcal{N} \left( \mathbf{0}, \boldsymbol{\Theta} \right) $$ where $\mathbf{y}_{i, t}$, $\boldsymbol{\eta}_{i, t}$, and $\boldsymbol{\varepsilon}_{i, t}$ are random variables and $\boldsymbol{\Lambda}$, and $\boldsymbol{\Theta}$ are model parameters. $\mathbf{y}_{i, t}$ represents a vector of observed random variables, $\boldsymbol{\eta}_{i, t}$ a vector of latent random variables, and $\boldsymbol{\varepsilon}_{i, t}$ a vector of random measurement errors, at time $t$ and individual $i$. $\boldsymbol{\Lambda}$ denotes a matrix of factor loadings, and $\boldsymbol{\Theta}$ the covariance matrix of $\boldsymbol{\varepsilon}$. In this model, $\boldsymbol{\Lambda}$ is an identity matrix and $\boldsymbol{\Theta}$ is a diagonal matrix.

The dynamic structure is given by $$ \boldsymbol{\eta}_{i, t} = \boldsymbol{\alpha} + \boldsymbol{\beta} \boldsymbol{\eta}_{i, t - 1} + \boldsymbol{\zeta}_{i, t}, \quad \mathrm{with} \quad \boldsymbol{\zeta}_{i, t} \sim \mathcal{N} \left( \mathbf{0}, \boldsymbol{\Psi} \right) $$ where $\boldsymbol{\eta}_{i, t}$, $\boldsymbol{\eta}_{i, t - 1}$, and $\boldsymbol{\zeta}_{i, t}$ are random variables, and $\boldsymbol{\alpha}$, $\boldsymbol{\beta}$, and $\boldsymbol{\Psi}$ are model parameters. Here, $\boldsymbol{\eta}_{i, t}$ is a vector of latent variables at time $t$ and individual $i$, $\boldsymbol{\eta}_{i, t - 1}$ represents a vector of latent variables at time $t - 1$ and individual $i$, and $\boldsymbol{\zeta}_{i, t}$ represents a vector of dynamic noise at time $t$ and individual $i$. $\boldsymbol{\alpha}$ denotes a vector of intercepts, $\boldsymbol{\beta}$ a matrix of autoregression and cross regression coefficients, and $\boldsymbol{\Psi}$ the covariance matrix of $\boldsymbol{\zeta}_{i, t}$.

Covariances such as $\boldsymbol{\Psi}$ and $\boldsymbol{\Theta}$ are estimated using the LDL′ decomposition of a positive definite covariance matrix. See LDL() for more details.

References

Hunter, M. D. (2017). State space modeling in an open source, modular, structural equation modeling environment. Structural Equation Modeling: A Multidisciplinary Journal, 25(2), 307–324. doi:10.1080/10705511.2017.1369354

Neale, M. C., Hunter, M. D., Pritikin, J. N., Zahery, M., Brick, T. R., Kirkpatrick, R. M., Estabrook, R., Bates, T. C., Maes, H. H., & Boker, S. M. (2015). OpenMx 2.0: Extended structural equation and statistical modeling. Psychometrika, 81(2), 535–549. doi:10.1007/s11336-014-9435-8

Author

Ivan Jacob Agaloos Pesigan

Examples

if (FALSE) { # \dontrun{
# Generate data using the simStateSpace package------------------------------
set.seed(42)
beta_mu <- matrix(
  data = c(
    0.7, 0.5, -0.1,
    0.0, 0.6, 0.4,
    0, 0, 0.5
  ),
  nrow = 3
)
beta_sigma <- diag(3 * 3)
beta <- simStateSpace::SimBetaN(
  n = 5,
  beta = beta_mu,
  vcov_beta_vec_l = t(chol(beta_sigma))
)
sim <- simStateSpace::SimSSMVARIVary(
  n = 5,
  time = 100,
  mu0 = list(rep(x = 0, times = 3)),
  sigma0_l = list(t(chol(diag(3)))),
  alpha = list(rep(x = 0, times = 3)),
  beta = beta,
  psi_l = list(t(chol(diag(3))))
)
data <- as.data.frame(sim)

# Fit the model--------------------------------------------------------------
library(fitDTVARMx)
fit <- FitDTVARIDMx(
  data = data,
  observed = c("y1", "y2", "y3"),
  id = "id"
)
print(fit)
summary(fit)
coef(fit)
vcov(fit)
} # }