Package 'matrixStrucTest' reference manual

Title:	Tests of Matrix Structure for Construct Validation
Description:	Tests for block-diagonal structure in symmetric matrices (e.g. correlation matrices) under the null hypothesis of exchangeable off-diagonal elements. As described in Segal et al. (2019), these tests can be useful for construct validation either by themselves or as a complement to confirmatory factor analysis. Monte Carlo methods are used to approximate the permutation p-value with Hubert's Gamma (Hubert, 1976) and a t-statistic. This package also implements the chi-squared statistic described by Steiger (1980). Please see Segal, et al. (2019) <doi:10.1007/s11336-018-9647-4> for more information.
Authors:	Brian D. Segal [aut, cre]
Maintainer:	Brian D. Segal <[email protected]>
License:	GPL (>= 3)
Version:	1.0.0
Built:	2024-08-22 03:46:43 UTC
Source:	https://github.com/bdsegal/matrixstructest

Big Five personality questionnaire

Description

A dataset containing answers to a Big Five Personality Test conducted by http://personality-testing.info. These data were collected (c. 2012) through an interactive online personality test. The test was constructed with items from the International Personality Item Pool. Participants were informed that their responses would be recorded and used for research at the beginning of the test and asked to confirm their consent at the end of the test. The items were rated on a five point scale where 1=Disagree, 3=Neutral, 5=Agree. All were presented on one page in the order E1, N1, A1, C1, O1, E2,...

Usage

big5
big5

Format

A data frame with 19,719 rows of 57 variables:

race: 1=Mixed Race, 2=Arctic (Siberian, Eskimo), 3=Caucasian (European), 4=Caucasian (Indian), 5=Caucasian (Middle East), 6=Caucasian (North African, Other), 7=Indigenous Australian, 8=Native American, 9=North East Asian (Mongol, Tibetan, Korean Japanese, etc), 10=Pacific (Polynesian, Micronesian, etc), 11=South East Asian (Chinese, Thai, Malay, Filipino, etc), 12=West African, Bushmen, Ethiopian, 13=Other
age: Entered as text (individuals reporting age < 13 were not recorded)
engnat: Response to "is English your native language?". 1=yes, 2=no
gender: 1=Male, 2=Female, 3=Other
hand: "What hand do you use to write with?". 1=Right, 2=Left, 3=Both
country: The participant's technical location. ISO country code
source: How the participant came to the test. Based on HTTP Referer. 1=from another page on the test website, 2=from google, 3=from facebook, 4=from any url with ".edu" in its domain name, 6=other source, or HTTP Referer not provided
E1: I am the life of the party.
E2: I don't talk a lot.
E3: I feel comfortable around people.
E4: I keep in the background.
E5: I start conversations.
E6: I have little to say.
E7: I talk to a lot of different people at parties.
E8: I don't like to draw attention to myself.
E9: I don't mind being the center of attention.
E10: I am quiet around strangers.
N1: I get stressed out easily.
N2: I am relaxed most of the time.
N3: I worry about things.
N4: I seldom feel blue.
N5: I am easily disturbed.
N6: I get upset easily.
N7: I change my mood a lot.
N8: I have frequent mood swings.
N9: I get irritated easily.
N10: I often feel blue.
A1: I feel little concern for others.
A2: I am interested in people.
A3: I insult people.
A4: I sympathize with others' feelings.
A5: I am not interested in other people's problems.
A6: I have a soft heart.
A7: I am not really interested in others.
A8: I take time out for others.
A9: I feel others' emotions.
A10: I make people feel at ease.
C1: I am always prepared.
C2: I leave my belongings around.
C3: I pay attention to details.
C4: I make a mess of things.
C5: I get chores done right away.
C6: I often forget to put things back in their proper place.
C7: I like order.
C8: I shirk my duties.
C9: I follow a schedule.
C10: I am exacting in my work.
O1: I have a rich vocabulary.
O2: I have difficulty understanding abstract ideas.
O3: I have a vivid imagination.
O4: I am not interested in abstract ideas.
O5: I have excellent ideas.
O6: I do not have a good imagination.
O7: I am quick to understand things.
O8: I use difficult words.
O9: I spend time reflecting on things.
O10: I am full of ideas.

