starts_uni {STARTS} | R Documentation |
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 |
covmat |
Covariance matrix (not necessary if |
nobs |
Number of observations (not necessary if |
estimator |
Type of estimator: |
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_state |
Prior for state variance. See |
prior_a |
Vector of length two for specification of the beta prior for 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 |
n.burnin |
Number of burn-in iterations (if |
n.iter |
Total number of iterations (if |
verbose |
Logical indicating whether iteration progress should be
displayed (if |
optim_fct |
Type of optimization function if |
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 |
digits |
Number of digits after decimal in |
file |
Optional file name for |
print_call |
Logical indicating whether call should be printed in |
x |
Object of class |
... |
Further arguments to be passed. For the |
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)