This is an old revision of the document!
This pipeline is a collection of steps that can be used to process a single subject's resting state data from raw into a node based correlation matrix representing connectivity between different regions of the brain.
Usage: resting_pipeline.py --func /path/to/run4.bxh --steps all --outpath /here/ -p func Program to run through Nan-kuei Chen's resting state analysis pipeline: steps: 0 - convert data to nii in LAS orientation ( we suggest LAS if you are skipping this step ) 1 - slice time correction 2 - motion correction, then regress out motion parameter 3 - skull stripping 4 - normalize data 5 - regress out WM/CSF 6 - bandpass filter 7 - do parcellation and produce correlation matrix from label file * or split it up: 7a - do parcellation from label file 7b - produce correlation matrix [--func option is ignored if step 7b is run by itself unless --dvarsthreshold is specified, and --corrts overrides default location for input parcellation results (outputpath/corrlabel_ts.txt)] 8 - functional connectivity density mapping Options: -h, --help show this help message and exit -f /path/to/BXH, --func=/path/to/BXH bxh ( or nifti ) file for functional run --throwaway=4 number of timepoints to dis-regard from beginning of run --t1=/path/to/BXH bxh ( or nifti ) file for the anatomical T1 -p func, --prefix=func prefix for all resulting images, defaults to name of input -s 0,1,2,3, --steps=0,1,2,3 comma seperated string of steps. 'all' will run everything, default is all -o PATH, --outpath=PATH location to store output files --sliceorder=string sliceorder if slicetime correction ( odd=interleaved (1,3,5,2,4,6), up=ascending, down=descending, even=interleaved (2,4,6,1,3,5) ). Default is to read this from input image, if available. --tr=MSEC TR of functional data in MSEC --ref=FILE pointer to FLIRT reference image if not using standard brain --flirtmat=FILE a pre-defined flirt matrix to apply to your functional data. (ie: func2standard.mat) --refwm=FILE pointer to WM mask of reference image if not using standard brain --refcsf=FILE pointer to CSF mask of reference image if not using standard brain --refgm=FILE pointer to GM mask of reference image if not using standard brain --refbrainmask=FILE pointer to brain mask of reference image if not using standard brain --refacpoint=45,63,36 AC point of reference image if not using standard MNI brain --betfval=0.4 f value to use while skull stripping. default is 0.4 --anatbetfval=0.5 f value to use while skull stripping ANAT. default is 0.5 --lpfreq=0.08 frequency cutoff for lowpass filtering in HZ. default is .08hz. highpass is fixed at .001hz. --corrlabel=FILE pointer to 3D label containing ROIs for the correlation search. default is the 116 region AAL label file --corrtext=FILE pointer to text file containing names/indices for ROIs for the correlation search. default is the 116 region AAL label txt file --corrts=FILE If using step 7b by itself, this is the path to parcellation output (default is to use OUTPATH/corrlabel_ts.txt), which will be used as input to the correlation. --dvarsthreshold=THRESH If specified, this reprsents a DVARS threshold either in BOLD units, or if ending in a '%' character, as a percentage of mean global signal intensity (over the brain mask). Any volume contributing to a DVARS value greater than this threshold will be excluded ("scrubbed") from the (final) correlation step. DVARS calculation is performed on the results of the last pre-processing step, and is calculated as described by Power, J.D., et al., "Spurious but systematic correlations in functional connectivity MRI networks arise from subject motion", NeuroImage(2011). Note: data is only excluded during the final correlation, and so will never affect any operations that require the full signal, like regression, etc. --dvarsnumneighbors=NUMNEIGHBORS If --dvarsthreshold is specified, then --dvarsnumnumneighbors specifies how many neighboring volumes, before and after the initially excluded volumes, should also be excluded. Default is 0. --fdthreshold=THRESH If specified, this reprsents a FD threshold in mm. Any volume contributing to a FD value greater than this threshold will be excluded ("scrubbed") from the (final) correlation step. FD calculation is performed on the results of the last pre-processing step, and is calculated as described by Power, J.D., et al., "Spurious but systematic correlations in functional connectivity MRI networks arise from subject motion", NeuroImage(2011). Note: data is only excluded during the final correlation, and so will never affect any operations that require the full signal, like regression, etc. --fdnumneighbors=NUMNEIGHBORS If --fdthreshold is specified, then --fdnumnumneighbors specifies how many neighboring volumes, before and after the initially excluded volumes, should also be excluded. Default is 0. --motionthreshold=THRESH If specified, any volume whose motion parameters indicate a movement greater than this threshold (in mm) will be excluded ("scrubbed") from the (final) correlation step. Volume-to-volume movement is calculated per pair of neighboring volumes from the three rotational and three translational parameters generated by mcflirt. Motion for a pair of neighboring volumes is calculated as the maximum displacement (due to the combined rotation and translation) of any voxel on the 50mm-radius sphere surrounding the center of rotation. Note: data is only excluded during the final correlation, and so will never affect any operations that require the full signal, like regression, etc. --motionnumneighbors=NUMNEIGHBORS If --motionthreshold is specified, then --motionnumnumneighbors specifies how many neighboring volumes, before and after the initially excluded volumes, should also be excluded. Default is 1. --motionpar=FILE.par If --motionthreshold is specified, then --motionpar specifies the .par file from which the motion parameters are extracted. If you allow this script to perform motion correction, then this option is ignored. --scrubop=SCRUBOP If --motionthreshold, --dvarsthreshold, or --fdthreshold are specified, then --scrubop specifies the aggregation operator used to determine the final list of excluded volumes. Default is 'or', which means a volume will be excluded if *any* of its thresholds are exceeded, whereas 'and' means all the thresholds must be exceeded to be excluded. --powerscrub Equivalent to specifying --fdthreshold=0.5 --fdnumneighbors=0 --dvarsthreshold=0.5% --dvarsnumneigbhors=0 --scrubop='and', to mimic the method used in the Power et al. article. Any conflicting options specified before or after this will override these. --scrubkeepminvols=NUMVOLS If --motionthreshold, --dvarsthreshold, or --fdthreshold are specified, then --scrubminvols specifies the minimum number of volumes that should pass the threshold before doing any correlation. If the minimum is not met, then the script exits with an error. Default is to have no minimum. --fcdmthresh=THRESH R-value threshold to be used in functional connectivity density mapping ( step8 ). Default is set to 0.6. Algorithm from Tomasi et al, PNAS(2010), vol. 107, no. 21. Calculates the fcdm of functional data from last completed step, inside a dilated gray matter mask --cleanup delete files from intermediate steps?
* that is the zr_values from the subject.graphml displayed in matplotlib. the cursor shows the intersecting region at the bottom, and if you click, time courses are displayed. we're working on a release (cp - 3/30/12)
For the rs-pipeline viewer:
/usr/local/packages/biacpython/bin/rspipe_viewer.py --help Usage: rspipe_viewer.py --graphml /path/to/subject.graphml --stat zrvalue Program to display graphml output from resting_pipeline --stat is the statistic to view ( zrvalue, rvalue ) --notimecourse is a flag to skip the timecourse display when clicking Options: -h, --help show this help message and exit -g /path/to/subject.graphml, --graphml=/path/to/subject.graphml full path to graphml file to display -s zrvalue, --stat=zrvalue statistic type to display ( zrvalue or rvalue ). default zr --notimecourse do not display the seperate timecourse figures
One method group analysis could be done using Monte-Carlo permutation testing with FSL's randomise .
To do this, you would combine all of your subjects's results into one 3D file with fslmerge ( 116 x 116 x NumSubjs ):
>> fslmerge -t group_zr subj1/zr_matrix.nii.gz subj2/zr_matrix.nii.gz subj3/zr_matrix.nii.gz subjN/zr_matrix.nii.gz
For a single group result, the input to randomise is simply:
>> randomise -i group_zr -o group_res -1 -x -m mask_matrix * -i input, -o output prefix, -1 represents a 1-tailed t-test, -x will output corrected ( _corrp_ ) and uncorrected ( _p_ ) pvals, * -m points to one of the inclusion masks produced for your matrix ( this assures the connections aren't being used twice )
Your results will be the same correlation matrix size, but now will represent corrected p-values of the connectivity.
To do something more complicated ( group differences, other regressions ), please create a design matrix and contrasts file using FSL's Glm gui.
Now, within randomise you need to input the .mat and .con files instead of “-1” to produce your contrasts.
>> randomise -i group_zr -o group_res -d 2group.mat -t 2group.con -x -m mask_matrix
The results will be in the same format described above, except there will be more contrasts labeled as “tstat#”
If using the cluster, you can turn on “fsl_sub” with export FSLSUBMIT=1, then use randomise_parallel, which will run all the permutations simultaneously.
Here's an example of the matrix with the matrix_mask, including this would only analyze things inside the yellow triangle:
Usage: connectome2graphml.py -s stats.nii.gz -p prefix Program to convert the 2D correlation matrix to a graphml file which can be used with graph-theory packages. --type is the statistics type ( ie: pvalue, rvalue, zrvalue ) --labels and --text default to aal116 if no input is provided ( ie: aal116, raichle36 or full paths ) --AC point defaults to 45,63,36 if undefined ( assuming MNI152_T1_2mm_brain ) --thresh is the threshold to use for extracting edges. default is 0. ( ie: .99 for p > .01 ) --above is to specify that your stats are above the diagonal instead of below ( below is the default ) Options: -h, --help show this help message and exit -s FILE, --stats=FILE input correlation matrix --type=STRING type of statistics of input matrix --thresh=STRING threshold for edge extraction -l FILE, --labels=FILE label file used to produce the correlation matrix -t FILE, --text=FILE delimited text file associated with correlation labels ( contains region index and names ) --ac=STRING anterior commissure point for coordinate conversion -p STRING, --prefix=STRING prefix to name your output graphml --above option to specify if your stats are above the diagonal of the connectome instead of below ( below is the default )
Usage: connectome_2Dgraph.py --graphml /path/to/connectome.graphml --edgeval pvalue --thresh 0.9998 Generates a graphy-theroy 2D graph with nodes/edges above a certain threshold. Communities are colored by a Louvian algorithm. Clicking a specific node with produce another graph containing only nodes that are directly connected to the area selected. EDGEVAL is the label for the statistic from the .graphml file created above Options: -h, --help show this help message and exit -g /path/to/graphml, --graphml=/path/to/graphml graphml file containing connectome information -t 0.9998, --thresh=0.9998 threshold to use for displaying significant connection -e pvalue, --edgeval=pvalue the statistic that is represented by the connections in the graphml
connectome_2Dgraph.py -g myconnectome_all.graphml --thresh 0.99 -e pvalue