Package 'flps' reference manual

Title:	Fully-Latent Principal Stratification
Description:	Simulation and analysis of Fully-Latent Principal Stratification (FLPS) with measurement models. Lee, Adam, Kang, & Whittaker (2023). <doi:10.1007/978-3-031-27781-8_25>. This package is supported by the Institute of Education Sciences, U.S. Department of Education, through Grant R305D210036.
Authors:	Sooyong Lee [aut, cre], Adam Sales [aut], Hyeon-Ah Kang [aut], Tiffany Whittaker [aut]
Maintainer:	Sooyong Lee <[email protected]>
License:	GPL-3
Version:	1.1.0
Built:	2024-11-17 04:57:07 UTC
Source:	https://github.com/sooyongl/flps

Fully latent principal stratification

Description

The FLPS package conducts Bayesian analysis for fully latent principal stratification via rstan.

_PACKAGE

Details

The 'flps' package.

Author(s)

Sooyong Lee [email protected]

References

Sales, A. C., & Pane, J. F. (2019). The role of mastery learning in an intelligent tutoring system: Principal stratification on a latent variable. The Annals of Applied Statistics, 13(1), 420-443. Lee, S., Adam, S., Kang, H.-A., & Whittaker, T. A. (2022). Fully latent principal stratification: Combining ps with model-based measurement models. In The annual meeting of the psychometric society (pp. 287–298).

binary.rda

Description

A data set containing binary items information. Example data regenerated from CTA1

Usage

binary
binary

Format

A data frame with variables:

schid: School ID
id: Student ID
sex: 0 = boys; 1 = girls
race: 0 = White; 1 = Others
pretest: Pre test scores
stdscore: Standardized scores
cm_sex: Cluster-mean of sex
cm_race: Cluster-mean of race
cm_pretest: Cluster-mean of Pre test scores
cm_stdscore: Cluster-mean of of Standardized scores
trt: Treatment assignment; 0 = control, 1 = treatment
Y: Outcome
q1: Binary item
q2: Binary item
q3: Binary item
q4: Binary item
q5: Binary item
q6: Binary item
q7: Binary item
q8: Binary item
q9: Binary item
q10: Binary item
q11: Binary item
q12: Binary item
q13: Binary item
q14: Binary item
q15: Binary item
q16: Binary item
q17: Binary item
q18: Binary item
q19: Binary item
q20: Binary item

Source

CTA1

Examples

data(binary)
summary(binary)
data(binary)
summary(binary)

continuous.rda

Description

A data set containing continuous items information. Example data regenerated from CTA1

Usage

continuous
continuous

Format

A data frame with variables:

schid: School ID
id: Student ID
sex: 0 = boys; 1 = girls
race: 0 = White; 1 = Others
pretest: Pre test scores
stdscore: Standardized scores
cm_sex: Cluster-mean of sex
cm_race: Cluster-mean of race
cm_pretest: Cluster-mean of Pre test scores
cm_stdscore: Cluster-mean of of Standardized scores
trt: Treatment assignment; 0 = control, 1 = treatment
Y: Outcome
q1: Continuous item
q2: Continuous item
q3: Continuous item
q4: Continuous item
q5: Continuous item
q6: Continuous item
q7: Continuous item
q8: Continuous item
q9: Continuous item
q10: Continuous item
q11: Continuous item
q12: Continuous item
q13: Continuous item
q14: Continuous item
q15: Continuous item
q16: Continuous item
q17: Continuous item
q18: Continuous item
q19: Continuous item
q20: Continuous item

Source

CTA1

Examples

data(continuous)
summary(continuous)
data(continuous)
summary(continuous)

example0.rda

Description

A generated data set for rasch FLPS to mimic CTA1 data.

Usage

example0
example0

Format

A data frame with variables:

Y: Outcome
trt: Treatment assignment; 0 = control, 1 = treatment
sex: 0 = boys; 1 = girls
race: 0 = White; 1 = Others
pretest: Pre test scores
stdscore: Standardized scores
V1: Binary item
V2: Binary item
V3: Binary item
V4: Binary item
V5: Binary item
V6: Binary item
V7: Binary item
V8: Binary item
V9: Binary item
V10: Binary item
V11: Binary item
V12: Binary item

example1.rda

Description

A generated data set containing binary items information.

Usage

example1
example1

Format

A data frame with variables:

