nben/occipital_atlas

Deprecation Notice

This docker is now deprecated. Since its development, we have described a newer and better atlas on the cortical surface using the fsaverage (rather than the fsaverage_sym) subject. This functionality is available using the https://hub.docker.com/r/nben/neuropythy/ docker instead. The 'atlas' command of neuropythy applies both the Benson 2014 v4.0 retinotopy atlas and the Wang 2015 atlas. The occipital_atlas docker will remain unchanged, however.

Atlas of the Occipital Cortex

This docker applies the V1, V2, and V3 anatomical template of retinotopy from Benson et al. (2014) as well as the ROI template of Wang et al. (2015). Currently this does not use the original version of the Benson et al. template but rather an updated version that has also been published on the website indicated in the original paper.

Author

Noah C. Benson <<***>>

Usage

This docker can be run with the following command:

bash
docker run -ti --rm -v /path/to/your/freesurfer/subject:/input \
       nben/occipital_atlas:latest

In the above example, the "/path/to/your/freesurfer/subject" is the path to an individual FreeSurfer subject's directory, not to the path of the FreeSurfer SUBJECTS_DIR environment variable, which generally contains the individual subject's directory. The "/input" is the directory inside of the Docker to which the subject's directory is mapped (this must always be /input).

Note that the Docker expects that you have run the xhemireg and surfreg scripts on your subject after having run recon-all in order to register the subject's left and inverted-right hemispheres to the fsaverage_sym subject. (The fsaverage_sym subject is a version of the fsaverage subject with a single the left-right symmetric pseudo-hemisphere.) If your FreeSurfer version is 5.1 or lower, you can obtain the scripts https://surfer.nmr.mgh.harvard.edu/fswiki/Xhemi. The scripts are generally run as follows (using example subject 'bert'):

bash
# Invert the right hemisphere
xhemireg --s bert
# Register the left hemisphere to fsaverage_sym
surfreg --s bert --t fsaverage_sym --lh
# Register the inverted right hemisphere to fsaverage_sym
surfreg --s bert --t fsaverage_sym --lh --xhemi

Additionally, the Docker may be run as follows to view the license file (see the "License" section below) or this README file.

bash
# View the License:
docker run -ti --rm nben/occipital_atlas:latest license
# View the README:
docker run -ti --rm nben/occipital_atlas:latest readme

Outputs

The script writes the following surface data files to /path/to/your/freesurfer/subject/surf:

• lh.template_angle.mgz, rh.template_angle.mgz
• lh.template_eccen.mgz, rh.template_eccen.mgz
• lh.template_areas.mgz, rh.template_areas.mgz
• lh.wang2015_atlas.mgz, rh.wang2015_atlas.mgz

It additionally writes out the following volume files to /path/to/your/freesurfer/subject/mri:

• native.template_angle.mgz
• native.template_eccen.mgz
• native.template_areas.mgz
• native.wang2015_atlas.mgz

The volume files are labeled native because they are oriented in FreeSurfer's native LIA orientation (like the orig.mgz volume). Both the angle and eccentricity are measured in degrees (for both hemispheres polar angle is between 0 and 180 (0 is the upper vertical meridian) and eccentricity is between 0 and 90). The areas template specifies visual areas V1, V2, and V3 as the numbers 1, 2, and 3, respectively, and is 0 everywhere else. The angle and eccentricity templates are also 0 outside of V1, V2, and V3.

If you wish to make volume files oriented identically to the original T1 used with FreeSurfer's recon-all command (scanner orientation), the following commands may be run after this Docker has completed; the command assumes that your subject is named "bert" and your FreeSurfer SUBJECTS_DIR environment variable is correctly set:

bash
mri_convert -rl "$SUBJECTS_DIR/bert/mri/rawavg.mgz"            \
            "$SUBJECTS_DIR/bert/mri/native.template_angle.mgz" \
            "$SUBJECTS_DIR/bert/mri/scanner.template_angle.mgz"

Warning: Some users have noticed that using FreeSurfer's mri_convert utility to transform the volumes results in blurring or noise in the results. We suspect that this is because the conversion routine performs a heuristic resampling rather than simply reslicing the volume in some cases. Be sure to check your 'scanner' volumes against the 'native' volumes for accuracy.

Extracting the fsaverage-aligned atlas files

