=====================
Section 1: Background
=====================
This folder contains the estimated maps and results from Yeo et al. (Under Review). We estimated the distribution and degree of functional specialization within the association cortex based on a large-scale neuroimaging meta-analysis (N=10,449) and resting-state fMRI analyses (N=1000). By mathematically formalizing the notion that a task engages multiple cognitive components, each supported by multiple brain regions, we identified cognitive components that are shared across tasks. We derived quantitative functional specialization maps, revealing complex zones of frontal and parietal regions ranging from being highly specialized to highly flexible. Regions specialized for the same components were strongly coupled. Functionally flexible regions were functionally heterogeneous and exhibited connectivity patterns that may drive their selectivity for individual components. Our results suggest that heterogeneous networks of functionally specialized and functionally flexible association regions contribute to our capacity to execute multiple and varied tasks.


======================================
Section 2: Information about Downloads
======================================
There are two folders: "YeoBrainmapMNI152" and "YeoBrainmapFreeSurfer". The "YeoBrainmapMNI152" folder contains the estimates in FSL MNI152 space. The "YeoBrainmapFreeSurfer" folder contains the estimates in FreeSurfer fsaverage space. There are 4 sets of results: (1) Probability a component would activate a voxel Pr(voxel | component), (2) probability a task would recruit a component Pr(component | task), (3) Functional Specificity maps and (4) Functional Flexibility maps. Note that the Pr(component | task) is the same across both MNI152 and fsaverage atlas spaces.  

Important Note: Because some image viewers do not handle these range of values very well, we have multipled the values in the *PrActGivenComp* files by 1e5. Therefore in the resulting volumes, value of 1 corresponds to probability of 1e-5.


====================================================
Section 3: Information about FSL MNI152 distribution
====================================================

Information about Folder structure
==================================
1) All the results are inside the "FSL" folder within the "YeoBrainmapMNI152" folder.

2) Within the "FSL" folder, FSL_MNI152_2mm.nii.gz corresponds to the MNI152 template released by FSL software.

3) Yeo_XXComp_PrActGivenComp_FSL_MNI152_2mm.nii.gz is a 4D volume showing Pr(voxel | component) for XX components. It has exactly the same resolution as FSL_MNI152_2mm.nii.gz. For example, Yeo_12Comp_PrActGivenComp_FSL_MNI152_2mm.nii.gz corresponds to 12 components shown in the paper. Note that the probability distribution is over all the voxels in the brain mask. Given that there are about 280k voxels, the probability values are therefore quite small: in the order of 1/280k, which is about 3e-6. Because some image viewers do not handle these range of values very well, we have multipled all the values by 1e5. Therefore in the resulting volumes, value of 1 corresponds to probability of 1e-5.  

4) Yeo_XXComp_PrCompGivenTasks.csv is a comma-separated-value file of Pr(component | task). The file can be opened in excel or other software that can read csv files. For example, Yeo_12Comp_PrCompGivenTasks.csv corresponds to 12 components shown in the paper. The first column corresponds to the 83 behavioral tasks (paradigm class) in BrainMap. The next 12 columns correspond to Pr(component | task) for each of the 12 components.

5) Within the "FSL" folder is a "Flexibility" folder containing quantification of regions activated by multiple components. For example, YeoMD_12comp_FSL_MNI152_thresh1e-5.nii.gz correspond to the number of components (out of 12 components) that activates a brain voxel with probability at least 1e-5. Therefore a value of 2 means that a voxel has greater than 1e-5 probability of being activated by two components. In the paper, we consider such a voxel to be functionally flexible. Note that the flexibilty measures are not integer-valued because the original estimate was computed in a volume (in the same space but different header information). The resulting interpolation into FSL MNI152 resulted in the non integer-values.

6) Within the "FSL" folder is a "Specialization" folder containing quantification of specialized regions. For example, YeoSpecialization_12comp_LogRatio.nii.gz correspond to the 12-component specialization map from the paper (although computed in the volume rather than the surface). The number corresponds to log2 of Pr(top component | voxel)/Pr(second top component | voxel). Therefore a value of 1 indicates functional specificity, because it means that if the voxel was observed to be activated, then the top component would be twice as likely as the second most likely component to be recruited. 


