This function performs Sparse ICA on group-level fMRI data. It processes BIDS-formatted fMRI datasets, performs PCA to reduce dimensionality, selects a tuning parameter nu (optionally using a BIC-like criterion), and executes Sparse ICA to estimate independent components.
group_sparseICA(
bids_path,
subj_list = NULL,
nu = "BIC",
n.comp = 30,
method = "C",
ncore = 1,
npc = 85,
iter_std = 5,
brainstructures = c("left", "right"),
restarts = 40,
positive_skewness = TRUE,
use_irlba = TRUE,
eps = 1e-06,
maxit = 500,
BIC_plot = TRUE,
nu_list = seq(0.1, 4, 0.05),
verbose = TRUE,
BIC_verbose = FALSE,
converge_plot = FALSE
)A list containing the results of the group Sparse ICA analysis, including:
loglikThe minimal log-likelihood value among the random initializations.
estSA numeric matrix of estimated sparse independent components with dimensions P x Q.
estUThe estimated U matrix with dimensions Q x Q.
whitenerThe whitener matrix used for data whitening.
convergeThe trace of convergence for the U matrix.
best_nuThe selected nu value (if nu = "BIC").
BICA numeric vector of BIC values for each nu candidate (if nu = "BIC").
nu_listThe list of nu candidates used in the BIC-based selection (if nu = "BIC").
A character string specifying the root directory of the BIDS-formatted dataset.
A named list where each element corresponds to a subject and contains vectors of fMRI file names. If NULL, the subject list is generated automatically using create_group_list. Default is NULL.
A numeric value for the tuning parameter, or "BIC" to select nu using a BIC-like criterion. Default is "BIC".
An integer specifying the number of components to estimate. Default is 30.
A character string specifying the computation method for Sparse ICA. Options are "C" (default) for C-based computation or "R" for R-based computation.
An integer specifying the number of cores to use for parallel processing. Default is 1.
An integer specifying the number of components to retain during subject-level PCA. Default is 85.
An integer specifying the number of iterative standardization steps to apply to fMRI data. Default is 5.
A character vector specifying the brain structures to include in the analysis. Options are "left" (left cortex), "right" (right cortex), and/or "subcortical" (subcortex and cerebellum). Can also be "all" (obtain all three brain structures). Default is c("left", "right").
An integer specifying the number of random initializations for Sparse ICA. Default is 40.
A logical value indicating whether to enforce positive skewness on the estimated components. Default is TRUE.
A logical value indicating whether to use the irlba method for fast truncated Singular Value Decomposition (SVD) during whitening. This can improve memory efficiency for intermediate datasets. Default is TRUE.
A numeric value specifying the convergence threshold. Default is 1e-6.
An integer specifying the maximum number of iterations for Sparse ICA. Default is 500.
A logical value indicating whether to generate a plot of BIC values for different nu candidates when selecting nu. Default is TRUE.
A numeric vector specifying candidate values for nu when selecting it using a BIC-like criterion. Default is seq(0.1, 4, 0.05).
A logical value indicating whether to print progress messages. Default is TRUE.
A logical value indicating whether to print detailed messages during the BIC-based selection of nu. Default is FALSE.
A logical value indicating whether to generate a plot showing the convergence trace during Sparse ICA. Default is FALSE.
The function operates in four main steps:
If subj_list is not provided, it creates a list of subject-specific fMRI files using create_group_list.
Performs subject-level PCA using gen_groupPC to reduce data dimensionality.
Selects the tuning parameter nu using a BIC-like criterion (if nu = "BIC") or uses the provided nu.
Executes Sparse ICA on the group-level PCs to estimate independent components.
create_group_list, gen_groupPC, BIC_sparseICA, sparseICA