Group-level statistics and mapping results#

To run 2nd level, group-based statistical testing QuNex has adopted the FSL PALM package that uses permutation resampling methods of complex uni- and multi-variate general linear models (GLMs) for statistical inference. QuNex provides wrapper functions that simplify generation of input files, and running analyses.

Preparing for and running PALM#

To prepare for and run PALM analyses:

  • create_ws_palm_design

    This is a front-end command that generates the design matrix, t-contrasts, f-contrasts and exchangeability blocks specification files for standard full factorial within-subject ANOVA designs. The command currently allows creation of models of up to four factors with arbitrary number of levels each. It is recommended that the files are carefully examined to ensure that the information matches the data and that the design is appropriate for the type of second-level statistical analysis that you want to perform. More details on design matrices, t-contrasts, f-contrasts and exchangeability blocks that are appropriate for specific statistical analyses (e.g. independent t-test, paired t-test, one-way ANOVA etc.) can be found on FSL wiki.

  • run_palm

    This command prepares the relevant input files, runs PALM and organizes the results. When the inputs are CIFTI grayordinate .dtseries files, it seamlessly splits the .dtseries files into left hemisphere, right hemisphere, and volume components, runs PALM in parallel on each of them, and then combines the results back into joint .dscalar files. The command also works with regular volume NIfTI files, or parcellated .ptseries files. For details of the command use, please refer to the command inline help.

PALM examples#

Below we provide an example based on an actual study design.

Stroop task within design

In this study 30 participants performed the Stroop color-word task in a fast event-related design with pseudo randomly mixed congruent and incongruent trials. They performed the task in a baseline and then an incentive condition. At the 1st level, the BOLD data were analyzed using assumed modeling of the hemodynamic response function (HRF) specifically using the Boynton assumed shape. This resulted in four beta estimates per subject per voxel. The results were extracted using:

qunex general_extract_glm_volumes \
    --flist=stroop_glm.list \
    --effects="b_congruent,b_incongruent,i_congruent,i_incongruent" \
    --saveoption="by_session"

stroop_glm.list specified in the flist is a file that lists for each session the path to the glm file, e.g.:

session id:S001
    glm:/data/studies/Stroop/sessions/S001/images/bold_conc_Stroop_A_s_res-eA_Bcoeff.dtseries.nii
session id:S002
    glm:/data/studies/Stroop/sessions/S002/images/bold_conc_Stroop_A_s_res-eA_Bcoeff.dtseries.nii
...

The effects listed in the effects are regressor names specified when running preprocess_conc and refer to events specified in .fidl files, namely congruent and incongruent trials for baseline (b_) and incentive (i_) conditions. The command will join all the subjects' data in a single file, across all frames, starting by all estimates for subject 1, then all estimates for subject 2 and so on. The order of estimates will be the same as the order specified in the event_string when GLM was computed.

To prepare design files for PALM analysis, run the following command:

qunex create_ws_palm_design \
    --factors='2,2' \
    --nsubjects=30 \
    --root=stroop

Here the --root flag will specify the naming of the output files such that it will start with stroop. The command will prepare a stroop_d.csv design file coding both factors, their interaction, and subject intercepts. It will also prepare a stroop_t.csv t-contrast file coding t-contrasts for both main effects and interaction, and a stroop_f.csv f-contrast file coding for f-contrasts related to both main effects and an interaction. Of note, when you execute this command from the terminal pay attention to the location because the command will save the output files in that specific location where you are executing the command from. For instance, you may want consider running this command from ~/analysis folder within the QuNex folder hierarchy.

After these are prepared, it is possible to run PALM using the following command:

qunex run_palm \
    --image=stroop_glm.dtseries.nii \
    --design="name:stroop" \
    --args="n:500|T|T2DHEC:2:0.5:26|C:3.1|accel:tail" \
    --root=palm/stroop_anova

