User Tools
biac:analysis:resting_pipeline
Differences
This shows you the differences between two versions of the page.
|
biac:analysis:resting_pipeline [2013/09/17 17:20] admin [Python/FSL Resting State Pipeline] |
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 - 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/ | ||
| - | 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 lowpass is 0.08 HZ | ||
| - | * highpass is fixed at .001 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 | ||
| - | </ | ||
| - | |||
| - | |||
| - | ==== Step 8 ==== | ||
| - | * Functional connectivity density mapping | ||
| - | * Takes functional data from last step and calculates how connected they are to the voxels around them | ||
| - | * uses ( --fcdmthresh and --refgm ) as the pearson r-value and gray matter mask | ||
| - | * if defaults are used, then a dilated gray matter mask is used from FAST segmentation of MNI brain and a pearson r value of 0.6 | ||
| - | * Iteratively goes to all neighboring voxels and counts the number that have correlated signal until they are under the r threshold | ||
| - | * adapted from Dardo Tomasi, PNAS(2010), vol. 107, no. 21. 9885–9890 | ||
| - | * resulting file with be " | ||
| - | |||
| - | {{: | ||
| - | ===== 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: | ||
| - | |||
| - | {{: | ||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
| - | |||
biac/analysis/resting_pipeline.txt · Last modified: 2023/02/23 18:43 (external edit)
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
