GPvam (version 3.2-0)

bias.test.custom: Permutation Tests for Fixed Effects Bias Assessment

Description

Performs permutation tests on fixed effects within a linear mixed model to assess the bias of fixed effect parameters or contrasts. The function allows for both standard basis vectors and custom vectors to define the effects being tested. See Karl and Zimmerman (2021) <doi:10.1016/j.jspi.2020.06.004>.

Usage

bias.test.custom(result, 
                 k_vectors = NULL, 
                 n_perms = 1e5)

Value

A list containing:

permutation_results

A data frame with the following columns:

Fixed_Effect

Name of the fixed effect or custom contrast tested.

Nu_Prime_Eta

The observed value of \(\nu' \hat{\eta}\).

Permutation_P_Value

Permutation p-value for the test of the fixed effect bias.

plot_list

A list of ggplot2 objects for the permutation histograms.

Arguments

result

An object containing GPvam results, including the fixed effects matrix (X), random effects design matrix (Z), inverse variance matrix (vinv), estimated random effects (eta.hat), variance components matrix (G), number of teachers per group (num.teach), and persistence type (persistence). The object must contain the following components:

X

Fixed effects matrix.

Z

Random effects design matrix.

vinv

Inverse variance matrix.

eta.hat

Estimated random effects.

G

Variance components matrix for random effects.

num.teach

Vector indicating the number of teachers (random effects) per group.

persistence

Persistence type, must be either "CP" or "VP" or "ZP".

k_vectors

(Optional) A list of numeric vectors specifying custom \(k\) vectors for combined fixed effects. Each vector should be the same length as the number of fixed effects in the model. If NULL, the function generates standard basis vectors (one-hot vectors) to perform permutation tests for each fixed effect individually.

n_perms

(Optional) The number of permutations to perform for each \(k\) vector. A higher number of permutations increases the accuracy of the p-value estimates but also increases computation time. Default is 1e5.

Examples

if (FALSE) {
# Assuming 'result' is your GPvam object

# Perform bias test for all fixed effects
test_results <- bias.test.custom(result)

# Perform bias test including a custom contrast
k_custom <- c(1, -1, 0, 0)  # Contrast between first and second fixed effects
test_results <- bias.test.custom(result, k_vectors = list(k_custom))
}