This shows you the differences between two versions of the page.
biac:analysis:resting_pipeline [2013/09/16 18:26] admin |
biac:analysis:resting_pipeline [2023/02/23 18:43] |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Python/FSL Resting State Pipeline ====== | ||
- | |||
- | This pipeline is a collection of steps that can be used to process a single subject' | ||
- | |||
- | < | ||
- | |||
- | < | ||
- | Usage: | ||
- | resting_pipeline.py --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 - lowpass 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/ | ||
- | 8 - functional connectivity density mapping | ||
- | |||
- | |||
- | |||
- | Options: | ||
- | -h, --help | ||
- | -f / | ||
- | bxh ( or nifti ) file for functional run | ||
- | --throwaway=4 | ||
- | run | ||
- | --t1=/ | ||
- | -p func, --prefix=func | ||
- | prefix for all resulting images, defaults to name of | ||
- | input | ||
- | -s 0,1,2,3, --steps=0, | ||
- | comma seperated string of steps. ' | ||
- | everything, default is all | ||
- | -o PATH, --outpath=PATH | ||
- | location to store output files | ||
- | --sliceorder=string | ||
- | (1, | ||
- | even=interleaved (2, | ||
- | this from input image, if available. | ||
- | --tr=MSEC | ||
- | --ref=FILE | ||
- | brain | ||
- | --flirtmat=FILE | ||
- | data. (ie: func2standard.mat) | ||
- | --refwm=FILE | ||
- | standard brain | ||
- | --refcsf=FILE | ||
- | standard brain | ||
- | --refgm=FILE | ||
- | standard brain | ||
- | --refbrainmask=FILE | ||
- | standard brain | ||
- | --refacpoint=45, | ||
- | AC point of reference image if not using standard MNI | ||
- | brain | ||
- | --betfval=0.4 | ||
- | --anatbetfval=0.5 | ||
- | 0.5 | ||
- | --lpfreq=0.08 | ||
- | is .08hz | ||
- | --corrlabel=FILE | ||
- | correlation search. default is the 116 region AAL | ||
- | label file | ||
- | --corrtext=FILE | ||
- | for the correlation search. default is the 116 region | ||
- | AAL label txt file | ||
- | --corrts=FILE | ||
- | parcellation output (default is to use | ||
- | OUTPATH/ | ||
- | to the correlation. | ||
- | --dvarsthreshold=THRESH | ||
- | If specified, this reprsents a DVARS threshold either | ||
- | in BOLD units, or if ending in a ' | ||
- | percentage of mean global signal intensity (over the | ||
- | brain mask). | ||
- | greater than this threshold will be excluded | ||
- | (" | ||
- | calculation is performed on the results of the last | ||
- | pre-processing step, and is calculated as described by | ||
- | Power, J.D., et al., " | ||
- | correlations in functional connectivity MRI networks | ||
- | arise from subject motion", | ||
- | 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. | ||
- | --fdthreshold=THRESH | ||
- | Any volume contributing to a FD value greater than | ||
- | this threshold will be excluded (" | ||
- | (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., | ||
- | " | ||
- | connectivity MRI networks arise from subject motion", | ||
- | NeuroImage(2011). | ||
- | the final correlation, | ||
- | 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. | ||
- | --motionthreshold=THRESH | ||
- | If specified, any volume whose motion parameters | ||
- | indicate a movement greater than this threshold (in | ||
- | mm) will be excluded (" | ||
- | correlation step. Volume-to-volume movement is | ||
- | calculated per pair of neighboring volumes from the | ||
- | three rotational and three translational parameters | ||
- | generated by mcflirt. | ||
- | 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. | ||
- | only excluded during the final correlation, | ||
- | 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. | ||
- | --motionpar=FILE.par | ||
- | specifies the .par file from which the motion | ||
- | parameters are extracted. | ||
- | perform motion correction, then this option is | ||
- | ignored. | ||
- | --scrubop=SCRUBOP | ||
- | --fdthreshold are specified, then --scrubop specifies | ||
- | the aggregation operator used to determine the final | ||
- | list of excluded volumes. | ||
- | means a volume will be excluded if *any* of its | ||
- | thresholds are exceeded, whereas ' | ||
- | thresholds must be exceeded to be excluded. | ||
- | --powerscrub | ||
- | --fdnumneighbors=0 --dvarsthreshold=0.5% | ||
- | --dvarsnumneigbhors=0 --scrubop=' | ||
- | method used in the Power et al. article. | ||
- | conflicting options specified before or after this | ||
- | will override these. | ||
- | --scrubkeepminvols=NUMVOLS | ||
- | If --motionthreshold, | ||
- | --fdthreshold are specified, then --scrubminvols | ||
- | specifies the minimum number of volumes that should | ||
- | pass the threshold before doing any correlation. | ||
- | the minimum is not met, then the script exits with an | ||
- | error. | ||
- | --fcdmthresh=THRESH | ||
- | 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 | ||
- | </ | ||
- | |||
- | ===== Step Descriptions ===== | ||
- | |||
- | ==== Step 0 ==== | ||
- | * this step take the input bxh/nifti and changes the orientation of the data into LAS, then converts the data into niigz. | ||
- | * LAS is suggested because this is the orientation of the fsl T1 template. | ||
- | * this step utilizes the BXH tools | ||
- | * if **--throwaway** is defined, this number of timepoints will be disregarded during this step | ||
- | |||
- | ==== Step 1 ==== | ||
- | * run fsl's slice time correction ( slicetimer ) | ||
- | * if starting with a BXH header, you'll likely have the sliceorder field which will be used to create a custom sliceorder file to be used by fsl | ||
- | * if this isn't present, then you'll need to define **--sliceorder** so that we can generate the file for you | ||
- | * " | ||
- | * " | ||
- | * " | ||
- | * " | ||
- | |||
- | ==== Step 2 ==== | ||
- | * motion correct data using fsl's mcflirt | ||
- | * once mcflirt is completed, the 6 motion parameters ( which will be in a .par file ) are then regressed out of each individual voxel usings a linear regression | ||
- | |||
- | ==== Step 3 ==== | ||
- | * the functional run is meaned across time with fslmaths, then bet is applied. | ||
- | * if you find that bet is doing a poor job finding the edges you can adjust the intensity threshold with **--betfval** | ||
- | * this is equivalent of **-f** when actually running bet. the default is 0.4 (same as feat), but smaller values will be more conservative in finding the edges of the brain ( ie: larger mask ) | ||
- | * if provided T1 anatomical is skull stripped. **--anatbetfval** is used to control intensity threshold, the default is 0.5 (same as feat) | ||
- | ==== Step 4 ==== | ||
- | * normalize the data using flirt | ||
- | * if no options are specified, then the default is the standard MNI152_T1_2mm_brain used in feat | ||
- | * if you have a specific template, you can define it with **--ref** (ie: a kid brain, or study specific template) | ||
- | * if your subject has already been normalized during standard pre-processing of other runs, please provide the flirt matrix from pre-stats with **--flirtmat** ( most likely example_func2standard.mat) | ||
- | * this will apply the previously determined flirt matrix to your functional data instead of trying to calculate a new matrix based on the functionals. | ||
- | * if you've provided at T1 anatomical image then this sequence is followed: | ||
- | * func-2-t1 | ||
- | * t1-2-standard | ||
- | * flirt matrices are concatenated to create func-2-standard | ||
- | * if no T1 is provided, then the functional is used for the flirt normalization | ||
- | |||
- | ==== Step 5 ==== | ||
- | * this step will take the white matter and csf masks generated by FAST and regress out the signal from the functional data using the same method as the motion paramters. | ||
- | * if you've provided your own reference image for normalization, | ||
- | * this can be create with "fast -g INPUT.nii.gz": | ||
- | * if no options are defined, then the MNI152 masks will be used | ||
- | |||
- | ==== Step 6 ==== | ||
- | * this step will band-pass filter data to remove high-frequency noise using custom python code | ||
- | * the default is 0.08 HZ | ||
- | * if you'd like to chose a different frequency, please use ** --lpfreq ** | ||
- | ==== Step 7 ==== | ||
- | * if defaults are used, then the aal_MNI_V4 label file is used to extract the average timeseries for each of the 116 regions | ||
- | * if --dvarsthreshold or --motionthreshold are specified, then the ROI-averaged timeseries are further filtered (" | ||
- | * cross correlation coefficients are found for the entire matrix of 116x116 regions | ||
- | * this step produces 4 files: | ||
- | * " | ||
- | * " | ||
- | * " | ||
- | * " | ||
- | * " | ||
- | * since they are saved as nifti, then can be loaded into fslview. | ||
- | * if the default labels are used, then you can load a custom atlas ( " | ||
- | * this is loaded through the Atlas Toolbar, the atlas is installed on the cluster, but it can be provided with instructions to install elsewhere. | ||
- | * if you want to provide your own label file, the ** --corrlabel ** option can be used. | ||
- | * The input to this step would be a 3D image of ROIs the same size as your normalized data. | ||
- | * Each individual ROI needs to have a unique intensity value for the timecourse extraction ( ie: 5 ROIs with intergers as values from 1-5 ). | ||
- | * This would be the standard type of thing saved from the pickatlas | ||
- | * Also provide a label text ** --corrtext ** file with your labels intensity value and label name in tab delimited format | ||
- | * If your space is **different** from mni please provide the anterior commissure point **--refacpoint** for centroid/ | ||
- | * The correlation matrix would then be NumRois X NumRois and point 1,4 would be the corrcoef or zscore of the ROI with values 2 and 5 ( these are indexed starting at zero ) | ||
- | |||
- | {{: | ||
- | |||
- | * that is the zr_values from the subject.graphml displayed in matplotlib. | ||
- | |||
- | For the rs-pipeline viewer: | ||
- | < | ||
- | / | ||
- | Usage: | ||
- | rspipe_viewer.py --graphml / | ||
- | |||
- | Program to display graphml output from resting_pipeline | ||
- | | ||
- | | ||
- | |||
- | |||
- | Options: | ||
- | -h, --help | ||
- | -g / | ||
- | full path to graphml file to display | ||
- | -s zrvalue, --stat=zrvalue | ||
- | statistic type to display ( zrvalue or rvalue ). | ||
- | default zr | ||
- | --notimecourse | ||
- | </ | ||
- | |||
- | ===== Things to consider ===== | ||
- | * this was designed to be modular, so that you only need to run the steps you need | ||
- | * if you've already pre-processed your data, then you may only need steps 5,6,7 ... please provide the ** --steps ** flag as needed. | ||
- | * the default is " | ||
- | * If you just want to run a different label file, then you may only need step 7 | ||
- | * If you have physiological data, it should be removed from the functional data **prior** to running the pipeline | ||
- | * [[biac: | ||
- | |||
- | * this is installed on the cluster, but can also be run on a personal linux machine, or mac | ||
- | * nonstandard python dependencies: | ||
- | * FSL | ||
- | * bxh/xcede tools for step0 | ||
- | |||
- | |||
- | |||
- | ===== Group Analysis Suggestions ===== | ||
- | |||
- | One method group analysis could be done using Monte-Carlo permutation testing with [[http:// | ||
- | |||
- | * please don't add any clustering/ | ||
- | |||
- | To do this, you would combine all of your subjects' | ||
- | < | ||
- | >> fslmerge -t group_zr subj1/ | ||
- | </ | ||
- | |||
- | 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, | ||
- | * this will look identical to creating a 3rd-level design matrix through the feat gui. | ||
- | * the same same types of things done through feat can be done here ... [[http:// | ||
- | * Below is a snapshot of a simple 2-group model designed with the Glm wizard. | ||
- | |||
- | {{: | ||
- | |||
- | |||
- | Now, within randomise you need to input the .mat and .con files instead of " | ||
- | < | ||
- | >> 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 " | ||
- | * tstat1 represent contrast 1 as defined in your GLM, tstat2 contrast 2, etc | ||
- | |||
- | If using the cluster, you can turn on " | ||
- | |||
- | Here's an example of the matrix with the matrix_mask, | ||
- | |||
- | {{: | ||
- | ===== Going Further ===== | ||
- | |||
- | <code bash> | ||
- | connectome2graphml.py --help | ||
- | </ | ||
- | |||
- | <code bash> | ||
- | 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 | ||
- | -s FILE, --stats=FILE | ||
- | input correlation matrix | ||
- | --type=STRING | ||
- | --thresh=STRING | ||
- | -l FILE, --labels=FILE | ||
- | label file used to produce the correlation matrix | ||
- | -t FILE, --text=FILE | ||
- | ( contains region index and names ) | ||
- | --ac=STRING | ||
- | -p STRING, --prefix=STRING | ||
- | prefix to name your output graphml | ||
- | --above | ||
- | ( below is the default ) | ||
- | </ | ||
- | |||
- | * Convert the 3rd-Level connectome results into a graphml ( xml based definition for graphs ) file to be used with graph-theory based analyses/ | ||
- | * We have written some code to perform some simple graphing methods using [[http:// | ||
- | * The following functions will be based on the graphml created with the connectome2graphml.py function | ||
- | |||
- | |||
- | === 2D Graph-Theory Representation === | ||
- | |||
- | ---- | ||
- | <code bash> | ||
- | connectome_2Dgraph.py --help | ||
- | </ | ||
- | |||
- | <code bash> | ||
- | Usage: | ||
- | connectome_2Dgraph.py --graphml / | ||
- | |||
- | 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 | ||
- | -g / | ||
- | 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 | ||
- | </ | ||
- | |||
- | * This function takes your graphml input: | ||
- | * thresholds out the " | ||
- | * calculates their " | ||
- | * plots the graph in 2D brain space ( the z-dimension is thrown out ) | ||
- | * Node ( ROI ) color represent community, Node size represents " | ||
- | * If you click a node of interest, a new ego_graph will be shown ( all nodes with a direct connection to your ROI ) | ||
- | |||
- | <code bash> | ||
- | connectome_2Dgraph.py -g myconnectome_all.graphml --thresh 0.99 -e pvalue | ||
- | </ | ||
- | |||
- | {{: | ||
- | |||
- | |||
- | Still under-development | ||
- | 3D VTK: | ||
- | |||
- | {{: | ||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||