Y: Outcome
trt: Treatment assignment; 0 = control, 1 = treatment
X1: Continuous covariate 1
X2: Continuous covariate 2
q1: Binary item
q2: Binary item
q3: Binary item
q4: Binary item
q5: Binary item
q6: Binary item
q7: Binary item
q8: Binary item
q9: Binary item
q10: Binary item

example2.rda

Description

A generated data set containing continuous items information.

Usage

example2
example2

Format

A data frame with variables:

Y: Outcome
trt: Treatment assignment; 0 = control, 1 = treatment
X1: Continuous covariate 1
X2: Continuous covariate 2
q1: Continuous item
q2: Continuous item
q3: Continuous item
q4: Continuous item
q5: Continuous item
q6: Continuous item
q7: Continuous item
q8: Continuous item
q9: Continuous item
q10: Continuous item

example3.rda

Description

A generated data set for multidimensional FLPS.

Usage

example3
example3

Format

A data frame with variables:

Y: Outcome
Z: Treatment assignment; 0 = control, 1 = treatment
X1: Continuous covariate 1
X2: Continuous covariate 2
X3: Continuous covariate 2
X4: Continuous covariate 2
V1: Continuous item
V2: Continuous item
V3: Continuous item
V4: Continuous item
V5: Continuous item
V6: Continuous item
V7: Continuous item
V8: Continuous item
V9: Continuous item
V10: Continuous item
V11: Continuous item
V12: Continuous item

Make plots related to FLPS models

Description

Make plots related to FLPS models

Usage

flps_plot(object, type = "causal", ...)
flps_plot(object, type = "causal", ...)

Arguments

`object`	a `flps` object
`type`	a character indicating the type of plots
`...`	Additional features related to plots

Value

A ggplot object that can be further customized using the ggplot2 package.

graded.rda

Description

A data set containing graded response items information. Example data regenerated from CTA1

Usage

graded
graded

Format

A data frame with variables:

schid: School ID
id: Student ID
sex: 0 = boys; 1 = girls
race: 0 = White; 1 = Others
pretest: Pre test scores
stdscore: Standardized scores
cm_sex: Cluster-mean of sex
cm_race: Cluster-mean of race
cm_pretest: Cluster-mean of Pre test scores
cm_stdscore: Cluster-mean of of Standardized scores
trt: Treatment assignment; 0 = control, 1 = treatment
Y: Outcome
q1: Graded response item
q2: Graded response item
q3: Graded response item
q4: Graded response item
q5: Graded response item
q6: Graded response item
q7: Graded response item
q8: Graded response item
q9: Graded response item
q10: Graded response item
q11: Graded response item
q12: Graded response item
q13: Graded response item
q14: Graded response item
q15: Graded response item
q16: Graded response item
q17: Graded response item
q18: Graded response item
q19: Graded response item
q20: Graded response item

Source

CTA1

Examples

data(graded)
summary(graded)
data(graded)
summary(graded)

Import compiled Stan object

Description

Import compiled Stan object

Usage

importModel(lv_type, multilevel = FALSE, lv_randomeffect = FALSE)
importModel(lv_type, multilevel = FALSE, lv_randomeffect = FALSE)

Arguments

`lv_type`	a character indicating the type of FLPS model.
`multilevel`	a logical indicating multilevel Stan model.
`lv_randomeffect`	A logical indicating whether to estimate random effects for latent variables.

Value

a Stan compiled stanmodel object generated by modelBuilder

Generate a matrix style data for simulation

Description

makeInpData is a function for generating a data based on the given information.

Usage

makeInpData(
  N,
  R2Y,
  R2eta,
  omega,
  tau0,
  tau1,
  betaL,
  betaY,
  linear = TRUE,
  ydist = "n",
  lambda,
  nitem,
  nfac = 1,
  lvmodel,
  fcovmat,
  item.missing = TRUE,
  misspec = FALSE,
  cov.res = 0,
  relsize = 0.6
)
makeInpData(
  N,
  R2Y,
  R2eta,
  omega,
  tau0,
  tau1,
  betaL,
  betaY,
  linear = TRUE,
  ydist = "n",
  lambda,
  nitem,
  nfac = 1,
  lvmodel,
  fcovmat,
  item.missing = TRUE,
  misspec = FALSE,
  cov.res = 0,
  relsize = 0.6
)

Arguments

