---
title: "Measurement Invariance via Equivalence Testing and Projection Method"
author: "Ge Jiang, Yujiao Mai, and Ke-Hai Yuan"
output: 
  #pdf_document
  html_document 
vignette: >
  %\VignetteIndexEntry{Supplementary_Materials}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

This supplementary document illustrates the use of the accompanying R package equaltestMI. The sample statistics from Table 1 of Lee and Al Otaiba (2015) are used as an example. The description of the data can be found in the original article and the results obtained from equaltestMI are discussed at length in the published article “Advances in Measurement Invariance and Mean Comparison of Latent Variables: Equivalence Testing and A Projection-Based Approach” <doi: 10.3389/fpsyg.2017.01823>.

The R package equaltestMI is available on CRAN and can be downloaded for use on any R platform with version higher than 3.1.0. Users can pass different arguments to the main function eqMI.main() to examine measurement invariance using the conventional multiple-group approach (NHT) or equivalence testing (ET) approach. Under the framework of equivalence testing, users obtain the minimum tolerable size (T-size) and adjusted cutoff values to evaluate the goodness-of-fit of each invariance test. The projection method is also available for testing the equality of latent means.

## Important Notes:

This package is developed for complete dataset with two groups/time points. Use of saturated models might lead to problems in calculation of adjusted RMSEA thresholds. Please consider alternative methods if you have datasets that do not satisfy the requirements. 



## Part 0: Installation

Users can install the package from CRAN:

```{r setup, message=FALSE, warning=FALSE}
## load package
# install.packages("equaltestMI")
library(equaltestMI)
```

or install the most recent version from the maintainer's GitHub repository:

```{r setup2, message=FALSE, warning=FALSE}
# install.packages("devtools")
# library(devtools)
# devtools::install_github("gabriellajg/equaltestMI", force=TRUE)
library(equaltestMI)
```


## Part 1: Sample Means and Covariance Matrices of the Example Data

Load data first:

```{r}
data(LeeAlOtaiba)
# contains sample covariance matrices and sample means of four groups
```

We will use two of the groups as illustration:

```{r}
## group 1 = boys ineligible for free-reduced lunches
Group1 <- LeeAlOtaiba$BoysIneligible
Group1 <- as.matrix(Group1)

## group 2 = boys eligible for free-reduced lunches
Group2 <- LeeAlOtaiba$BoysEligible
Group2 <- as.matrix(Group2)

# sample means:
M1 <- Group1[1,]
M2 <- Group2[1,]

# sample covariance matrices:
Cov1 <- Group1[2:7,]
Cov2 <- Group2[2:7,]
```

#### Sample statistics for boys ineligible for free-reduced lunches (Group 1):

Sample means: 

```{r, echo=FALSE}
M1
```

Sample Covariance Matrix:

```{r, echo=FALSE}
round(Cov1, 3)
```


#### Sample statistics for boys eligible for free-reduced lunches (Group 2):

Sample means: 

```{r, echo=FALSE}
M2
```

Sample Covariance Matrix:

```{r, echo=FALSE}
round(Cov2, 3)
```


## Part 2: R Script for Obtaining Results from Equivalence Testing and Projection Method


```{r}
## lavaan model syntax
model <- '
AlphabetKnowledge =~ Letter_Name+ Letter_Sound
PhonologicalAwareness =~ Blending + Elision
Spelling =~ Real_Words + Pseudo_Words
'
```



```{r, eval=FALSE}
## the results using equivalence testing and projection method
## full R output will be presented in Part 3
test <- eqMI.main(model = model, 
	sample.nobs = c(78, 174), 
	sample.mean = list(M1, M2), 
	sample.cov = list(Cov1, Cov2),
	meanstructure = TRUE, 
	output = 'both', 
	quiet = TRUE, 	
	equivalence.test = TRUE, adjRMSEA = TRUE, 
	projection = TRUE, bootstrap = FALSE)
```



## Part 3: Full R Output of the “test” object in Part 2

```{r, echo=FALSE}
## the results using equivalence testing and projection method
test <- eqMI.main(model = model, 
	sample.nobs = c(78, 174), 
	sample.mean = list(M1, M2), 
	sample.cov = list(Cov1, Cov2),
	meanstructure = TRUE, 
	output = 'both', 
	quiet = FALSE, 	
	equivalence.test = TRUE, adjRMSEA = TRUE, 
	projection = TRUE, bootstrap = FALSE)
```



## Part 4: Some Commonly Performed Analysis

1. results using conventional multiple-group SEM approach:

