Title: | 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>. |
Authors: | Alexander Robitzsch [aut,cre]
|
Maintainer: | Alexander Robitzsch <[email protected]> |
License: | GPL (>= 2) |
Version: | 1.4-14 |
Built: | 2024-08-16 03:59:56 UTC |
Source: | https://github.com/alexanderrobitzsch/starts |
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>.
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]>
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
Some datasets for illustration used in the examples of the STARTS package.
data(data.starts01a) data(data.starts01b) data(data.starts02) data(data.starts03a) data(data.starts03b) data(data.starts03c)
data(data.starts01a) data(data.starts01b) data(data.starts02) data(data.starts03a) data(data.starts03b) data(data.starts03c)
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" ...
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 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 )
## 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 |
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. |
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. 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
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)
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)
Utlity functions in the STARTS package
## density inverse gamma distribution digamma2(x, n0, var0)
## density inverse gamma distribution digamma2(x, n0, var0)
x |
Numeric Vector |
n0 |
Prior sample size |
var0 |
Prior variance |