Example Usage
=============
*IMPORTANT* The following example usages assume that the working (current) directory is in the same directory as this README.

1) Except for the csv files (which can be opened with EXCEL), all the volumes are nifty volumes which can be read using any software like freeview (FreeSurfer), fslview (FSL), etc.

2) To overlay the 12-component Pr(voxel | component) on the MNI template using freeview: 

a) type: freeview -v YeoBrainmapMNI152/FSL/FSL_MNI152_2mm.nii.gz -v YeoBrainmapMNI152/FSL/Yeo_12Comp_PrActGivenComp_FSL_MNI152_2mm.nii.gz:colormap=heat:heatscale=1,3,5

b) In the freeview GUI, change "frame" to "5" to show the 5th component and so on. 

This is the colorscale and software used to produce volumetric figures for the paper. Only voxel with values at least 1 (corresponding to probability of 1e-5) are colored.  

3) To overlay the 12-component Pr(voxel | component) on the MNI template using fslview:

a) type: fslview YeoBrainmapMNI152/FSL/FSL_MNI152_2mm.nii.gz YeoBrainmapMNI152/FSL/Yeo_12Comp_PrActGivenComp_FSL_MNI152_2mm.nii.gz -l "Red-Yellow" -b 1,5

b) Note that FSLview's numbering starts at 0. In the fslview GUI, change "Volume" to "4" to show the 5th component and so on. Again, note that voxel with values at least 1 (corresponding to probability of 1e-5) are colored. Values of 5 correspond to probability of 5e-5, etc.

4) To overlay the 12-component flexibility maps on the MNI template using freeview, type:

freeview -v YeoBrainmapMNI152/FSL/FSL_MNI152_2mm.nii.gz YeoBrainmapMNI152/FSL/Flexibility/YeoMD_12comp_FSL_MNI152_thresh1e-5.nii.gz:colormap=heat:heatscale=2,3,5

5) To overlay the 12-component specialization maps on the MNI template using freeview, type:

freeview -v YeoBrainmapMNI152/FSL/FSL_MNI152_2mm.nii.gz YeoBrainmapMNI152/FSL/Specialization/YeoSpecialization_12comp_LogRatio.nii.gz:colormap=heat:heatscale=1,3,5

*IMPORTANT* Observe that there are some noisy clusters of "specific" voxels outside the MNI152 brain. The reason is that we have used a relatively loose brain mask in order to not miss anything. To remove these noisy clusters, one possibility is to mask the map using voxels of FSL_MNI152_2mm.nii.gz which are not equal 0 (voxels = 0 correspond to non-brain regions in MNI template).


==================================================
Section 4: Information about YeoBrainmapFreeSurfer
==================================================

Information about Folder structure
==================================
1) Within the "YeoBrainmapFreeSurfer" folder, the Pr(Component | Task) and Pr(Voxel | Component) are found in the folders "XXComp".

2) For example, YeoBrainmapFreeSurfer/12Comp/lh.Yeo_PrActGivenComp_fsaverage_06.curv is a (FreeSurfer) curvature file showing Pr(vertex | component) for the 6th component of the 12-component estimate in the left hemisphere. It has exactly the same resolution as the fsaverage surface space. These curvature files are obtained by a nonlinear projection of the estimates in MNI152 space to the fsaverage space (details in paper). Recall from Section 3 that the probability distribution is over all the voxels in the brain mask. Given that there are about 280k voxels, the probability values are therefore quite small: in the order of 1/280k, which is about 3e-6. Because some image viewers do not handle these range of values very well, we have multipled all the values by 1e5 (just like in section 3). Therefore in the resulting curvature files, value of 1 corresponds to probability of 1e-5.

3) For example, YeoBrainmapFreeSurfer/12Comp/Yeo_12Comp_PrCompGivenTasks.csv is a comma-separated-value file of Pr(component | task). You can open the file in excel or other software that can read csv files. This file is exactly the same as that in the MNI152 folder.

