starts_uni: Functions for the Univariate STARTS Model

In STARTS: Functions for the STARTS Model

Functions for the Univariate STARTS Model

Description

Functions for computing the covariance matrix and simulating data from the univariate STARTS model (Kenny & Zautra, 1995, 2001). The STARTS model can be estimated with maximum likelihood, penalized maximum likelihood (i.e., maximum posterior estimation) or Markov Chain Monte Carlo. See Luedtke, Robitzsch and Wagner (2018) for comparisons among estimation methods.

Usage

## estimation of univariate STARTS model
starts_uni_estimate(data=NULL, covmat=NULL, nobs=NULL, estimator="ML",
    pars_inits=NULL, prior_var_trait=c(3, 0.33), prior_var_ar=c(3, 0.33),
    prior_var_state=c(3, 0.33), prior_a=c(3, 0.5), est_var_trait=TRUE,
    est_var_ar=TRUE, est_var_state=TRUE, var_meas_error=0, constraints=TRUE,
    time_index=NULL, type="stationary", n.burnin=5000, n.iter=20000,
    verbose=FALSE, optim_fct="optim", use_rcpp=TRUE )

## S3 method for class 'starts_uni'
summary(object, digits=3, file=NULL, print_call=TRUE, ...)

## S3 method for class 'starts_uni'
plot(x, ...)

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

## S3 method for class 'starts_uni'
coef(object, ...)

## S3 method for class 'starts_uni'
vcov(object, ...)

## computation of covariance matrix
starts_uni_cov(W, var_trait, var_ar, var_state, a, time_index=NULL,
       add_meas_error=NULL)

## simulation of STARTS model
starts_uni_sim(N, W, var_trait, var_ar, var_state, a, time_index=NULL )

#--- deprecated functions
starts_cov(W, var_trait, var_ar, var_state, a)
starts_sim1dim(N, W, var_trait, var_ar, var_state, a )

Arguments

data	Data frame. Missing data must be coded as NA.
covmat	Covariance matrix (not necessary if data is provided)
nobs	Number of observations (not necessary if data is provided)
estimator	Type of estimator: "ML" for maximum likelihood estimation (using LAM::pmle), "PML" for penalized maximum likelihood estimation (using LAM::pmle) and "MCMC" for Markov chain Monte Carlo estimation (using LAM::amh).
pars_inits	Optional vector of initial parameters
prior_var_trait	Vector of length two specifying the inverse gamma prior for trait variance. The first entry is the prior sample size, the second entry the guess of the proportion of the variance that is attributed to the trait variance. See Luedtke et al. (2018) for further details.
prior_var_ar	Prior for autoregressive variance. See prior_var_trait for details.
prior_var_state	Prior for state variance. See prior_var_trait for details.
prior_a	Vector of length two for specification of the beta prior for stability parameter a. The first entry corresponds to the prior sample size, the second entry corresponds to the prior guess of the stability parameter.
est_var_trait	Logical indicating whether the trait variance should be estimated.
est_var_ar	Logical indicating whether the autoregressive variance should be estimated.
est_var_state	Logical indicating whether the state variance should be estimated.
var_meas_error	Value of known measurement variance. Could be based on a reliability estimate of internal consistency, for example.
constraints	Logical indicating whether variances should be constrained to be positive
time_index	Integer vector of time indices. Time points can be non-equidistant, but must be integer values.
type	Type of starts model. Only "stationary" is implemented in this package version.
n.burnin	Number of burn-in iterations (if estimator="MCMC")
n.iter	Total number of iterations (if estimator="MCMC")
verbose	Logical indicating whether iteration progress should be displayed (if estimator="ML" or estimator="PML")
optim_fct	Type of optimization function if estimator="ML" or estimator="PML". Can be "optim" for stats::optim or "nlminb" for stats::nlminb.
use_rcpp	Logical indicating whether Rcpp code should be used in estimation.
W	Number of measurement waves.
var_trait	Variance of trait component.
var_ar	Variance of autoregressive component.
var_state	Variance of state component.
N	Sample size of persons
a	Stability parameter
object	Object of class starts_uni
digits	Number of digits after decimal in summary output
file	Optional file name for summary output
print_call	Logical indicating whether call should be printed in summary output
x	Object of class starts_uni
...	Further arguments to be passed. For the plot method, see the plot method for the LAM::amh function for arguments
add_meas_error	Optional vector of measurement error variance which should be added to the diagonal of the covariance matrix.