Details

This dataset is for demonstration purposes only. Please see http://personality-testing.info/privacypolicy.html and http://personality-testing.info/about for more information.

Source

http://personality-testing.info/_rawdata/

Sub-routine to create Delta matrix

Description

This sub-routine outputs 1 if i and j are in at least one group together, and 0 otherwise, and is called by matrixStrucTest and prepBoxPlots.

Usage

deltaSub(i, j, group_list)
deltaSub(i, j, group_list)

Arguments

`i`	First index
`j`	Second index
`group_list`	List of indices for each block

Convert character string in lavaan syntax into a list of indices

Description

This sub-routine is called by matrixStrucTest and prepBoxPlots.

Usage

makeGroupList(groups, A)
makeGroupList(groups, A)

Arguments

`groups`	Character string in lavaan syntax specifying groups
`A`	A Distance or similarity matrix. Must have column names

Value

group_list List of column indices of A corresponding to each group

Permutation p-values for Gamma and t-statistics

Description

This function computes permutation p-values for Hubert's Gamma and t-statistics for both overall and block-specific tests.

Usage

matrixStrucTest(A, group_list = NULL, groups = NULL, B = 1000,
  absolute = TRUE)
matrixStrucTest(A, group_list = NULL, groups = NULL, B = 1000,
  absolute = TRUE)

Arguments

`A`	Distance or similarity matrix, e.g. correlation
`group_list`	List of column indices of A for each group. Either `groups` or `group_list` but not both must be supplied.
`groups`	CFA model in lavaan syntax. Either `groups` or `group_list` but not both must be supplied.
`B`	Number of Monte Carlo resamples (defaults to B=1000)
`absolute`	Use the absolute values of A (defaults to TRUE)

Value

pt_overall_one_sided: Overall one-sided p-value using t statistic

pt_overall_two_sided: Overall two-sided p-value using t statistic

pt_multi_one_sided: Block-specific one-sided p-values using t statistic

pt_multi_two_sided: Block-specific two-sided p-values using t statistic

t0 Observed overall: t statistic

t0k: Observed block-specific t statistic

t_overall: Vector of overall t statistics from permuted A

t_max_one_sided: Vector of max t statistics from permuted A (one-sided)

t_max_two_sided: Vector of max t statistics from permuted A (two-sided)

pG_overall_one_sided: Overall one-sided p-value using Hubert's Gamma

pG_overall_two_sided: Overall two-sided p-value using Hubert's Gamma

pG_multi_one_sided: Block-specific one-sided p-values using Hubert's Gamma

pG_multi_two_sided: Block-specific two-sided p-values using Hubert's Gamma

Gamma0: Observed overall Hubert's Gamma

Gamma0k: Observed block-specific Hubert's Gamma

Gamma_overall: Vector of Hubert's Gamma statistics from permuted A

Gamma_max_one_sided: Vector of max Hubert's Gamma statistics from permuted A (one-sided)

Gamma_max_two_sided: Vector of max Hubert's Gamma statistics from permuted A (two-sided)

B: number of Monte Carlo resamples

group_list: List of column/row indices corresponding to each group

Examples

# example for matrixStrucTest package
library(matrixStrucTest)
data("big5")

# get column numbers for questionnaire items
items <- grep("[0-9]", colnames(big5))

# compute Spearman's correlation matrix
A <- cor(big5[, items], use = "complete.obs", method = "spearman")

# specify the groups
groups <- "extrovert ~ E1 + E2 + E3 + E4 + E5 + E6 + E7 + E8 + E9 + E10
           neurotic ~ N1 + N2 + N3 + N4 + N5 + N6 + N7 + N8 + N9 + N10
           agreeable ~ A1 + A2 + A3 + A4 + A5 + A6 + A7 + A8 + A9 + A10
           conscientious ~ C1 + C2 + C3 + C4 + C5 + C6 + C7 + C8 + C9 + C10
           open ~ O1 + O2 + O3 + O4 + O5 + O6 + O7 + O8 + O9 + O10"

