Skip to contents

Functions for the Univariate STARTS Model

starts_uni.Rd

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 starts_uni
summary(object, digits=3, file=NULL, print_call=TRUE, ...)

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

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

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

# S3 method for 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)

if (FALSE) {
#- 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)
}