HCP ICAFix pipeline#

Prerequisites

HCP fMRISurface

For all HCP pipeline steps please refer to Running the HCP pipeline. For an overview on how to prepare data and run the HCP preprocessing steps, see Overview of steps for running the HCP pipeline.

The ICAFIX implementation in the QuNex suite covers all steps from the HCP ICAFIX pipeline. To achieve this, three commands are implemented:

hcp_icafix

Runs the ICAFIX step of HCP Pipelines. This step attempts to auto-classify ICA components into good and bad, so that the bad components can be then removed from the 4D fMRI data. If ICAFIX step finishes successfully PostFix step will be ran automatically, to disable this set the --hcp_icafix_postfix to FALSE.
hcp_post_fix

Runs the PostFix step of HCP Pipelines. This step creates Workbench scene files that can be used to visually review the signal vs. noise classification generated by ICAFIX.
hcp_reapply_fix

Runs the ReApplyFix step of HCP Pipelines. This function executes two steps, first it applies the hand reclassifications of noise and signal components from FIX using the ReclassifyAsNoise.txt and ReclassifyAsSignal.txt input files. Next it executes the HCP Pipeline's ReApplyFix or ReApplyFixMulti.

If the --hcp_icafix_bolds parameter is not provided ICAFIX will bundle all bolds together and execute multi-run HCP ICAFIX. The concatenated file will be named fMRI_CONCAT_ALL.

Warning

If session has many bolds such processing requires a lot of computational resources.

Instead of full bold names, you can also use bold tags from the batch file. Assume that the text bellow is an excerpt from a batch.txt file:

bold1:REST1         : rfMRI_REST1_PA ...
bold2:REST1         : rfMRI_REST1_AP ...
bold1:REST2         : rfMRI_REST2_PA ...
bold2:REST2         : rfMRI_REST2_AP ...
bold4:GUESSING      : tfMRI_GUESSING_PA ...
bold5:GUESSING      : tfMRI_GUESSING_AP ...

Using this batch file one might set --hcp_icafix_bolds=REST1 to execute a single-run HCP ICAFix on rfMRI_REST1_PA and rfMRI_REST1_AP or hcp_icafix_bolds=CONCAT_REST2:REST2|CONCAT_GUESSING:GUESSING to execute two multi-runs of HCP ICAFix, one on bolds tagged with REST2 (rfMRI_REST2_PA, rfMRI_REST2_AP) and the other on bolds tagged with GUESSING (tfMRI_GUESSING_PA, tfMRI_GUESSING_AP).

The full list of command's parameters along with example calls can be found at:

Manual classification and training a FIX model#

Depending on the acquisition parameters of your data, pre-trained models (referenced in the FSL FIX documentation) may be sufficient for automatic classification, specified by the --hcp_icafix_traindata parameter. Always visually inspect the classifications using the Workbench files created by hcp_post_fix to ensure quality. If necessary, you can adjust the automatic classification by entering the corresponding component numbers that you think were mis-classified into the files ReclassifyAsSignal.txt or ReclassifyAsNoise.txt (one number per line).

If the pre-trained models do not provide satisfactory results, you have two alternatives:

Manual classification: Classify all components manually and apply the classifications using hcp_reapply. This may be appropriate for small datasets (e.g. up to 20 subjects)
Train a custom model. This is useful for larger datasets. First, you create hand_labels_noise.txt within MNINonLinear/Results/<boldname>/<boldname>.ica directory. This text file should contain a single line, a list of the bad components only, with the format [1, 4, 99, ... 140]. Use this subset to train a custom classification model with the fix command from FSL FIX as described in FSL's FIX documentation. Training on 15-20 ICA decompositions (subjects or sessions) is recommended.

Example (manual classification)#

Run ICA-FIX on the dataset.

qunex_container hcp_icafix \
    --sessionsfolder="$study/sessions" \
    --batchfile="$study/processing/batch_hcp.txt" \
    --hcp_icafix_traindata="Standard.RData" \
    --overwrite="yes" \
    --scheduler="SLURM,jobname=QC,time=12:00:00,cpus-per-task=1,mem-per-cpu=64GB,partition=e7" \
    --parsessions=40 \
    --container="$qunex_container_path"

Manually review classifications using the Workbench scene files created by hcp_post_fix in MNINonLinear/Results/<boldname>/<session_id>_<boldname>_hp<highpass>_ICA_Classification_singlescreen.scene. Note, if you haven't manually specified --hcp_icafix_bolds parameter, all bolds will be concatenated into fMRI_CONCAT_ALL.

