group_sparseICA {SparseICA} | R Documentation |
Perform Group Sparse Independent Component Analysis (Sparse ICA)
Description
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.
Usage
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
)
Arguments
bids_path |
A character string specifying the root directory of the BIDS-formatted dataset. |
subj_list |
A named list where each element corresponds to a subject and contains vectors of fMRI file names. If |
nu |
A numeric value for the tuning parameter, or |
n.comp |
An integer specifying the number of components to estimate. Default is 30. |
method |
A character string specifying the computation method for Sparse ICA. Options are |
ncore |
An integer specifying the number of cores to use for parallel processing. Default is 1. |
npc |
An integer specifying the number of components to retain during subject-level PCA. Default is 85. |
iter_std |
An integer specifying the number of iterative standardization steps to apply to fMRI data. Default is 5. |
brainstructures |
A character vector specifying the brain structures to include in the analysis. Options are |
restarts |
An integer specifying the number of random initializations for Sparse ICA. Default is 40. |
positive_skewness |
A logical value indicating whether to enforce positive skewness on the estimated components. Default is |
use_irlba |
A logical value indicating whether to use the |
eps |
A numeric value specifying the convergence threshold. Default is |
maxit |
An integer specifying the maximum number of iterations for Sparse ICA. Default is 500. |
BIC_plot |
A logical value indicating whether to generate a plot of BIC values for different |
nu_list |
A numeric vector specifying candidate values for |
verbose |
A logical value indicating whether to print progress messages. Default is |
BIC_verbose |
A logical value indicating whether to print detailed messages during the BIC-based selection of |
converge_plot |
A logical value indicating whether to generate a plot showing the convergence trace during Sparse ICA. Default is |
Details
The function operates in four main steps:
If
subj_list
is not provided, it creates a list of subject-specific fMRI files usingcreate_group_list
.Performs subject-level PCA using
gen_groupPC
to reduce data dimensionality.Selects the tuning parameter
nu
using a BIC-like criterion (ifnu = "BIC"
) or uses the providednu
.Executes Sparse ICA on the group-level PCs to estimate independent components.
Value
A list containing the results of the group Sparse ICA analysis, including:
loglik
The minimal log-likelihood value among the random initializations.
estS
A numeric matrix of estimated sparse independent components with dimensions P x Q.
estU
The estimated U matrix with dimensions Q x Q.
whitener
The whitener matrix used for data whitening.
converge
The trace of convergence for the U matrix.
best_nu
The selected
nu
value (ifnu = "BIC"
).BIC
A numeric vector of BIC values for each
nu
candidate (ifnu = "BIC"
).nu_list
The list of
nu
candidates used in the BIC-based selection (ifnu = "BIC"
).
See Also
create_group_list
, gen_groupPC
, BIC_sparseICA
, sparseICA