From NITRC Wiki

Contents 1 Processing Scripts for the The 1000 Functional Connectomes Project (Version 1.1) 1.1 Setup 1.1.1 Computer Requirements 1.1.2 Directory Requirements 1.1.3 Setting Up the Scripts 1.2 Templates 1.3 Batch Processing 1.3.1 batch_process.sh 1.3.2 batch_list.txt 1.3.3 Run batch_process.sh 1.3.4 Running seed based RSFC using batch_process.sh 1.3.5 Calculating ALFF and fALFF using batch_process.sh 1.3.6 Calculating Dual-Regression-based RSFC using batch_process.sh 1.4 Output Files 1.5 Advanced Users

Processing Scripts for the The 1000 Functional Connectomes Project (Version 1.1)

Prepared By: Maarten Mennes, Xi-Nian Zuo and Michael P. Milham

1. The 1000 Functional Connectomes Project scripts are being released as part of the project’s commitment to public sharing and are intended to facilitate the processing of the datasets included in the project. They are a simplified version of the scripts that were used by for image processing and analysis in the initial feasibility analyses for the project (Biswal et al., 2010; PNAS). The scripts are designed to work for the directory structure utilized in the NITRC data distribution (see Directory Requirements section below for details). Usage of alternate directory structures will require modification by users.

2. The scripts are released under the same license as the data. You are free to modify and distribute the scripts in any way you want, but please credit the 1000 Functional Connectomes Project (www.nitrc.org/projects/fcon_1000). It is the user’s responsibility to ensure the accuracy of any results obtained with the 1000 Functional Connectomes Project scripts. The 1000 Functional Connectomes Project and its contributors are not responsible for the accuracy of any data obtained using the scripts provided.

3. The image processing steps included in the scripts are those specified in our initial publication (Biswal et al., 2010, PNAS). A variety of alternative parameters, analytic approaches and processing steps exist. Users are strongly encouraged to review the specific processing steps and modify/add/delete as they feel appropriate for their own personal intentions.

Setup

Computer Requirements