```{r, eval=FALSE}
test1 <- eqMI.main(model = model, 
	sample.nobs = c(78, 174), sample.cov = list(Cov1, Cov2), 
	sample.mean = list(M1, M2), meanstructure = TRUE, 
	equivalence.test = FALSE, adjRMSEA = FALSE)
```

2. results using conventional multiple-group SEM approach with mean structure tested by projection method:

```{r, eval=FALSE}
test2 <- eqMI.main(model = model, 
	sample.nobs = c(78, 174), sample.cov = list(Cov1, Cov2), 
	sample.mean = list(M1, M2), meanstructure = TRUE, 
	equivalence.test = FALSE, adjRMSEA = FALSE,
	projection = TRUE)
```

3. results using equivalence testing:

```{r, eval=FALSE}
test3 <- eqMI.main(model = model, 
	sample.nobs = c(78, 174), sample.cov = list(Cov1, Cov2), 
	sample.mean = list(M1, M2), meanstructure = TRUE, 
	equivalence.test = TRUE, adjRMSEA = FALSE)
```

4. results using equivalence testing and adjusted cutoff values:

```{r, eval=FALSE}
test4 <- eqMI.main(model = model, 
	sample.nobs = c(78, 174), sample.cov = list(Cov1, Cov2), 
	sample.mean = list(M1, M2), meanstructure = TRUE, 
	equivalence.test = TRUE, adjRMSEA = TRUE)
```

5. analysis of 4 with mean structure tested by projection method:

```{r, eval=FALSE}
test5 <- eqMI.main(model = model, 
	sample.nobs = c(78, 174), sample.cov = list(Cov1, Cov2), 
	sample.mean = list(M1, M2), meanstructure = TRUE, 
	equivalence.test = TRUE, adjRMSEA = TRUE,
	projection = TRUE)
```

6. if any of the tests above evaluate only mean structure or only covariance structure, add the argument "structure = 'mean'" or "structure = 'covariance'", say test5 with only mean structure:

```{r, eval=FALSE}
test6 <- eqMI.main(model = model, structure = 'mean',
	sample.nobs = c(78, 174), sample.cov = list(Cov1, Cov2), 
	sample.mean = list(M1, M2), meanstructure = TRUE, 
	equivalence.test = TRUE, adjRMSEA = TRUE,
	projection = TRUE)
```

7. if raw data are available, say the name of the raw data is 'literacy.dat' and the variable of group membership is 'FRL', then test5 is conducted as:

```{r, eval=FALSE}
test7 <- eqMI.main(model = model, data = literacy.dat, 
	group = "FRL", meanstructure = TRUE, 
	equivalence.test = TRUE, adjRMSEA = TRUE,
	projection = TRUE)
```

8. when raw data are available and project method is used, bootstrap resampling can be used to obtain empirical p-values of the tests conducted by project method by enabling bootstrap = TRUE. 

```{r, eval=FALSE}
test8 <- eqMI.main(model = model, data = literacy.dat, 
	group = "FRL", meanstructure = TRUE, 
	equivalence.test = TRUE, adjRMSEA = TRUE,
	projection = TRUE, bootstrap = TRUE)
```

9. in any of the tests above, the users can suppress the printing of results (not recommended) though the results are still contained in test9$eqMI.stat:

```{r, eval=FALSE}
test9 <- eqMI.main(model = model, data = literacy.dat, 
	group = "FRL", meanstructure = TRUE, 
	equivalence.test = TRUE, adjRMSEA = TRUE,
	projection = TRUE, bootstrap = FALSE,
	quite = TRUE)
```

10. in any of the tests above, the users can allow partial invariance by adding 'group.partial':

```{r, eval=FALSE}
test10 <- eqMI.main(model = model, data = literacy.dat, 
	group = "FRL", meanstructure = TRUE, 
	group.partial = c("Spelling=~Real_Words", "Blending~1"),
	equivalence.test = TRUE, adjRMSEA = TRUE,
	projection = TRUE)
```

so that the loadings of 'Spelling' on 'Real_Words' and the intercept of 'Blending' are allowed to vary across groups. 


## Part 5: Help page of the eqMI.main() function

For a complete view of the help page of function eqMI.main(), please install R package printr and type ?eqMI.main in R console:

```{r, echo=FALSE}
library(printr) 
?eqMI.main
```






```{r, include=FALSE}

# For a complete view of the help page of function eqMI.main(), please install R package printr and type ?eqMI.main in R console:

#library(printr) 
#?eqMI.main

#output: pdf_document
#devtools::build_vignettes()
#R CMD Rd2pdf "~/Box Sync/MacSync/Research/Frontier/equaltestMI"
#R CMD check --as-cran equaltestMI_0.6.0.tar.gz
#https://bookdown.org/yihui/rmarkdown-cookbook/package-vignette.html
```