# compute permutation p-values
# Note: Using small B for fast checking on CRAN. Set B >= 1000 in practice.
result <- matrixStrucTest(A = A, groups = groups, B = 100, absolute = TRUE)

# Note: two-sided p-values from Hubert's Gamma printed by default
#       other results available by directing accessing them from the
#       returned object
result

# Alternative approach for specifying the groups as a list of column/row indices
extrovert <- grep("E", colnames(A))
neurotic <- grep("N", colnames(A))
agreeable <- grep("A", colnames(A))
conscientious <- grep("C", colnames(A))
open <- grep("O", colnames(A))

# put blocks/groups in list
group_list <- list(extrovert = extrovert, 
                   neurotic = neurotic, 
                   agreeable = agreeable, 
                   conscientious = conscientious,
                   open = open)

# Note: Using small B for fast checking on CRAN. Set B >= 1000 in practice.
result <- matrixStrucTest(A = A, group_list = group_list, B = 100, absolute = TRUE)

# Note: two-sided p-values from Hubert's Gamma printed by default
#       other results available by directing accessing them from the
#       returned object
result

# Visualize groups
library(ggplot2)
library(reshape2)

ord <- unlist(result$group_list)
diag(A) <- NA # remove diagonals from color scale
Am <- melt(A[ord, ord])
names(Am) <- c("x", "y", "value")
Am$y <- factor(Am$y, levels = rev(levels(Am$y)))

ggplot(aes(x = x, y = y, fill = abs(value)), data = Am)+
  geom_tile()+
  theme_bw(18)+
  scale_fill_gradient2(space="Lab", name="abs(Cor)", lim = c(0, 1))+
  labs(x = "", y = "")+
  theme(axis.text.x = element_text(angle = 90, vjust = .35,hjust=1))
# example for matrixStrucTest package
library(matrixStrucTest)
data("big5")

# get column numbers for questionnaire items
items <- grep("[0-9]", colnames(big5))

# compute Spearman's correlation matrix
A <- cor(big5[, items], use = "complete.obs", method = "spearman")

# specify the groups
groups <- "extrovert ~ E1 + E2 + E3 + E4 + E5 + E6 + E7 + E8 + E9 + E10
           neurotic ~ N1 + N2 + N3 + N4 + N5 + N6 + N7 + N8 + N9 + N10
           agreeable ~ A1 + A2 + A3 + A4 + A5 + A6 + A7 + A8 + A9 + A10
           conscientious ~ C1 + C2 + C3 + C4 + C5 + C6 + C7 + C8 + C9 + C10
           open ~ O1 + O2 + O3 + O4 + O5 + O6 + O7 + O8 + O9 + O10"

# compute permutation p-values
# Note: Using small B for fast checking on CRAN. Set B >= 1000 in practice.
result <- matrixStrucTest(A = A, groups = groups, B = 100, absolute = TRUE)

# Note: two-sided p-values from Hubert's Gamma printed by default
#       other results available by directing accessing them from the
#       returned object
result

# Alternative approach for specifying the groups as a list of column/row indices
extrovert <- grep("E", colnames(A))
neurotic <- grep("N", colnames(A))
agreeable <- grep("A", colnames(A))
conscientious <- grep("C", colnames(A))
open <- grep("O", colnames(A))

# put blocks/groups in list
group_list <- list(extrovert = extrovert, 
                   neurotic = neurotic, 
                   agreeable = agreeable, 
                   conscientious = conscientious,
                   open = open)

# Note: Using small B for fast checking on CRAN. Set B >= 1000 in practice.
result <- matrixStrucTest(A = A, group_list = group_list, B = 100, absolute = TRUE)

# Note: two-sided p-values from Hubert's Gamma printed by default
#       other results available by directing accessing them from the
#       returned object
result

# Visualize groups
library(ggplot2)
library(reshape2)