• Unix-compatible operating system (e.g., Solaris, Linux, Mac OSX)
• Bash shell
• AFNI (http://afni.nimh.nih.gov/afni)
• FSL (http://www.fmrib.ox.ac.uk/fsl)
• AFNI and FSL commands need to be generally accessible at the command prompt (i.e. located in the user’s path; see documentation on AFNI and FSL websites)

Directory Requirements

To build the directory structure, simply create a project directory and put all the sites as you downloaded them from NITRC inside this directory.

Directory Structure:

/<project directory>

/<project directory>/<site directory>

/<project directory>/<site directory>/<subject directory>

/<project directory>/<site directory>/<subject directory>/anat

/<project directory>/<site directory>/<subject directory>/func

Sample:

/home/fcon_1000/

/home/fcon_1000/NewYork_a

/home/fcon_1000/NewYork_a/sub001

/home/fcon_1000/NewYork_a/sub001/anat

/home/fcon_1000/NewYork_a/sub001/func

project directory = /home/fcon_1000

site directory = NewYork_a

Setting Up the Scripts

After downloading the 1000 Functional Connectome projects scripts, be sure to:

1. place the fcon_1000_scripts_ver1.1.tar.gz in the desired location (e.g., /home/fcon_1000)
2. untar the file from the command-line as follows:

tar -xzpf fcon_1000_scripts_ver1.1.tar.gz

If done correctly, you will have a folder called <scripts> that contains the necessary files (e.g., /home/fcon_1000/scripts). You may want to add this to your path, though this is not necessary.

Templates

Several templates are included with the scripts:

1. nuisance.fsf - feat model template for the nuisance analyses
2. 3mm MNI152_T1 templates (since these are not included in the FSL standard brains)
3. metaICA.nii.gz - 20 independent component maps derived using meta-ICA as described in Biswal et al., 2010, PNAS. These maps serve as the templates for the dual-regression-based RSFC calculations.

Batch Processing

batch_process.sh

The batch_process.sh script allows the user to process a list of one or more sites using a single command. Prior to executing the script, one must first open the script and:

1. set the directory where the scripts are kept, e.g. /home/fcon_1000/scripts
2. select the process to be executed. The choices are:

   • general image preprocessing of the data for later functional connectivity analyses
   • seed based connectivity analyses (requires the image preprocessing to be completed)
   • calculate two amplitude measures, i.e., ALFF and fALFF (requires the image preprocessing to be completed)
   • do dual regression functional connectivity analyses (requires the image preprocessing to be completed)

3. identify other parameters that might need to be changed from their default setting:

   • the name of the anatomical scan that you want to use
   • the name of the resting-state scan you want to use
   • the directories and names of files listing seeds (seed_list.txt) and sites (batch_list.txt) you want to run
   • the low-frequency band for computing ALFF and fALFF
   • the template used for dual regression model

batch_list.txt

The batch_list.txt file included in the script release contains the appropriate parameters for all sites that are currently available on nitrc. Feel free to make new batch list files (e.g., my_batch_list.txt) to run a particular site or combination of sites. Batch_list.txt contains 1 line per site indicating (inputs are separated by a space):

• the main directory for the site
• the full path to the subject list for the site
• the first timepoint to use (default = 0 as timepoint counting starts at 0)
• the last timepoint to use (default = number of timepoints -1)
• the number of timepoints in the resting-state scan for that particular site
• the TR for that site

You must open batch_list.txt and edit YOUR_DIRECTORY to match your directory setup. e.g., change YOUR_DIRECTORY to /home/fcon_1000/

Run batch_process.sh

Save your changes and run the script by typing ./batch_process.sh or bash batch_process.sh on the command line, while being in the directory that contains the batch_process.sh script (e.g. /home/fcon_1000/scripts).

NOTE: all .txt files (e.g., batch_list.txt, seed_list.txt, subjects.txt) can be called however you want (e.g., my_seeds.txt). Just make sure to adjust the according parameter in batch_process.sh or batch_list.txt so the scripts can find your file.

Running seed based RSFC using batch_process.sh

1. Prepare a list of seeds you want to run. Prepare the list as shown in example_seed_list.txt

   For your convenience we included the 6 seeds from Fox et al. (2005, PNAS) that were used in the Biswal et al. (2010, PNAS) manuscript. We also included an example seed list called Fox_seed_list.txt that lists the Fox seeds. If you want to run the Fox seeds, you will have to edit this file and change YOUR_DIRECTORY to match your directory structure (e.g. change YOUR_DIRECTORY to /home/fcon_1000/).

2. In batch_process.sh:

   • Select option 2 (seed-based RSFC) in the “What to do?” section of batch_process.sh
   • If needed edit the parameter that points to SEED_LIST.txt; e.g., change it to ${scripts_dir}/my_seeds.txt

3. Run batch_process.sh

Calculating ALFF and fALFF using batch_process.sh

1. This script will calculate the amplitude of low frequency fluctuations (ALFF) and fractional ALFF (fALFF) from the resting-state scan.

   Please see "Zuo et al., 2010, Neuroimage: The oscillating brain: Complex and reliable" for more information.

2. Set the appropriate parameters in batch_process.sh

   • Select option 3. The script will start preprocessing the data starting from the skullstripped resting-state scan. Therefore it requires general preprocessing to be completed.

3. Run batch_process.sh

Calculating Dual-Regression-based RSFC using batch_process.sh

1. This script calculate dual-regression based connectivity.

   The templates used for the dual regression are included in the scripts release (you can use any template you want, but that will require editing the script). Please see "Zuo et al., 2010, Neuroimage: Reliable intrinsic connectivity networks: Test–retest evaluation using ICA and dual regression approach" and "Biswal et al., 2010, PNAS: Toward discovery science of human brain function" for more information.

2. Set the appropriate parameters in batch_process.sh

   • Select option 4. The image that is used to calculate the RSFC on is set to the resting-state residuals after removing the nuisance variables (rest_res2standard.nii.gz). You can choose another image but it has to be registered to standard space.

3. Run batch_process.sh

Output Files

The most important output files

• mprage_..._brain.nii.gz – skullstripped anatomical image
• rest_pp.nii.gz – preprocessed resting-state scan
• rest_res.nii.gz – residuals of the resting-state scan after removing the nuisance covariates
• rest_res2standard.nii.gz – same as rest_res.nii.gz but registered to standard space

• func/RSFC/seed1_Z.nii.gz – Z-transformed single subject RSFC map for a seed mask named “seed1” (e.g. func/RSFC/Fox_tn_LP_3mm.nii.gz)
• func/RSFC/seed1_Z_2standard.nii.gz – same as seed1_Z.nii.gz but registered to standard space

• func/ALFF/ALFF.nii.gz – single subject ALFF map (same for fALFF)
• func/ALFF/ALFF_Z.nii.gz – same as ALFF.nii.gz but Z transformed
• func/ALFF/ALFF_Z_2standard.nii.gz – same as ALFF_Z.nii.gz but registered to standard space

• func/DR/dr_icXX_Z_2standard.nii.gz – single subject dual regressed RSFC map for component XX registered to standard space

Advanced Users

1. Batch_process.sh passes a number of parameters to a number of main processing scripts. You do not need batch_process.sh to run the scripts. Instead, you can open the main scripts and enter parameters yourself to suit your processing needs. You can then run the main scripts separately. The main scripts are:

1. batch_process.sh
2. 0_preprocess.sh
3. 6_singlesubjectRSFC.sh
4. 7_singlesubjectfALFF.sh
5. 8_singlesubjectDR.sh

2. 0_preprocess.sh preprocesses your data for functional connectivity analyses. It calls 5 scripts each running a part of the preprocessing (1_anatpreproc.sh, 2_funcpreproc.sh, 3_registration.sh, 4_segmentation.sh and 5_nuisance.sh). You can modify the parameters in 0_preprocess to match another dataset you have. You can also modify parameters in the subscripts to match your preprocessing needs (e.g., you might want to add slice time correction, or change the spatial smoothing or temporal filtering settings).

3. 6_singelsubjectRSFC.sh calculates single subject seed-based functional connectivity. You can easily change the parameters in the script to calculate connectivity for a dataset you already have. The script loops through all seeds for each subject.

4. 7_singelsubjectfALFF.sh calculates single subject amplitude of low frequency oscillations. You can easily change the parameters in the script to calculate ALFF and fALFF for a dataset you already have. After specific preprocessing the script calculates the ALFF and fALFF.

5. 8_singelsubjectDR.sh calculates single subject dual regression-based functional connectivity. You can easily change the parameters in the script to calculate DR connectivity for a dataset you already have. The script loops through all 'components' for each subject. Default the script works of the metaICA.nii.gz image that is included in the templates folder. Therefore the scripts loops through the 20 components included in that image. You can use a different template to use for the dual-regression, but you will have to edit the template loop in the script to match your template. We tried to comment all steps in the script to clarify each step. Please refer to the forums if something is unclear or can be optimized.