This command will take the stroop_glm.dtseries.nii with all subject's beta estimates. It will split it into the volume, left surface, and right surface components and then run PALM separately on each of them. Specifically, it will run PALM with 500 permutations, it will make use of Threshold Free Cluster Enhancement (TFCE) with additional H, E, and C parameters for 2D surface, it will also perform cluster extent correction of p values with threshold of 3.1, and it will make use of tail acceleration. The results will be saved in the palm folder and named stroop_anova. It will run the three PALM instances in parallel, and once all three are finished, it will join the volume and two surface results back into a single CIFTI file.

The same procedure can be used for any other second level analysis, be it on task activation beta estimates, seed-based functional connectivity results, global brain connectivity (GBC) maps, or any other results. Do note that create_ws_palm_design prepares design files, t- and f-contrast files optimized for ANOVA type analysis of within subject design only. Do consult PALM and FSL documentation for construction of other types of designs and contrasts.

Setting thresholds and combining maps#

To threshold, mask and combine the final results, the following functions are available:

  • mask_map

    This is a convenience wrapper command that utilizes wb_command to mask arbitrary CIFTI files (e.g. ztstat .dscalar images from PALM) using the provided list of criterion files (e.g. p-values .dscalar images from PALM) and thresholds.

  • join_maps

    Another convenience wrapper command that utilizes wb_command to join multiple .dscalar images into a single file with named maps.

Maps examples#

To continue with the example above, imagine that we were only interested in the comparison of the effect of congruency in the baseline and in incentive condition separately. We ran PALM with two contrasts for each condition (baseline and incentive), first for incongruent is larger than incongruent (C1) and the second for congruent is larger than incongruent (C2). The results were stored in folder planned and root names stroop_congruency_baseline, and stroop_congruency_incentive. We can threshold and join maps using the following commands:

# set the threshold of significance to 0.05 adjusted over three separate brain segments
pcrit=0.017

# create a masked Z value image for congruency in baseline based on TFCE results
qunex mask_map \
    --image="planned/stroop_congruency_baseline_reg_ztstat_C1.dscalar.nii" \
    --masks="planned/stroop_congruency_baseline_tfce_ztstat_fwep_C1.dscalar.nii,planned/stroop_congruency_baseline_tfce_ztstat_fwep_C2.dscalar.nii" \
    --output="planned/stroop_congruency_baseline_ztstat_tfwep_${pcrit}.dscalar.nii" \
    --maxv="${pcrit}"

# create a masked Z value image for congruency in incentive based on TFCE results
qunex mask_map \
    --image="planned/stroop_congruency_incentive_reg_ztstat_C1.dscalar.nii" \
    --masks="planned/stroop_congruency_incentive_tfce_ztstat_fwep_C1.dscalar.nii,planned/stroop_congruency_incentive_tfce_ztstat_fwep_C2.dscalar.nii" \
    --output="planned/stroop_congruency_incentive_ztstat_tfwep_${pcrit}.dscalar.nii" \
    --maxv="${pcrit}"

# join all maps and name them
qunex join_maps \
    --images="planned/stroop_congruency_baseline_reg_ztstat_C1.dscalar.nii, \
              planned/stroop_congruency_incentive_reg_ztstat_C1.dscalar.nii, \
              planned/stroop_congruency_baseline_ztstat_tfwep_${pcrit}.dscalar.nii, \
              planned/stroop_congruency_incentive_ztstat_tfwep_${pcrit}.dscalar.niii" \
    --names="congruency in baseline [Z], congruency in incentive [Z], congruency in baseline [TFCE p=${pcrit}], congruency in incentive [TFCE p=${pcrit}]" \
    --output="planned/Stroop_congruency_baseline_and_incentive_Z_TFCE${pcrit}.dscalar.nii"

The results Stroop_congruency_baseline_and_incentive_Z_TFCE${pcrit}.dscalar.nii can be visualized in the Connectome Workbench. For full details regarding how to visualize CIFTI data please refer to Human Connectome Project Tutorials.