Help for package ICED

Title:

IntraClass Effect Decomposition

Version:

0.0.1

Maintainer:

Sam Parsons <sam.parsons@radboudumc.nl>

Description:

Estimate test-retest reliability for complex sampling strategies and extract variances using IntraClass Effect Decomposition. Developed by Brandmaier et al. (2018) "Assessing reliability in neuroimaging research through intra-class effect decomposition (ICED)" <doi:10.7554/eLife.35718> Also includes functions to simulate data based on sampling strategy. Unofficial version release name: "Good work squirrels".

License:

MIT + file LICENSE

URL:

https://github.com/sdparsons/ICED

BugReports:

https://github.com/sdparsons/ICED

Imports:

boot, knitr, lavaan, MASS, stringr

VignetteBuilder:

knitr

Encoding:

UTF-8

RoxygenNote:

7.1.1

Suggests:

rmarkdown, testthat (≥ 3.0.0)

Config/testthat/edition:

NeedsCompilation:

Packaged:

2022-08-16 15:04:08 UTC; samdp

Author:

Sam Parsons

[aut, cre], Rogier Kievit

[aut], Andreas Brandmaier

[aut]

Repository:

CRAN

Date/Publication:

2022-08-18 07:40:10 UTC

iced_syntax function - generates lavaan syntax for ICED models

Description

The function takes a dataframe describing the data structure and returns lavaan syntax to run the model

Usage

iced_syntax(
  structure,
  fix_lower_bounds = TRUE,
  set_variances = NULL,
  e_label = "e",
  print = TRUE,
  groups = NULL,
  groups_inequality = NULL
)

Arguments

structure

data.frame describing the structure of the data, with each variable covering a design aspect - see example. Note: currently the first variable must be time and include a different value for each repeated measure.

fix_lower_bounds

fixes error variance estimates to be positive, defaults to TRUE

set_variances

allows the user to specify a list of variances for each latent variable

e_label

user defined variable name of the error variance. defaults to "e"

print

option to print the syntax to the console. defaults to TRUE

groups

allows the user to specify a number or list of group names. The syntax will generate separate latent variable variances to estimate for each group

groups_inequality

allows the user to specify which variance components they wish to allow to vary between groups. Useful for model comparisons.

Value

returns a character string for the ICED model following lavaan syntax

Examples

## see online documentation for full examples
# https://github.com/sdparsons/ICED
structure <- data.frame(time = c("T1", "T2", "T3", "T4"),
                        day = c("day1","day1","day2","day2"),
                        session = c("session1", "session1","session2", "session3"))

run ICED models

Description

Wrapper function for lavaan to run an ICED model generated with ICED_syntax()

Usage

run_ICED(model = NULL, data = NULL, boot = NULL, ncores = NULL)

Arguments

model

lavaan model syntax, generated with ICED_syntax

data

specify data to be analysed - repeated measures variable names must correspond to separate variables in the data (wide format)

boot

run bootstrapped analysis to extract 95% CIs for the ICC and ICC2 estimates

ncores

specify the number of cores to run with boot, defaults to 1

Value

returns a list of estimated variances and reliability coefficients and the lavaan output

Examples

## see online documentation for full examples
# https://github.com/sdparsons/ICED

# generate data structure and syntax
struc <- data.frame(time = c("T1", "T2", "T3", "T4"),
day = c("day1","day1","day2","day2"),
session = c("ses1", "ses1","ses2", "ses3"))

syn <- iced_syntax(struc)

# generate data
sim1 <- sim_ICED(struc,
variances = list(time = 10,
               day = 2,
                 session = 1,
                 error = 3),
n = 2000)

res1 <- run_ICED(model = syn,
data = sim1$data)

simulates data based on ICED model structure and list of variances

Description

sim_ICED simulates n x p data frame based on ICED model structure, selected variance components, and specified n

Usage

sim_ICED(structure, variances, n, check_recovery = FALSE)

Arguments

structure

variances

list of variances corresponding to each latent variable specified in strucutre

n

number of participants to simulate

check_recovery

runs run_ICED to extract variance components in order to check the variance parameter recovery

Value

list including simulated data

Examples

# compare recovery of variance parameters

# ICED structure
struc <- data.frame(time = c("T1", "T2", "T3", "T4"),
day = c("day1","day1","day2","day2"),
session = c("ses1", "ses1","ses2", "ses3"))

sim_ICED(struc,
variances = list(time = 10,
                 day = 2,
                 session = 1,
                 error = 3),
n = 20,
check_recovery = TRUE)

sim_ICED(struc,
         variances = list(time = 10,
                          day = 2,
                          session = 1,
                          error = 3),
         n = 2000,
         check_recovery = TRUE)

converts a ICED measurement structure data.frame and a vector

Description

helper function to generate an expected covariance matrix from an ICED measurement structure and vector of variances. Not expected to be called directly, but used within sim_ICED

Usage

str2cov(structure, variances, e_label = "e")

Arguments

structure

data.frame describing the structure of the data, with each variable convering a design aspect - see example. Note: currently the first variable must be time and include a different value for each repeated measure.

variances

list of variances for each source of variance

e_label

sting label for error variance. defaults to "e"

Value

returns a matrix

Examples

struc <- data.frame(time = c("T1", "T2", "T3", "T4"),
day = c("day1","day1","day2","day2"),
session = c("ses1", "ses1","ses2", "ses3"))
 
str2cov(struc,
list(time = 10,
     day = 2,
     session = 1,
     e = 3))