Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Build Scree Plot for Configural Invariance

Description

Creates a ggplot2 scree plot comparing the PVE by FPCs for two groups.

Usage

build_scree_plot(fpca_A, fpca_B, groups)

Arguments

Value

A ggplot object.

Examples

  sim <- simulate_fmi_data(N_A = 20, N_B = 20, T_points = 30)
  g_fac <- factor(sim$group_vec)
  idx_A <- which(g_fac == levels(g_fac)[1])
  # --- FIX: Added Y= and argvals= ---
  fpca_A <- refund::fpca.sc(Y = sim$Y_mat[idx_A, ], argvals = sim$argvals, npc = 3)
  fpca_B <- refund::fpca.sc(Y = sim$Y_mat[-idx_A, ], argvals = sim$argvals, npc = 3)
  build_scree_plot(fpca_A, fpca_B, levels(g_fac))

Compare Latent Means

Description

Performs Welch's t-tests on FPC scores between groups. This function should only be run after scalar invariance is established.

Usage

compare_latent_means(fmi_results, group_vec)

Arguments

Value

A tibble summarizing the t-test results for each FPC.

Examples

  sim <- simulate_fmi_data(N_A = 20, N_B = 20, T_points = 30)
  fmi_results <- run_fmi(
    Y_mat = sim$Y_mat,
    group_vec = sim$group_vec,
    argvals = sim$argvals,
    n_perms = 9,
    progress = FALSE
  )
  # This will run only if scalar invariance passed
  if (!is.null(fmi_results$scalar) && fmi_results$scalar$passed) {
    mean_results <- compare_latent_means(fmi_results, sim$group_vec)
    print(mean_results)
  }

Determine Number of FPCs Automatically

Description

Determines the number of functional principal components (FPCs) required to meet a target Proportion of Variance Explained (PVE).

Usage

determine_npc(Y_mat, argvals, target_pve = 0.95, max_npc = 6L)

Arguments

Value

A list containing:

Examples

  sim <- simulate_fmi_data(N_A = 20, N_B = 20, T_points = 30)
  npc_info <- determine_npc(sim$Y_mat, sim$argvals)
  print(npc_info$npc)

DTI Example Data Wrapper

Description

A helper function to load and pre-process the DTI dataset from the 'refund' package for use in examples.

Usage

run_dti_example(n_perms = 499L)

Arguments

Value

Invisibly returns the FMI results list.

Examples

  # n_perms=9 is for a quick check. Use 499+ for real analysis.
  if (requireNamespace("refund", quietly = TRUE)) {
    dti_results <- run_dti_example(n_perms = 9)
  }

Run Hierarchical Functional Measurement Invariance (FMI) Tests

Description

A wrapper function that performs a sequence of permutation tests for configural, metric, scalar, and (optionally) strict invariance.

Usage

run_fmi(
  Y_mat,
  group_vec,
  argvals,
  alpha = 0.05,
  npc = NULL,
  target_pve = 0.95,
  max_npc = 6L,
  n_perms = 499L,
  strict_test = FALSE,
  progress = interactive()
)

Arguments

Value

A list containing test results for each invariance level, settings, and the pooled FPCA object.

Examples

  # Use small N and n_perms for a quick example
  sim <- simulate_fmi_data(N_A = 20, N_B = 20, T_points = 30)
  fmi_results <- run_fmi(
    Y_mat = sim$Y_mat,
    group_vec = sim$group_vec,
    argvals = sim$argvals,
    n_perms = 9, # Use 499+ for actual research
    progress = FALSE
  )
 print(fmi_results)

Berkeley Growth Example Data Wrapper

Description

A helper function to load and pre-process the Growth dataset from the 'fda' package for use in examples.

Usage

run_growth_example(n_perms = 499L)

Arguments

Value

Invisibly returns the FMI results list.

Examples

  # n_perms=9 is for a quick check. Use 499+ for real analysis.
  if (requireNamespace("fda", quietly = TRUE)) {
    growth_results <- run_growth_example(n_perms = 9)
  }

Simulate FMI Data

Description

Generates functional data for two groups with optional differences in latent means or scalar intercepts.

Usage

simulate_fmi_data(
  N_A = 50,
  N_B = 50,
  T_points = 51,
  mean_shift = 0,
  scalar_shift = 0,
  eigenvalues = c(4, 1, 0.5, 0.1),
  noise_sd = 0.5,
  seed = NULL
)

Arguments

Value

A list with Y_mat, group_vec, and argvals.

Examples

sim_data <- simulate_fmi_data(N_A = 10, N_B = 10, T_points = 20, seed = 123)
str(sim_data)

Test for Configural Invariance

Description

Permutation test to check if the cumulative PVE is equivalent across groups.

Usage

test_configural(Y_mat, group_vec, argvals, npc, n_perms, alpha, progress)

Arguments

Value

A list with passed (boolean), p_value, statistic, and plot.

Examples

  sim <- simulate_fmi_data(N_A = 20, N_B = 20, T_points = 30)
  res <- test_configural(sim$Y_mat, sim$group_vec, sim$argvals,
                         npc = 3, n_perms = 9, alpha = 0.05, progress = FALSE)
  print(res$p_value)

Test for Metric Invariance

Description

Permutation test to check if the eigenfunctions are equivalent across groups.

Usage

test_metric(Y_mat, group_vec, argvals, npc, n_perms, alpha, progress)

Arguments

Value

A list with passed (boolean), p_value, and statistic.

Examples

  sim <- simulate_fmi_data(N_A = 20, N_B = 20, T_points = 30)
  res <- test_metric(sim$Y_mat, sim$group_vec, sim$argvals,
                     npc = 3, n_perms = 9, alpha = 0.05, progress = FALSE)
  print(res$p_value)

Test for Scalar Invariance

Description

Permutation test to check if the mean functions (intercepts) are equivalent across groups, after accounting for latent factors.

Usage

test_scalar(Y_mat, group_vec, argvals, pooled_fpca, n_perms, alpha, progress)

Arguments

Value

A list with passed (boolean), p_value, and statistic.

Examples

  sim <- simulate_fmi_data(N_A = 20, N_B = 20, T_points = 30)
  npc_info <- determine_npc(sim$Y_mat, sim$argvals, max_npc = 3)
  res <- test_scalar(sim$Y_mat, sim$group_vec, sim$argvals,
                     pooled_fpca = npc_info$pooled_fpca,
                     n_perms = 9, alpha = 0.05, progress = FALSE)
  print(res$p_value)

Test for Strict Invariance

Description

Permutation test to check if the residual error variances are equivalent across groups.

Usage

test_strict(Y_mat, group_vec, argvals, npc, n_perms, alpha, progress)

Arguments

Value

A list with passed (boolean), p_value, and statistic.

Examples

  sim <- simulate_fmi_data(N_A = 20, N_B = 20, T_points = 30)
  res <- test_strict(sim$Y_mat, sim$group_vec, sim$argvals,
                     npc = 3, n_perms = 9, alpha = 0.05, progress = FALSE)
  print(res$p_value)