Package 'STARTS'

Functions for the STARTS Model

Description

Contains functions for estimating the STARTS model of Kenny and Zautra (1995, 2001) <DOI:10.1037/0022-006X.63.1.52>, <DOI:10.1037/10409-008>. Penalized maximum likelihood estimation and Markov Chain Monte Carlo estimation are also provided, see Luedtke, Robitzsch and Wagner (2018) <DOI:10.1037/met0000155>.

Author(s)

Alexander Robitzsch [aut,cre] (<https://orcid.org/0000-0002-8226-3132>), Oliver Luedtke [aut] (<https://orcid.org/0000-0001-9744-3059>)

Maintainer: Alexander Robitzsch <[email protected]>

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

---

Datasets in the STARTS Package

Description

Some datasets for illustration used in the examples of the STARTS package.

Usage

data(data.starts01a)
data(data.starts01b)
data(data.starts02)
data(data.starts03a)
data(data.starts03b)
data(data.starts03c)

Format

• data.starts01a. A resimulated dataset containing three factors from the Big5 scale measured at five time points used in Luedtke, Robitzsch and Wagner (2018). The dataset only contains observations without missing data.

  'data.frame': 890 obs. of 16 variables:
$ id: int 100006 100008 100010 100014 100032 100033 100035 100038 100049 100050 ...
$ E1: num -0.28 1.48 0.12 -1.05 -0.28 ...
$ E2: num 0.12 -0.092 0.495 -0.679 -0.467 ...
$ E3: num 1.08 0.12 0.12 -1.27 -0.28 ...
$ E4: num 0.495 0.12 1.294 -2.229 -0.28 ...
$ E5: num -0.092 0.707 0.707 -2.041 -0.092 ...
$ N1: num 1.114 -0.173 -0.017 0.958 1.27 ...
$ N2: num -0.348 0.003 -1.167 1.602 1.758 ...
$ N3: num -0.192 0.471 -0.348 1.114 0.627 ...
$ N4: num -0.348 -1.167 -0.504 1.426 1.27 ...
$ N5: num -0.192 -0.836 -0.192 2.421 1.27 ...
$ O1: num 1.994 -1.82 -0.107 -0.678 -0.792 ...
$ O2: num 1.423 -0.678 -0.678 -0.678 1.423 ...
$ O3: num 1.423 -1.066 -0.678 0.075 0.852 ...
$ O4: num -0.29 -0.678 -0.29 0.075 -0.107 ...
$ O5: num 1.217 -1.637 -0.29 -0.678 0.646 ...
  

• data.starts01b. Like data.starts01a, but the dataset also contains cases with missing data.

  'data.frame': 3215 obs. of 17 variables:
$ id : int 100001 100002 100003 100004 100005 100006 100007 100008 100009 100010 ...
$ patt: Factor w/ 26 levels "P00010","P00011",..: 24 19 20 25 22 26 18 26 19 26 ...
$ E1 : num 0.308 1.67 0.308 0.308 -0.468 ...
$ E2 : num 0.308 0.895 0.707 0.707 0.12 0.12 NA -0.092 -0.28 0.496 ...
$ E3 : num 0.895 NA NA 0.895 NA ...
$ E4 : num NA NA NA 0.496 0.496 ...
$ E5 : num 0.707 NA 0.308 NA 0.496 -0.092 -0.28 0.707 NA 0.707 ...
$ N1 : num 0.783 -0.017 -0.192 -0.017 -0.504 ...
$ N2 : num 1.114 -0.348 -0.348 -0.348 -0.836 ...
$ N3 : num -0.348 NA NA -0.348 NA ...
$ N4 : num NA NA NA -0.504 -1.811 ...
$ N5 : num 0.471 NA -0.192 NA -1.421 ...
$ O1 : num -0.495 -0.107 -0.495 1.035 -0.792 ...
$ O2 : num -0.107 -0.107 -0.29 1.035 -0.29 ...
$ O3 : num 0.464 NA NA 1.423 NA ...
$ O4 : num NA NA NA 1.423 0.281 ...
$ O5 : num 0.646 NA -1.066 NA 0.281 ...
  

• data.starts02 contrains means and covariance matrices of the study of Wu (2016) for the older and the younger cohort (Table 2). Variables a indicate item parcels of negative attitude factor at six occasions. Variable b denotes the performance difficulty factor and variable c the somatic factor.

  List of 2
$ older_cohort :List of 3
..$ nobs : num 630
..$ mean : Named num [1:18] 3.53 3.46 3.12 2.71 2.8 2.67 2.62 2.69 2.46 2.37 ...
.. ..- attr(*, "names")=chr [1:18] "a1" "a2" "a3" "a4" ...
..$ covmat:'data.frame': 18 obs. of 18 variables:
$ younger_cohort:List of 3
..$ nobs : num 660
..$ mean : Named num [1:18] 4.62 4.52 4.46 3.58 3.96 3.21 2.94 3.16 3.03 2.74 ...
.. ..- attr(*, "names")=chr [1:18] "a1" "a2" "a3" "a4" ...
..$ covmat:'data.frame': 18 obs. of 18 variables:
  

• data.starts03a contains data from Wagner, Luedtke and Trautwein (2016) of the total sample. data.starts03b contains covariance matrices for both gender groups. data.starts03c contains covariance matrices for both groups of different levels of depression.
  

  The structure of data.starts03a is

  List of 2
$ nobs : num 4532
$ covmat: num [1:6, 1:6] 0.236 0.164 0.147 0.129 0.13 ...
..- attr(*, "dimnames")=List of 2
.. ..$ : chr [1:6] "T1" "T2" "T3" "T4" ...
.. ..$ : chr [1:6] "T1" "T2" "T3" "T4" ...
  

  The structure of data.starts03b is

  List of 2
$ female:List of 2
..$ nobs : num 2495
..$ covmat: num [1:6, 1:6] 0.22 0.158 0.139 0.18 0.116 ...
.. ..- attr(*, "dimnames")=List of 2
.. .. ..$ : chr [1:6] "T1" "T2" "T3" "T4" ...
.. .. ..$ : chr [1:6] "T1" "T2" "T3" "T4" ...
$ male :List of 2
..$ nobs : num 2037
..$ covmat: num [1:6, 1:6] 0.25 0.165 0.152 0.13 0.147 ...
.. ..- attr(*, "dimnames")=List of 2
.. .. ..$ : chr [1:6] "T1" "T2" "T3" "T4" ...
.. .. ..$ : chr [1:6] "T1" "T2" "T3" "T4" ...
  

  The structure of data.starts03c is

  List of 2
$ high:List of 2
..$ nobs : num 1342
..$ covmat: num [1:6, 1:6] 0.24 0.172 0.153 0.191 0.127 ...
.. ..- attr(*, "dimnames")=List of 2
.. .. ..$ : chr [1:6] "T1" "T2" "T3" "T4" ...
.. .. ..$ : chr [1:6] "T1" "T2" "T3" "T4" ...
$ low :List of 2
..$ nobs : num 1742
..$ covmat: num [1:6, 1:6] 0.213 0.12 0.118 0.109 0.12 ...
.. ..- attr(*, "dimnames")=List of 2
.. .. ..$ : chr [1:6] "T1" "T2" "T3" "T4" ...
.. .. ..$ : chr [1:6] "T1" "T2" "T3" "T4" ...
  

References

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

Wagner, J., Luedtke, O., & Trautwein, U. (2016). Self-esteem is mostly stable across young adulthood: Evidence from latent STARTS models. Journal of Personality, 84(4), 523-535. doi:10.1111/jopy.12178

Wu, P.-C. (2016). Longitudinal stability of the Beck Depression Inventory II: A latent trait-state-occasion model. Journal of Psychoeducational Assessment, 34, 39-53. doi:10.1177/0734282915582101

---

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)

---

Utility Functions in the STARTS Package

Description

Utlity functions in the STARTS package

Usage

## density inverse gamma distribution
digamma2(x, n0, var0)

Arguments

x	Numeric Vector
n0	Prior sample size
var0	Prior variance

---