Value

Output of starts_uni_estimate

coef	Vector of estimated parameters
...	Further values

Output of starts_uni_cov is a covariance matrix.

Output of starts_uni_sim is a data frame containing simulated values.

References

Kenny, D. A., & Zautra, A. (1995). The trait-state-error model for multiwave data. Journal of Consulting and Clinical Psychology, 63, 52-59. doi: 10.1037/0022-006X.63.1.52

Kenny, D. A., & Zautra, A. (2001). Trait-state models for longitudinal data. In L. M. Collins & A. G. Sayer (Eds.), New methods for the analysis of change (pp. 243-263). Washington, DC, US: American Psychological Association. doi: 10.1037/10409-008

Luedtke, O., Robitzsch, A., & Wagner, J. (2018). More stable estimation of the STARTS model: A Bayesian approach using Markov Chain Monte Carlo techniques. Psychological Methods, 23(3), 570-593. doi: 10.1037/met0000155

Examples

library(sirt)

#############################################################################
# EXAMPLE 1: STARTS model specification using starts_uni_estimate
#############################################################################

## use simulated dataset according to Luedtke et al. (2017)

data(data.starts01a, package="STARTS")
dat <- data.starts01a

#--- covariance matrix and number of observations
covmat <- stats::cov( dat[, paste0("E",1:5) ] )
nobs <- nrow(dat)

#*** Model 1a: STARTS model with ML estimation
mod1a <- STARTS::starts_uni_estimate( covmat=covmat, nobs=nobs)
summary(mod1a)

## Not run: 
#- estimate model based on input data
mod1a1 <- STARTS::starts_uni_estimate( data=dat[, paste0("E",1:5) ])
summary(mod1a1)

#*** Model 1b: STARTS model with penalized ML estimation using the default priors
mod1b <- STARTS::starts_uni_estimate( covmat=covmat, nobs=nobs, estimator="PML")
summary(mod1b)

#*** Model 1c: STARTS model with MCMC estimation and default priors
set.seed(987)
mod1c <- STARTS::starts_uni_estimate( covmat=covmat, nobs=nobs, estimator="MCMC")

# assess convergence
plot(mod1c)
# summary
summary(mod1c)
# extract more information
logLik(mod1c)
coef(mod1c)
vcov(mod1c)

#*** Model 1d: MCMC estimation with different prior distributions
mod1d <- STARTS::starts_uni_estimate( covmat=covmat, nobs=nobs, estimator="MCMC",
             prior_var_trait=c(10, 0.5), prior_var_ar=c(10, 0.3),
             prior_var_state=c(10, 0.2), prior_a=c(1, 0.5) )
summary(mod1d)

#*** Model 2: remove autoregressive process
mod2 <- STARTS::starts_uni_estimate( covmat=covmat, nobs=nobs, est_var_ar=FALSE)
summary(mod2)

#*** Model 3: remove stable trait factor
mod3 <- STARTS::starts_uni_estimate( covmat=covmat, nobs=nobs, est_var_trait=FALSE)
summary(mod3)

#*** Model 4: remove state variance from the model
mod4 <- STARTS::starts_uni_estimate( covmat=covmat, nobs=nobs, est_var_state=FALSE)
summary(mod4)

## End(Not run)

STARTS documentation built on May 20, 2022, 1:08 a.m.