If you wish to examine the Wang2015 atlas on the fsaverage surface, you can extract an MGZ-formatted version of the surface atlas from the docker using the "docker cp" command. A demonstration of how to do this (in bash) is below.

bash
# Pull the docker
docker pull nben/occipital_atlas:latest
# Start the container in daemon mode; save it's key in IMGID
IMGID=`docker run -d nben/occipital_atlas` 
# Copy the lh.wang2015_atlas.mgz file to the current dir
docker cp ${IMGID}:/opt/freesurfer/subjects/fsaverage/surf/lh.wang2015_atlas.mgz .
# Copy the rh.wang2015_atlas.mgz file
docker cp ${IMGID}:/opt/freesurfer/subjects/fsaverage/surf/rh.wang2015_atlas.mgz .
# Stop the container
docker stop ${IMGID}

Conversion of Wang et al. labels to FreeSurfer labels

The following Script was contributed by Hiromasa Takemura and can be used to transform the Docker's outputs into a series of FreeSurfer label files, one per visual area in the Wang et al. (2015) atlas.

bash

#
# This script converts the surface data of Wang et al. (2015)'s atlas into Freesurfer/MNE's label format.  
# The script will be particularly useful for MEG users because it is a preferred format for MNE analysis.
# 
# In this script, we use "bert" as an example of subjectid in freesurfer directory.
# 
# Requirement: Freesurfer:
# https://surfer.nmr.mgh.harvard.edu/
# 
# This script has been tested in Ubuntu 14.04.2 LTS.
#
# For information about Docker tools to generate surface map of Wang's atlas into single brain space:
# https://hub.docker.com/r/nben/occipital_atlas/
# 
# Information of original Wang et al. (2015)'s atlas:
# Wang L, Mruczek RE, Arcaro MJ, Kastner S (2015) Probabilistic Maps of Visual Topography in Human Cortex. Cereb Cortex 25(10):3911-31. doi:10.1093/cercor/bhu277
#
# Author: Hiromasa Takemura, Center for Information and Neural Networks (CiNet), Japan <htakemur@nict.go.jp>
#

export roiname_array=(1 "V1v" "V1d" "V2v" "V2d" "V3v" "V3d" "hV4" "VO1" "VO2" "PHC1" "PHC2" \
    "TO2" "TO1" "LO2" "LO1" "V3B" "V3A" "IPS0" "IPS1" "IPS2" "IPS3" "IPS4" \
    "IPS5" "SPL1" "FEF")
export subjid=004_RT

for i in {1..25}
do
 mri_cor2label --i ${SUBJECTS_DIR}/${subjid}/surf/lh.wang2015_atlas.mgz --id ${i} --l lh.wang2015atlas.${roiname_array[${i}]}.label --surf ${subjid} lh inflated
 mri_cor2label --i ${SUBJECTS_DIR}/${subjid}/surf/rh.wang2015_atlas.mgz --id ${i} --l rh.wang2015atlas.${roiname_array[${i}]}.label --surf ${subjid} rh inflated
done

Dependencies

This docker depends on the ubuntu:trusty Docker; it does not depend on FreeSurfer in any direct way and may be run without it even installed on your own computer; however, FreeSurfer is required to perform the mri_convert step listed above.

The computations performed by this Docker use the https://github.com/noahbenson/neuropythy neuroscience library for Python by Noah C. Benson.

References

• Benson NC, Butt OH, Datta R, Radoeva PD, Brainard DH, Aguirre GK (2012) The retinotopic organization of striate cortex is well predicted by surface topology. Curr Biol 22(21):2081-5. http://www.ncbi.nlm.nih.gov/pubmed/23041195
• Benson NC, Butt OH, Brainard DH, Aguirre GK (2014) Correction of distortion in flattened representations of the cortical surface allows prediction of V1-V3 functional organization from anatomy. PLoS Comput Biol 10(3):e***. http://www.ncbi.nlm.nih.gov/pubmed/24676149
• Wang L, Mruczek RE, Arcaro MJ, Kastner S (2015) Probabilistic Maps of Visual Topography in Human Cortex. Cereb Cortex 25(10):3911-31. http://www.ncbi.nlm.nih.gov/pubmed/25452571

License

Copyright (C) 2016 by Noah C. Benson.

This README file is part of the occipital_atlas Docker.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. if not, see (http://www.gnu.org/licenses/).