ord <- unlist(result$group_list)
diag(A) <- NA # remove diagonals from color scale
Am <- melt(A[ord, ord])
names(Am) <- c("x", "y", "value")
Am$y <- factor(Am$y, levels = rev(levels(Am$y)))

ggplot(aes(x = x, y = y, fill = abs(value)), data = Am)+
  geom_tile()+
  theme_bw(18)+
  scale_fill_gradient2(space="Lab", name="abs(Cor)", lim = c(0, 1))+
  labs(x = "", y = "")+
  theme(axis.text.x = element_text(angle = 90, vjust = .35,hjust=1))

Compute Gamma and t-statistics for a single permutation

Description

This sub-routine is called by matrixStrucTest and prepBoxPlots.

Usage

matrixStrucTestSub(A, group_list_ord, Delta, multi_group_ind, A_upper_ind,
  K)
matrixStrucTestSub(A, group_list_ord, Delta, multi_group_ind, A_upper_ind,
  K)

Arguments

`A`	Distance or similarity matrix, e.g. correlation
`group_list_ord`	List of groupings for ordered matrix A
`Delta`	Delta matrix
`multi_group_ind`	List of indicator matrices for membership in block k test
`A_upper_ind`	indicator matrix for upper triangular elements
`K`	Total number of hypothesized blocks

Value

Gamma_overall: Overall Hubert's Gamma

Gamma_multi: Block-specific Hubert's Gamma

t_overall: Overall t-statistic (unequal variance)

t_multi: Block-specific t-statistics

Ak_list: List of values in A used for each block-specific test

Deltak_list: List of values in Delta used for each block-specific test

A_upper: Upper triangular elements of A (used for box plot function)

Delta_upper: Upper triangular elements of Delta (used for box plot function)

Sub-routine to create Delta matrix for block-specific tests

Description

This sub-routine outputs TRUE if either i or j are in group, FALSE otherwise, and is called by matrixStrucTest and prepBoxPlots.

Usage

multiSub(i, j, group)
multiSub(i, j, group)

Arguments

`i`	First index
`j`	Second index
`group`	Indices for items in group

Prepare data for box plots

Description

This function prepares the data for making box plots.

Usage

prepBoxPlots(A, groups = NULL, group_list = NULL, absolute = TRUE)
prepBoxPlots(A, groups = NULL, group_list = NULL, absolute = TRUE)

Arguments

`A`	Distance or similarity matrix, e.g. correlation
`groups`	CFA model in lavaan syntax. Either `groups` or `group_list` but not both must be supplied.
`group_list`	List of groupings. Either `groups` or `group_list` but not both must be supplied.
`absolute`	Use the absolute values of A (defaults to TRUE)

Value

multi: data frame for making box plots for block-specific tests

overall: data frame for making box plots for overall test

Examples

library(matrixStrucTest)
library(ggplot2)

data("big5")

# get column numbers for questionnaire items
items <- grep("[0-9]", colnames(big5))

# compute Spearman's correlation matrix
A <- cor(big5[, items], use = "complete.obs", method = "spearman")

groups <- "extrovert ~ E1 + E2 + E3 + E4 + E5 + E6 + E7 + E8 + E9 + E10
           neurotic ~ N1 + N2 + N3 + N4 + N5 + N6 + N7 + N8 + N9 + N10
           agreeable ~ A1 + A2 + A3 + A4 + A5 + A6 + A7 + A8 + A9 + A10
           conscientious ~ C1 + C2 + C3 + C4 + C5 + C6 + C7 + C8 + C9 + C10
           open ~ O1 + O2 + O3 + O4 + O5 + O6 + O7 + O8 + O9 + O10"

# Make box plots contrasting within and between group correlations
box <- prepBoxPlots(A = A, groups = groups, absolute = TRUE)

ggplot(aes(x = as.factor(delta), y = a), data = box$overall)+
  geom_boxplot()+
  theme_bw(22)+
  labs(x = expression(Delta), y="|a|")

dev.new(width = 12, height = 5)
ggplot(aes(x = as.factor(delta), y = a), data = box$multi)+
  geom_boxplot()+
  facet_grid(~block)+
  theme_bw(22)+