4) There is a "Flexibility" folder containing quantification of regions activated by multiple components. For example, lh.YeoMD_12comp_thresh1e-5.curv is a (freesurfer) curvature file corresponding to the number of components (out of 12 components) that activates a brain vertex in the left hemisphere with probability at least 1e-5. Therefore a value of 2 means that a vertex has greater than 1e-5 probability of being activated by two components. In the paper, we consider such a vertex to be functionally flexible. Note that the flexibilty measures are not integer-valued because the original estimate was computed in the volume. The resulting projection to freesurfer space resulted in the non integer-values.


5) There is a "Specialization" folder containing quantification of specialized regions. For example, lh.YeoSpecialization_12comp_LogRatio.curv is a (freesurfer) curvature file corresponding to the specialization map from the paper, computed on the surface for the 12 component estimate. The number corresponds to log2 of Pr(top component | vertex)/Pr(second top component | vertex). Therefore a value of 1 indicates functional specificity, because it means that if the vertex was observed to be activated, then the top component would be twice as likely as the second most likely component to be recruited.

6) Within the "Specialization" folder, there are also ROIs extracted from the specificity maps by running a connected component analysis on the surface. For example, lh.YeoSpecialization_12comp_Island.curv is a (freesurfer) curvature file whose values are integer values. Vertices with the same values correspond to a single ROI. The "background" corresponds to values = 0. These ROIs correspond to those used in the paper. 


Example Usage of YeoBrainmapFreeSurfer
======================================
1) The curvature files can be read using tksurfer (FreeSurfer). In the following, we assume that the working (current) directory is in the same directory as this README.

2) To overlay Pr(vertex | 5th component) for the 12-component estimate on the left hemisphere fsaverage template: 

>> setenv SUBJECTS_DIR $FREESURFER_HOME/subjects/
>> tksurfer fsaverage lh inflated -gray -overlay YeoBrainmapFreeSurfer/12Comp/lh.Yeo_PrActGivenComp_fsaverage_05.curv -fminmax 1 5

Note that the option fminmax is only available for FreeSurfer version 5 and above.

3) To overlay the 12-component flexibility maps on the left hemisphere fsaverage template:

>> setenv SUBJECTS_DIR $FREESURFER_HOME/subjects/
>> tksurfer fsaverage lh inflated -gray -overlay YeoBrainmapFreeSurfer/Flexibility/lh.YeoMD_12comp_thresh1e-5.curv -fminmax 2 5

4) To overlay the 12-component specialization maps on the left hemisphere fsaverage template: 

>> setenv SUBJECTS_DIR $FREESURFER_HOME/subjects/
>> tksurfer fsaverage lh inflated -gray -overlay YeoBrainmapFreeSurfer/Specialization/lh.YeoSpecialization_12comp_LogRatio.curv -fminmax 1 5

Note that there are small blobs on this map not in the paper because these small blobs were filtered out for display purposes in the paper.

5) To overlay ROIs derived from the 12-component specialization maps on the left hemisphere fsaverage template:

>> setenv SUBJECTS_DIR $FREESURFER_HOME/subjects/
>> tksurfer fsaverage lh inflated -gray -overlay YeoBrainmapFreeSurfer/Specialization/lh.YeoSpecialization_12comp_Island.curv -fminmax 1 200

Note that each red island has its own unique value, though it may not seem so due to the freesurfer color scale used. For example, if you click on the red blob in the dorsal portion of the central sulcus, the value would correspond to 1. If you click on the red blob in the ventral portion of the central sulcus, the value would correspond to 5.


=====================
Section 5: References
=====================
Yeo BT, Krienen FM, Eickhoff SB, Yaakub SN, Fox PT, Buckner RL, Asplund CL, Chee MWL. Functional Specialization and Confluence in Human Association Cortex. Under Review.

Also see: https://surfer.nmr.mgh.harvard.edu/fswiki/BrainmapOntology_Yeo2015

