Functions for the Univariate STARTS Model
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.
## 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 )
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.
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.
Kenny, D. A., & Zautra, A. (1995). The trait-state-error model for multiwave data. Journal of Consulting and Clinical Psychology, 63, 52-59. tools:::Rd_expr_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. tools:::Rd_expr_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. tools:::Rd_expr_doi("10.1037/met0000155")
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)
Useful links