# Group-level statistics and mapping results To run 2nd level, group-based statistical testing QuNex has adopted the FSL [PALM](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/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`](../../api/gmri/create_ws_palm_design.rst) 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](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/GLM). * [`run_palm`](../../api/gmri/run_palm.rst) 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: ``` bash 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.: ``` bash 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: ``` bash 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: ``` bash 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: ``` bash # 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](https://www.humanconnectome.org/tutorials).