FMRIGroupDataset: R6 Class for Managing Multi-Subject fMRI Datasets

FMRIGroupDatasetR Documentation

R6 Class for Managing Multi-Subject fMRI Datasets

Description

The FMRIGroupDataset class provides a container and interface for managing multiple fMRI datasets, typically representing different subjects in a study. It supports operations like subsetting, applying functions across subjects, and accessing individual subject data.

The class is designed to work with the BIDS (Brain Imaging Data Structure) format and integrates with the bidser package for BIDS data handling.

Key Features

  • Manages multiple fMRI datasets with consistent interface

  • Supports subject-wise operations and filtering

  • Integrates with BIDS format and bidser package

  • Provides method chaining for complex operations

Class Structure

The class maintains:

  • A list of individual fMRI datasets

  • Subject IDs corresponding to each dataset

  • Optional task and run information

  • Methods for data access and manipulation

Public fields

datasets

List of individual fMRI datasets Each element should be an object inheriting from class "fmri_dataset"

subject_ids

Vector of subject IDs Character vector of BIDS-compliant subject identifiers (e.g., "sub-01")

tasks

Vector of task names Optional character vector of task names present in the datasets

runs

Vector of run IDs Optional character vector of run identifiers

Methods

Public methods


Method new()

Create a new FMRIGroupDataset object

Usage
FMRIGroupDataset$new(datasets, subject_ids, tasks = NULL, runs = NULL)
Arguments
datasets

List of individual fmri_dataset objects

subject_ids

Vector of subject IDs corresponding to datasets

tasks

Optional vector of task names

runs

Optional vector of run IDs

Returns

A new FMRIGroupDataset object

Examples
\dontrun{
# Basic creation
group_ds <- FMRIGroupDataset$new(
  datasets = list(ds1, ds2),
  subject_ids = c("sub-01", "sub-02")
)

# With task and run information
group_ds <- FMRIGroupDataset$new(
  datasets = list(ds1, ds2),
  subject_ids = c("sub-01", "sub-02"),
  tasks = c("rest", "task"),
  runs = c("run-01", "run-02")
)
}

Method get_subject()

Retrieve dataset for a specific subject

Usage
FMRIGroupDataset$get_subject(subject_id)
Arguments
subject_id

Character string specifying the subject ID

Returns

The fmri_dataset object for the specified subject

Examples
\dontrun{
# Get single subject's dataset
sub1_ds <- group_ds$get_subject("sub-01")

# Use in pipeline
sub1_ds %>% 
  get_data() %>%
  process_data()
}

Method get_tasks()

Get all unique tasks across datasets

Usage
FMRIGroupDataset$get_tasks()
Details

Returns explicitly set tasks if available, otherwise discovers unique tasks across all datasets

Returns

Character vector of task names


Method get_runs()

Get all unique runs across datasets

Usage
FMRIGroupDataset$get_runs()
Details

Returns explicitly set runs if available, otherwise discovers unique runs across all datasets

Returns

Character vector of run IDs


Method apply()

Apply a function to each dataset

Usage
FMRIGroupDataset$apply(fun, ...)
Arguments
fun

Function to apply to each dataset

...

Additional arguments passed to fun

Details

The function fun should accept at least two arguments:

  • dataset: The individual fmri_dataset object

  • subject_id: The ID of the current subject

Returns

List of results from applying fun to each dataset

Examples
\dontrun{
# Simple mean calculation
means <- group_ds$apply(function(ds, subj) {
  colMeans(get_data(ds))
})

# More complex analysis
results <- group_ds$apply(function(ds, subj, threshold) {
  list(
    subject = subj,
    data = analyze_subject(ds, threshold = threshold)
  )
}, threshold = 0.05)
}

Method subset()

Create new dataset containing only specified subjects

Usage
FMRIGroupDataset$subset(subject_ids)
Arguments
subject_ids

Character vector of subject IDs to keep

Returns

A new FMRIGroupDataset containing only the specified subjects

Examples
\dontrun{
# Basic subsetting
sub_ds <- group_ds$subset(c("sub-01", "sub-02"))

# Chain operations
results <- group_ds$
  subset(c("sub-01", "sub-02"))$
  apply(analyze_subject)
}

Method print()

Print summary of group dataset

Usage
FMRIGroupDataset$print()
Returns

Invisibly returns self (for method chaining)


Method clone()

The objects of this class are cloneable with this method.

Usage
FMRIGroupDataset$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

See Also

  • fmri_dataset() for individual dataset creation

  • bidser::bids_project() for BIDS project handling

Examples

## Not run: 
# Create individual datasets
ds1 <- fmri_dataset("sub-01_task-rest_bold.nii.gz", mask="mask.nii.gz", TR=2)
ds2 <- fmri_dataset("sub-02_task-rest_bold.nii.gz", mask="mask.nii.gz", TR=2)

# Create group dataset
group_ds <- FMRIGroupDataset$new(
  datasets = list(ds1, ds2),
  subject_ids = c("sub-01", "sub-02"),
  tasks = c("rest")
)

# Get specific subject's data
sub1_data <- group_ds$get_subject("sub-01")

# Apply function to all subjects
results <- group_ds$apply(function(ds, subj) {
  # Process individual dataset
  list(
    subject = subj,
    mean_signal = colMeans(get_data(ds))
  )
})

# Subset to specific subjects
subset_ds <- group_ds$subset(c("sub-01"))

## End(Not run)


## ------------------------------------------------
## Method `FMRIGroupDataset$new`
## ------------------------------------------------

## Not run: 
# Basic creation
group_ds <- FMRIGroupDataset$new(
  datasets = list(ds1, ds2),
  subject_ids = c("sub-01", "sub-02")
)

# With task and run information
group_ds <- FMRIGroupDataset$new(
  datasets = list(ds1, ds2),
  subject_ids = c("sub-01", "sub-02"),
  tasks = c("rest", "task"),
  runs = c("run-01", "run-02")
)

## End(Not run)

## ------------------------------------------------
## Method `FMRIGroupDataset$get_subject`
## ------------------------------------------------

## Not run: 
# Get single subject's dataset
sub1_ds <- group_ds$get_subject("sub-01")

# Use in pipeline
sub1_ds %>% 
  get_data() %>%
  process_data()

## End(Not run)

## ------------------------------------------------
## Method `FMRIGroupDataset$apply`
## ------------------------------------------------

## Not run: 
# Simple mean calculation
means <- group_ds$apply(function(ds, subj) {
  colMeans(get_data(ds))
})

# More complex analysis
results <- group_ds$apply(function(ds, subj, threshold) {
  list(
    subject = subj,
    data = analyze_subject(ds, threshold = threshold)
  )
}, threshold = 0.05)

## End(Not run)

## ------------------------------------------------
## Method `FMRIGroupDataset$subset`
## ------------------------------------------------

## Not run: 
# Basic subsetting
sub_ds <- group_ds$subset(c("sub-01", "sub-02"))

# Chain operations
results <- group_ds$
  subset(c("sub-01", "sub-02"))$
  apply(analyze_subject)

## End(Not run)

bbuchsbaum/fmrireg documentation built on March 1, 2025, 11:20 a.m.