`N`	a numeric indicating sample size.
`R2Y`	a numeric indicating predictive power of covariates.
`R2eta`	a numeric indicating Predictive power of latent variable
`omega`	a numeric indicating the size of effect of latent factor on the outcome.
`tau0`	a numeric indicating the size of difference in the outcome between the treatment and the control.
`tau1`	a numeric indicating the principal effect
`betaL`	a numeric vector indicating the effects of covariates on the latent factor
`betaY`	a numeric vector indicating the effects of covariates on the outcome
`linear`	a logical whether the relationship between the outcome and covariates is linear (default is `TRUE`).
`ydist`	a character indicating the outcome distribution (default is `n`).
`lambda`	a numeric indicating the mean of Worked problems/person. (extent to which covariates predict eta).
`nitem`	a numeric indicating the number of maximum measurement items given to students.
`nfac`	a numeric indicating the number of latent factors
`lvmodel`	a character specifying a type of latent variable model.
`fcovmat`	a matrix indicating the variance-covariance matrix of latent factors when nfac > 1
`item.missing`	a logical to make the measurement item data missing for the control group (default is `TRUE`).
`misspec`	a logical to allow cross-loadings across latent factors when nfac > 1 (default is `FALSE`).
`cov.res`	a logical to allow for residual correlations (only for CFA model) (default is `0`).
`relsize`	a numeric indicating the degree to which the latent factor explain the variances of continuous items (only for CFA model) (default is `0.6`).

Value

a list containing all the data related to population values and running FLPS.

Examples

sdat <- makeInpData(
N       = 200,  # sample size
R2Y     = 0.2,  # r^2 of outcome
R2eta   = 0.5,  # r^2 of eta by one covariates
omega   = 0.2,  # the effect of eta
tau0    = 0.13, # direct effect
tau1    = -0.06,# interaction effect between Z and eta
betaL   = 0.2,
betaY   = 0.4,
lambda  = 0.8,  # the proportion of administered items
nitem    = 10,   # the total number of items
nfac    = 1,    # the number of latent factors
lvmodel = '2pl' )
sdat <- makeInpData(
N       = 200,  # sample size
R2Y     = 0.2,  # r^2 of outcome
R2eta   = 0.5,  # r^2 of eta by one covariates
omega   = 0.2,  # the effect of eta
tau0    = 0.13, # direct effect
tau1    = -0.06,# interaction effect between Z and eta
betaL   = 0.2,
betaY   = 0.4,
lambda  = 0.8,  # the proportion of administered items
nitem    = 10,   # the total number of items
nfac    = 1,    # the number of latent factors
lvmodel = '2pl' )

Generate Fully Latent Principal Stratification data for simulation

Description

makeInpData is a function for generating a data based on the given information.

Usage

makeSimData(
  N,
  R2Y,
  R2eta,
  omega,
  tau0,
  tau1,
  betaL,
  betaY,
  linear = TRUE,
  ydist = "n",
  lambda,
  nitem,
  nfac,
  lvmodel,
  fcovmat,
  item.missing = TRUE,
  misspec = FALSE,
  cov.res = 0,
  relsize = 0.6
)
makeSimData(
  N,
  R2Y,
  R2eta,
  omega,
  tau0,
  tau1,
  betaL,
  betaY,
  linear = TRUE,
  ydist = "n",
  lambda,
  nitem,
  nfac,
  lvmodel,
  fcovmat,
  item.missing = TRUE,
  misspec = FALSE,
  cov.res = 0,
  relsize = 0.6
)

Arguments

`N`	a numeric indicating sample size.
`R2Y`	a numeric indicating predictive power of covariates.
`R2eta`	a numeric indicating Predictive power of latent variable
`omega`	a numeric indicating the size of effect of latent factor on the outcome.
`tau0`	a numeric indicating the size of difference in the outcome between the treatment and the control.
`tau1`	a numeric indicating the principal effect
`betaL`	a numeric vector indicating the effects of covariates on the latent factor
`betaY`	a numeric vector indicating the effects of covariates on the outcome
`linear`	a logical whether the relationship between the outcome and covariates is linear (default is `TRUE`).
`ydist`	a character indicating the outcome distribution (default is `n`).
`lambda`	a numeric indicating the mean of Worked problems/person. (extent to which covariates predict eta).
`nitem`	a numeric indicating the number of maximum measurement items given to students.
`nfac`	a numeric indicating the number of latent factors
`lvmodel`	a character specifying a type of latent variable model.
`fcovmat`	a matrix indicating the variance-covariance matrix of latent factors when nfac > 1
`item.missing`	a logical to make the measurement item data missing for the control group (default is `TRUE`).
`misspec`	a logical to allow cross-loadings across latent factors when nfac > 1 (default is `FALSE`).
`cov.res`	a logical to allow for residual correlations (only for CFA model) (default is `0`).
`relsize`	a numeric indicating the degree to which the latent factor explain the variances of continuous items (only for CFA model) (default is `0.6`).