You can also zip the scene file in order to download it and explore it with Workbench on your computer:

cd ${ResultsFolder}
for subject in <study_path>/sessions/<subject_pattern*>; do

    subject=$(basename "$subject")
    cd <study_path>/sessions/${subject}/hcp/${subject}/MNINonLinear/Results/<boldname>/

    wb_command -zip-scene-file ${subject}_<boldname>_hp<highpass>_ICA_Classification_dualscreen.scene   ${subject}_<boldname>_hp<highpass>_ICA_Classification_dualscreen   ${subject}_<boldname>_hp<highpass>_ICA_Classification_dualscreen.zip   -skip-missing
    wb_command -zip-scene-file ${subject}_<boldname>_hp<highpass>_ICA_Classification_dualscreen.scene   ${subject}_<boldname>_hp<highpass>_ICA_Classification_singlescreen   ${subject}_<boldname>_hp<highpass>_ICA_Classification_singlescreen.zip   -skip-missing
done

Adjust misclassified components by modifying ReclassifyAsSignal.txt or ReclassifyAsNoise.txt in the MNINonLinear/Results/<boldname>/<boldname>_hp<highpass>.ica directory. Add one number per line.
Apply manual reclassification to the dataset.

qunex_container hcp_reapply_fix \
    --sessionsfolder="$study/sessions" \
    --batchfile="$study/processing/batch_hcp.txt" \
    --container="$qunex_container_path"

Example (training a custom model)#

Run ICA-FIX on the dataset.

qunex_container hcp_icafix \
    --sessionsfolder="$study/sessions" \
    --batchfile="$study/processing/batch_hcp.txt" \
    --hcp_icafix_traindata="Standard.RData" \
    --overwrite="yes" \
    --scheduler="SLURM,jobname=QC,time=12:00:00,cpus-per-task=1,mem-per-cpu=64GB,partition=e7" \
    --parsessions=40 \
    --container="$qunex_container_path"

Manually inspect classifications using the Workbench files (see point #2 above) and create hand_labels_noise.txt files inside MNINonLinear/Results/<boldname>/<boldname>_hp<highpass>.ica for a subset of subjects. hand_labels_noise.txt files should look like this:

[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ..., 267, 268, 269, 270, 271, 272]

Train a new FIX model using the fix command:

fix -t <model_name> -l <mel1.ica> <mel2.ica> <mel3.ica> ...

-l parameter will apply leave-one out cross-validation to the results.

If fix is not installed on your system, you can run it inside the container with:

singularity run --cleanenv ${CONTAINER}
source /opt/qunex/env/qunex_environment.sh

Example:

fix -t mblab_s15_TR25 -l \
/data/studies/fMRI/ICA_model/sessions/OP109/hcp/OP109/MNINonLinear/Results/fMRI_CONCAT_ALL/fMRI_CONCAT_ALL_hp0.ica \
/data/studies/fMRI/ICA_model/sessions/OP110/hcp/OP110/MNINonLinear/Results/fMRI_CONCAT_ALL/fMRI_CONCAT_ALL_hp0.ica \
...
/data/studies/fMRI/ICA_model/sessions/OP140/hcp/OP140/MNINonLinear/Results/fMRI_CONCAT_ALL/fMRI_CONCAT_ALL_hp0.ica \
/data/studies/fMRI/ICA_model/sessions/OP140/hcp/OP150/MNINonLinear/Results/fMRI_CONCAT_ALL/fMRI_CONCAT_ALL_hp0.ica

The output files will include:

<model_name>.pyfix_model - The trained FIX model.
<model_name>_LOO_results - Leave-one-out cross-validation results.
<model_name>.file_table - Index of files used for training.

Inspect <model_name>_LOO_results file to assess the quality of the model and to determine the optimal threshould.

Run hcp_icafix again using the new model:

qunex_container hcp_icafix \
    --sessionsfolder="$study/sessions" \
    --batchfile="$study/processing/batch_hcp.txt" \
    --hcp_icafix_traindata="/data/studies/fMRI/ICA_model/analysis/model/mymodel.pyfix_model" \
    --hcp_icafix_threshold=5 \  # adjust the threshold as appropriate based on <model_name>_LOO_results
    --container="$qunex_container_path" \
    --hcp_reuse_existing_ica=TRUE \  # set this to TRUE in order to avoid running ICA again
    --hcp_fix_backup=fix_v1  # backup previous FIX solution

QuNex documentation

HCP ICAFix pipeline

Contents

HCP ICAFix pipeline#

Manual classification and training a FIX model#

Example (manual classification)#

Example (training a custom model)#