labs(x = expression(Delta), y = "|a|")
library(matrixStrucTest)
library(ggplot2)

data("big5")

# get column numbers for questionnaire items
items <- grep("[0-9]", colnames(big5))

# compute Spearman's correlation matrix
A <- cor(big5[, items], use = "complete.obs", method = "spearman")

groups <- "extrovert ~ E1 + E2 + E3 + E4 + E5 + E6 + E7 + E8 + E9 + E10
           neurotic ~ N1 + N2 + N3 + N4 + N5 + N6 + N7 + N8 + N9 + N10
           agreeable ~ A1 + A2 + A3 + A4 + A5 + A6 + A7 + A8 + A9 + A10
           conscientious ~ C1 + C2 + C3 + C4 + C5 + C6 + C7 + C8 + C9 + C10
           open ~ O1 + O2 + O3 + O4 + O5 + O6 + O7 + O8 + O9 + O10"

# Make box plots contrasting within and between group correlations
box <- prepBoxPlots(A = A, groups = groups, absolute = TRUE)

ggplot(aes(x = as.factor(delta), y = a), data = box$overall)+
  geom_boxplot()+
  theme_bw(22)+
  labs(x = expression(Delta), y="|a|")

dev.new(width = 12, height = 5)
ggplot(aes(x = as.factor(delta), y = a), data = box$multi)+
  geom_boxplot()+
  facet_grid(~block)+
  theme_bw(22)+
labs(x = expression(Delta), y = "|a|")

Print results from `matrixStrucTest`

Description

This function prints results from an object returned by matrixStrucTest.

Usage

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

Arguments

`x`	Output from matrixStrucTest
`...`	Further arguments passed to print

Sub-routine to compute OLS estimates of covariance between correlations

Description

This sub-routine is called by X2fun.

Usage

sigmaRhoFun(j, k, h, m, A)
sigmaRhoFun(j, k, h, m, A)

Arguments

`j`	First index
`k`	Second index
`h`	Third index
`m`	Fourth index
`A`	Correlation matrix

Sub-routine to get covariance of z-transformed variables

Description

This sub-routine is called by X2fun.

Usage

sigmaZFun(s, t, index, A, Sigma)
sigmaZFun(s, t, index, A, Sigma)

Arguments

`s`	First index
`t`	Second index
`index`	Matrix with two columns with index pairs given by rows
`A`	Correlation matrix
`Sigma`	Variance-covariances of correlation matrix A

Goodness-of-fit chi-squared statistic described by Steiger (1980).

Description

This function computed the goodness-of-fit chi-squared statistic described by Steiger (1980). Reference: Steiger, J. H. (1980). Tests for comparing elements of a correlation matrix. Psychological Bulletin, 87(2) 245-251.

Usage

X2Fun(data, group_list, corMethod = "spearman")
X2Fun(data, group_list, corMethod = "spearman")

Arguments

`data`	Data frame
`group_list`	List of column indices of A for each group
`corMethod`	Type of correlations; passed to cor()

Package 'matrixStrucTest'

Help Index

Big Five personality questionnaire

Description

Usage

Format

Details

Source

Sub-routine to create Delta matrix

Description

Usage

Arguments

Convert character string in lavaan syntax into a list of indices

Description

Usage

Arguments

Value

Permutation p-values for Gamma and t-statistics

Description

Usage

Arguments

Value

Examples

Compute Gamma and t-statistics for a single permutation

Description

Usage

Arguments

Value

Sub-routine to create Delta matrix for block-specific tests

Description

Usage

Arguments

Prepare data for box plots

Description

Usage

Arguments

Value

Examples

Print results from matrixStrucTest

Description

Usage

Arguments

Sub-routine to compute OLS estimates of covariance between correlations

Description

Usage

Arguments

Sub-routine to get covariance of z-transformed variables

Description

Usage

Arguments

Goodness-of-fit chi-squared statistic described by Steiger (1980).

Description

Usage

Arguments

Print results from `matrixStrucTest`