Value

a list containing all the data related to population values and running FLPS.

Examples

sdat <- makeSimData(
N       = 200,  # sample size
R2Y     = 0.2,  # r^2 of outcome
R2eta   = 0.5,  # r^2 of eta by one covariates
omega   = 0.2,  # the effect of eta
tau0    = 0.13, # direct effect
tau1    = -0.06,# interaction effect between Z and eta
betaL   = 0.2,
betaY   = 0.4,
lambda  = 0.8,  # the proportion of administered items
nitem    = 10,   # the total number of items
nfac    = 1,    # the number of latent factors
lvmodel = '2pl' )

sdat <- makeSimData(
N       = 200,  # sample size
R2Y     = 0.2,  # r^2 of outcome
R2eta   = 0.5,  # r^2 of eta by one covariates
omega   = 0.2,  # the effect of eta
tau0    = 0.13, # direct effect
tau1    = -0.06,# interaction effect between Z and eta
betaL   = 0.2,
betaY   = 0.4,
lambda  = 0.8,  # the proportion of administered items
nitem    = 10,   # the total number of items
nfac    = 1,    # the number of latent factors
lvmodel = '2pl' )

Generate compiled Stan object to facilitate the analysis

Description

Generate compiled Stan object to facilitate the analysis

Usage

modelBuilder(lv_type, multilevel = FALSE, lv_randomeffect = FALSE)
modelBuilder(lv_type, multilevel = FALSE, lv_randomeffect = FALSE)

Arguments

`lv_type`	A character string specifying the type of FLPS model
`multilevel`	a logical indicating multilevel Stan model.
`lv_randomeffect`	A logical indicating whether to estimate random effects for latent variables.

Value

There's no return, but the compiled objects are saved in the package root directory.

Plot

Description

Plot

Usage

## S3 method for class 'flps'
plot(x, type = NULL, pars = c("tau0", "tau1"), ...)
## S3 method for class 'flps'
plot(x, type = NULL, pars = c("tau0", "tau1"), ...)

Arguments

`x`	an object of class `flps`
`type`	a string for the type of plot
`pars`	a character vector indicating the target parameters
`...`	additional options for `stan_plot`

Value

A ggplot object that can be further customized using the ggplot2 package.

Print results

Description

Print results

Usage

## S3 method for class 'flps'
print(x, ...)
## S3 method for class 'flps'
print(x, ...)

Arguments

`x`	an object of class `flps`
`...`	additional options for future development

Value

Summary of FLPS model are printed.

Print summary of results

Description

Print summary of results

Usage

## S3 method for class 'summary.flps'
print(x, type = "structures", ...)
## S3 method for class 'summary.flps'
print(x, type = "structures", ...)

Arguments

x

an object of class flps

type

a string for the part of FLPS model

structures : prints the results of structural parts.
measurement : prints the results of measurement parts.
latent : prints the information of individual latent scores
raw : prints the results via the summary function of rstan package..

...

additional options for future development

Value

Summary of FLPS model are printed.

Conduct fully latent principal stratification

Description

Conduct fully latent principal stratification

Usage

runFLPS(
  inp_data = NULL,
  compiled_stan = NULL,
  outcome = NULL,
  trt = NULL,
  covariate = NULL,
  lv_model = NULL,
  lv_type = NULL,
  priors_input = NULL,
  stan_options = list(),
  ...
)
runFLPS(
  inp_data = NULL,
  compiled_stan = NULL,
  outcome = NULL,
  trt = NULL,
  covariate = NULL,
  lv_model = NULL,
  lv_type = NULL,
  priors_input = NULL,
  stan_options = list(),
  ...
)

Arguments

