Voxelwise GAMM4 Wrapper

This wiki expands on the use of the gamm4 voxelwise wrapper. This script is able to run a voxelwise analysis using the gamm4 analysis. The script currently takes in an .Rds file containing paths to each subject image and is able to create a 4D image based on it. The script works both on chead and monstrum but the wiki will only elaborate on running it on chead.

Required Flags

The script requires the following flags in order to run. You must include all of them in order to run the script

Options:

-c COVARIATES, --covariates=COVARIATES
Full path to RDS covariate file.  
Please include bblid and scanid in this file as a column each

-o OUTPUT, --output=OUTPUT
Full path to output directory

-p IMAGEPATHS, --imagepaths=IMAGEPATHS
Name of the variable in the covariate file.
Must  contains the path to the images to be analyzed. 

-m MASK, --mask=MASK
Full path to the mask to be used 

-s SMOOTHING, --smoothing=SMOOTHING
The smoothing in sigmas required for the fourd image. Default is NA

-i INCLUSION, --inclusion=INCLUSION
Name of inclusion variable on dataset. By default 1 should mean include

-u SUBJID, --subjId=SUBJID
subjID name on the covariates dataset

-f FORMULA, --formula=FORMULA
Formula for covariates to be used
Should only include the right hand side of the formula.
DO NOT INCLUDE SPACES IN THE FORMULA
Example: ~ stai_stai_tr+sex+s(age)+s(age,by=sex)

-r RANDOM, --random=RANDOM
Formula for random effects to be used. 
Should only include the right hand side of the formula.
Example: ~(1|bblid)

-n NUMBERCORES, --numbercores=NUMBERCORES
Number of cores to be used, default is 10

-h, --help
Show this help message and exit

Sample Call

This is the sample call for chead:

subjDataName="/data/joy/BBL/studies/exampleData/groupAnalysis/testScript/n404_longitudinal_dataset_asl_chead.rds"
OutDirRoot="/data/joy/BBL/studies/exampleData/groupAnalysis/testScript"
namePaths="asl_paths"
maskName="/home/agarza/masks/pnc_template_brain_2mm_MASK_ROI76.nii.gz"
smooth=0
inclusionName="categorical_include"
subjID="bblid"
covsFormula="~dx+sex+s(age)"
randomFormula="~(1|bblid)"
ncores=10
logfile="/data/joy/BBL/studies/exampleData/groupAnalysis/testScript/n230_asl_paths_categorical_include_smooth0/logs"
errfile="/data/joy/BBL/studies/exampleData/groupAnalysis/testScript/n230_asl_paths_categorical_include_smooth0/logs"

qsub -V -S /share/apps/R/R-3.1.1/bin/Rscript -cwd -o ${logfile} -e ${errfile} -binding linear:10 -pe unihost 10 -l h_vmem=6.5G,s_vmem=6.0G /data/joy/BBL/applications/groupAnalysis/gamm4_voxelwise.R -c $subjDataName -o $OutDirRoot -p $namePaths -m $maskName -i $inclusionName -u $subjID -f $covsFormula -r $randomFormula -n 10 -s 0

To expand on the last command, this is the command required to submit to the grid and take advantage of the multicore functionality of the script. You must edit the flags -n -binding and -pe depending on the number of cores you want, the default here is 10 and this is the recommended amount. The maximum cores you can used on chead is 16. More information on running jobs using multiple cores on the CFN wiki here.

You must also edit v_mem and s_vmem based on the amount of memory you need for your analysis. The flags after the call to the script are all passed to the script and you should reference to the help menu from the script.

Output

The script outputs a first level folder that is named in the following way: n{number of observations}{name of paths}{inclusion criterion}_smooth{smoothing number}. For the example call the first level directory is called n230_asl_paths_categorical_include_smooth0.

Inside the first level directory you will find a CSV with the paths that were used to create the 4d image. A list of subject ids for cross-reference. You will also include the 4d image and the mask used for the analysis. Inside this first level directory there will be a logs directory as well as a second directory named using the type of model you are running and the actual formula for the model. For example for the following call our directory is called "n230gamm_Cov_dx_sex_sage_sagebysex_Random_1bblid".

Inside this second level directory you will find p-maps, t-maps, and z-maps for all covariates named accordingly, as well as a logs text file with all the arguments that were passed to the script.

Example Directory Contents:

This section includes the example directory contents from the above call.

[agarza@chead testScript]$ ls n230_asl_paths_categorical_include_smooth0/
asl_paths.csv  bblid.csv  fourd.nii.gz  logs  
mask.nii.gz  n230gamm_Cov_dx_sex_sage_Random_1bblid

The first level includes a csv with the paths used to create the 4d image, a csv with the subject ids in the same order as the paths, the 4d image, a copy of the mask, a logs folder as well as a model-specific folder named using the covariates included in the model.

[agarza@chead ]$ ls n230gamm_Cov_dx_sex_sage_Random_1bblid/
gamm4P_dxTDTD.nii.gz     gamm4P_sage.nii.gz   gamm4T_dxTDTD.nii.gz     
gamm4T_sex.L.nii.gz   gamm4Z_Intercept.nii.gz gamm4Z_sex.L.nii.gz 
gamm4P_Intercept.nii.gz  gamm4P_sex.L.nii.gz  gamm4T_Intercept.nii.gz  
gamm4Z_dxTDTD.nii.gz gamm4Z_sage.nii.gz       logs.txt

The second level directory, or model specific directory, includes a maps for each covariates in the model. All fixed effects have a p-map, t-map and z-map, while splines have a p-map and a z-map. There is also a text file that includes the arguments you passed via the command line.

Alternative way of running script using qlogin

In order to run the script using qlogin you can just follow the next steps:

Note: the maximum number of cores you can run the script using qlogin is 5.

qloginp5 -l h_vmem=30.5G,s_vmem=30G 
Rscript /data/joy/BBL/applications/groupAnalysis/gamm4_voxelwise.R -args $$$$