group_sparseICA: Perform Group Sparse Independent Component Analysis (Sparse...

In SparseICA: Sparse Independent Component Analysis

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 NULL, the subject list is generated automatically using create_group_list. Default is NULL.
nu	A numeric value for the tuning parameter, or "BIC" to select nu using a BIC-like criterion. Default is "BIC".
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 "C" (default) for C-based computation or "R" for R-based computation.
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 "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").
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 TRUE.
use_irlba	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.
eps	A numeric value specifying the convergence threshold. Default is 1e-6.
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 candidates when selecting nu. Default is TRUE.
nu_list	A numeric vector specifying candidate values for nu when selecting it using a BIC-like criterion. Default is seq(0.1, 4, 0.05).
verbose	A logical value indicating whether to print progress messages. Default is TRUE.
BIC_verbose	A logical value indicating whether to print detailed messages during the BIC-based selection of nu. Default is FALSE.
converge_plot	A logical value indicating whether to generate a plot showing the convergence trace during Sparse ICA. Default is FALSE.

Details

The function operates in four main steps:

1. If subj_list is not provided, it creates a list of subject-specific fMRI files using create_group_list.

2. Performs subject-level PCA using gen_groupPC to reduce data dimensionality.

3. Selects the tuning parameter nu using a BIC-like criterion (if nu = "BIC") or uses the provided nu.

4. 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 (if nu = "BIC").

BIC

A numeric vector of BIC values for each nu candidate (if nu = "BIC").

nu_list

The list of nu candidates used in the BIC-based selection (if nu = "BIC").

See Also

create_group_list, gen_groupPC, BIC_sparseICA, sparseICA

SparseICA documentation built on April 12, 2025, 1:50 a.m.