`inp_data`	A matrix or data frame containing the input data.
`compiled_stan`	An object of S4 class stanmodel produced by the `modelBuilder` function.
`outcome`	A character string specifying the outcome variable's name.
`trt`	A character string specifying the treatment or control group variable's name.
`covariate`	A character string specifying the covariate variable names.
`lv_model`	A description of the latent variable model using syntax akin to the lavaan package. Key operators include: `=~` : Denotes associations between factors and indicators (e.g., F1 =~ v1 + v2 + v3). All indicators associated with the corresponding factor should be written in the same line with `+`. `+` : Specifies a series of indicators.
`lv_type`	A character string indicating the type of latent variable models.
`priors_input`	A list specifying the priors or defaults to N(0, 5) if not provided. Relevant parameters: `tau0` (group difference), `tau1` (principal effects), and `omega` (effect of latent factors on outcome). Ensure that the lengths of `tau1` and `omega` match the number of factors. Examples: `list(tau0 = c(0, 1), tau1 = c(0.5, 1))` : Mean and variance for normal priors. `list(tau1 = list(c(0.5, 1), c(-0.4, 1)))` : For two factors.
`stan_options`	A list of options for [rstan::stan()], specified as 'name = value'.
`...`	Additional parameters for the latent variable models `nclass` A number specifying the number of latent classes. `multilevel` A logical indicating if a multilevel structure is present. `lv_randomeffect` A logical indicating whether to estimate random effects for latent variables. `group_id` A string for grouping variable for multilevel structure.

Value

An object of class flps encompassing a stanfit object. Components include:

`call`	Function call with arguments.
`inp_data`	The input data frame provided.
`flps_model`	The Stan syntax used in [rstan::stan()].
`flps_data`	Data list used for [rstan::stan()].
`flps_fit`	Resulting `stanfit` object.
`time`	A numeric; Time taken for computation

Examples


inp_data <- flps::makeInpData(
  N       = 200,
  R2Y     = 0.2,
  R2eta   = 0.5,
  omega   = 0.2,
  tau0    = 0.23,
  tau1    = -0.16,
  betaL   = 0.1,
  betaY   = 0.2,
  lambda  = 0.8,
  nitem    = 10,
  nfac    = 1,
  lvmodel = 'rasch' )

res <- runFLPS(
   inp_data = inp_data,
   outcome = "Y",
   trt = "Z",
   covariate = c("X1"),
   lv_type = "rasch",
   lv_model = "F =~ v1 + v2 + v3 + v4 + v5 + v6 + v7 + v8 + v9 + v10",
   stan_options = list(iter = 1000, warmup = 500, cores = 1, chains = 2)
   )


inp_data <- flps::makeInpData(
  N       = 200,
  R2Y     = 0.2,
  R2eta   = 0.5,
  omega   = 0.2,
  tau0    = 0.23,
  tau1    = -0.16,
  betaL   = 0.1,
  betaY   = 0.2,
  lambda  = 0.8,
  nitem    = 10,
  nfac    = 1,
  lvmodel = 'rasch' )

res <- runFLPS(
   inp_data = inp_data,
   outcome = "Y",
   trt = "Z",
   covariate = c("X1"),
   lv_type = "rasch",
   lv_model = "F =~ v1 + v2 + v3 + v4 + v5 + v6 + v7 + v8 + v9 + v10",
   stan_options = list(iter = 1000, warmup = 500, cores = 1, chains = 2)
   )

Summarize the results

Description

Summarize the results

Usage

## S3 method for class 'flps'
summary(object, type = "structures", ...)
## S3 method for class 'flps'
summary(object, type = "structures", ...)

Arguments

object

an object of class flps

type

a string for the part of FLPS model

structures : prints the results of structural parts.
measurement : prints the results of measurement parts.
latent : prints the information of individual latent scores
raw : prints the results via the summary function of rstan package..

...

additional options for future development

Value

Summary of FLPS model are printed.

Package 'flps'

Help Index

Fully latent principal stratification

Description

Details

Author(s)

References

binary.rda

Description

Usage

Format

Source

Examples

continuous.rda

Description

Usage

Format

Source

Examples

example0.rda

Description

Usage

Format

example1.rda

Description

Usage

Format

example2.rda

Description

Usage

Format

example3.rda

Description

Usage

Format

Make plots related to FLPS models

Description

Usage

Arguments

Value

graded.rda

Description

Usage

Format

Source

Examples

Import compiled Stan object

Description

Usage

Arguments

Value

Generate a matrix style data for simulation

Description

Usage

Arguments

Value

Examples

Generate Fully Latent Principal Stratification data for simulation

Description

Usage

Arguments

Value

Examples

Generate compiled Stan object to facilitate the analysis

Description

Usage

Arguments

Value

Plot

Description

Usage

Arguments

Value

Print results

Description

Usage

Arguments

Value

Print summary of results

Description