fMRIPost-AROMA on Biowulf

Quick Links

fMRIPost-AROMA is a workflow for reducing motion-related noise in fMRI data that have already been preprocessed. It uses ICA-AROMA and works with BIDS-formatted derivatives, including compatible outputs from fMRIPrep, as long as the BOLD images are in MNI152NLin6Asym space at 2 mm resolution. It replaces the ICA-AROMA workflow that was included in fMRIPrep version 23.0 and earlier.

Documentation

fMRIPost-AROMA Documentation

Important Notes

Module Name: fmripost-aroma (see the modules page for more information)

Interactive job

Interactive jobs should be used for debugging, graphics, or applications that cannot be run as ba tch jobs.

Below we use datalad on Helix to download a sample dataset, then test fmripost-aroma on an sinteractive session (user input in bold):

[user@biowulf ~]$ ssh helix.nih.gov

[user@helix ~] cd /data/$USER
[user@helix ~] mkdir -pv FMRIPOST-AROMA_TEST
[user@helix ~] cd FMRIPOST-AROMA_TEST

[user@helix ~]$ module load datalad
[+] Loading datalad  1.1.4  on helix.nih.gov 

[user@helix ~]$ datalad install \
                   https://gin.g-node.org/nipreps-data/ds000005-fmriprep
                
install(ok): FMRIPOST-AROMA_TEST/ds000005-fmriprep (dataset)
[
[user@helix ~]$ cd ds000005-fmriprep

[user@helix ~]$ datalad get -r sub-01
[INFO   ] Ensuring presence of Dataset(FMRIPOST-AROMA_TEST/ds000005-fmriprep) to get FMRIPOST-AROMA_TEST/ds000005-fmriprep/sub-01 
get(ok): sub-01/anat/sub-01_desc-brain_mask.nii.gz (file) [from origin...]               
get(ok): sub-01/anat/sub-01_desc-preproc_T1w.nii.gz (file) [from origin...]              
get(ok): sub-01/anat/sub-01_desc-ribbon_mask.nii.gz (file) [from origin...]
get(ok): sub-01/anat/sub-01_dseg.nii.gz (file) [from origin...]
get(ok): sub-01/anat/sub-01_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 (file) [from origin...]
get(ok): sub-01/anat/sub-01_from-MNI152NLin6Asym_to-T1w_mode-image_xfm.h5 (file) [from origin...]
get(ok): sub-01/anat/sub-01_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 (file) [from origin...]
get(ok): sub-01/anat/sub-01_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5 (file) [from origin...]
get(ok): sub-01/anat/sub-01_from-T1w_to-fsnative_mode-image_xfm.txt (file) [from origin...]
get(ok): sub-01/anat/sub-01_from-fsnative_to-T1w_mode-image_xfm.txt (file) [from origin...]
  [1 similar message has been suppressed; disable with datalad.ui.suppress-similar-result  [79 similar messages have been suppressed; disable with datalad.ui.suppress-similar-results=off]
get(ok): sub-01 (directory)
action summary:
get (ok: 90)

[user@helix ~]$ exit

[user@biowulf ~]$ sinteractive --mem=20g --cpus-per-task=16 --gres=lscratch:10
salloc: Pending job allocation 28020319
salloc: job 28020319 queued and waiting for resources
salloc: job 28020319 has been allocated resources
salloc: Granted job allocation 28020319
salloc: Waiting for resource configuration
salloc: Nodes cn1234 are ready for job

[user@cn1234 ~]$ cd /data/$USER/FMRIPOST-AROMA_TEST
[user@cn1234 ~]$ module load fmripost-aroma
[+] Loading fmripost-aroma  0.0.12  on cn1234 
[+] Loading singularity  4.3.7  on cn1234

[user@cn1234 ~]$ fmripost-aroma \
    ds000005-fmriprep \
    output \
    participant \
    --participant-label 01 \
    --denoising-method nonaggr \
    --nprocs 16 \
    --omp-nthreads 8 \
    --mem 16000 \
    --skip-bids-validation \
    -w /lscratch/$SLURM_JOB_ID \
    --notrack

260826-09:35:35,798 nipype.workflow IMPORTANT:
	 Running fMRIPost-AROMA version 0.0.12

         License NOTICE ##################################################
         fMRIPost-AROMA 0.0.12
         Copyright 2023 The NiPreps Developers.
         
         This product includes software developed by
         the NiPreps Community (https://nipreps.org/).
         
         Portions of this software were developed at the Department of
         Psychology at Stanford University, Stanford, CA, US.
         
         This software is also distributed as a Docker container image.
         The bootstrapping file for the image ("Dockerfile") is licensed
          under the MIT License.
         
         This software may be distributed through an add-on package called
         "Docker Wrapper" that is under the BSD 3-clause License.
         #################################################################
260826-09:35:35,873 nipype.workflow IMPORTANT:
	 Building fMRIPost-AROMA's workflow:
           * BIDS dataset path: FMRIPOST-AROMA_TEST/ds000005-fmriprep.
           * Participant list: ['01'].
           * Run identifier: 20260826-093523_0c07fdef-bb91-46aa-b4af-209b14b5532c.
           * Output spaces: None.
[...]

260826-09:46:52,395 nipype.workflow INFO:
	 [Node] Executing "conf_plot" 
260826-09:47:01,516 nipype.workflow INFO:
	 [Node] Finished "conf_plot", elapsed time 9.120486s.
260826-09:47:04,372 nipype.workflow IMPORTANT:
	 fMRIPost-AROMA finished successfully!
260826-09:47:04,373 nipype.workflow IMPORTANT:
	 Works derived from this fMRIPost-AROMA execution should include the boilerplate text found in /logs/CITATION.md.

[user@cn1234 ~]$ exit

Batch job

Most jobs should be run as batch jobs.

Create a batch input file (e.g. fmripost-aroma.sh). For example:

#!/bin/bash

module load fmripost-aroma

cd /data/$USER/FMRIPOST-AROMA_TEST

fmripost_aroma \
    ds000005-fmriprep \
    output \
    participant \
    --participant-label 01 \
    --denoising-method nonaggr \
    --nprocs 16 \
    --omp-nthreads 8 \
    --mem 16000 \
    --skip-bids-validation \
    -w /lscratch/$SLURM_JOB_ID \
    --notrack

Submit this job using the Slurm sbatch command.

sbatch --cpus-per-task=16 --mem=20g --gres=lscratch:10 fmripost-aroma.sh

Swarm of Jobs

A swarm of jobs is an easy way to submit a set of independent commands requiring identical resources.

Create a swarmfile (e.g. fmripost-aroma.swarm). For example:

fmripost-aroma \
    /data/${USER}/FMRIPOST-AROMA_TEST/ds000005-fmriprep \
    /data/${USER}/FMRIPOST-AROMA_TEST/output_aggr \
    participant \
    --participant-label 01 \
    --denoising-method aggr \
    --nprocs 16 \
    --omp-nthreads 8 \
    --mem 16000 \
    --skip_bids_validation \
    -w /lscratch/${SLURM_JOB_ID} \
    --notrack
fmripost-aroma \
    /data/${USER}/FMRIPOST-AROMA_TEST/ds000005-fmriprep \
    /data/${USER}/FMRIPOST-AROMA_TEST/output_nonaggr \
    participant \
    --participant-label 01 \
    --denoising-method nonaggr \
    --nprocs 16 \
    --omp-nthreads 8 \
    --mem 16000 \
    --skip_bids_validation \
    -w /lscratch/${SLURM_JOB_ID} \
    --notrack
fmripost-aroma \
    /data/${USER}/FMRIPOST-AROMA_TEST/ds000005-fmriprep \
    /data/${USER}/FMRIPOST-AROMA_TEST/output_orthaggr \
    participant \
    --participant-label 01 \
    --denoising-method orthaggr \
    --nprocs 16 \
    --omp-nthreads 8 \
    --mem 16000 \
    --skip_bids_validation \
    -w /lscratch/${SLURM_JOB_ID} \
    --notrack

Submit this job using the swarm command.

swarm --gres=lscratch:10 -g 20 -t 16 --module fmripost-aroma fmripost-aroma.swarm

where

`-gres=lscratch:#`	Number of Gigabytes of local disk space allocated per process (1 line in the swarm command file)
`-g #`	Number of Gigabytes of memory required for each process (1 line in the swarm command file)
`-t #`	Number of threads/CPUs required for each process (1 line in the swarm command file).
`--module fmripost-aroma`	Loads the fmripost-aroma module for each subjob in the swarm