Using atlas ROIs with mrTools

Noah Benson has a set of python based tools that implement his method for doing surface based prediction of retinotopic visual field maps Neuropythy as well as a Bayesian analysis which combines pRF measurements with anatomical information to generate receptive field maps.

To import these atlases from your freesurfer sturctures, you can do the following.

Install neuropythy (see here for more details):

pip install neuropythy

Setup configuration file by copying the following into the file ~/.npythyrc - making sure to change folders into what makes sense for you. (see here for more details):

{"freesurfer_subject_paths": "~/data/atlas/freesurfer",
 "data_cache_root":          "~/data/atlas/tmp",
 "hcp_subject_paths":        "~/data/atlas/hcp",
 "hcp_auto_download":        true,
 "hcp_credentials":          "~/.hcp-passwd"}

Now to get retinotopy predictions from the anatomy, you can call their function ny.vision.predict_retinotopy (see here for more details)

cynar:/Users/justin> python
Python 2.7.13 |Anaconda 2.3.0 (x86_64)| (default, Dec 20 2016, 23:05:08) 
# import library
>>> import neuropythy as ny
# Load subject ID from freesurfer path (see above configuration setting) jg
>>> sub = ny.freesurfer_subject('jg')
>>> sub
Subject(<jg>, <'/Users/justin/data/atlas/freesurfer/jg'>)
# run the retinotopy prediction
>>> (lh_retino, rh_retino) = ny.vision.predict_retinotopy(sub)

Takes a few minutes and then spits back two structures with the left and right retinotopy predictions. We can save that out to a matlab file:

# import scipy library
>>> import scipy.io as sio
# save out the left and right retinotopy
>>> sio.savemat('lh_retino.mat',lh_retino)
>>> sio.savemat('rh_retino.mat',rh_retino)

You may also wish to save what the mappings of each visual area number is to a string (this will save to a txt file). Note that you can skip this step, if the ROIs are in the order that mlrImportNeuropythy expects ('V1','V2','V3','hV4','V01','V02','LO1','LO2','TO1','TO2','V3b','V3a')

>>> mdl_lh = ny.vision.retinotopy_model('benson17','lh')
>>> with open('lh_labels.txt','w') as f:
...     for item in mdl_lh.area_id_to_name:
...             f.write("%s\n" % mdl_lh.area_id_to_name[item])
>>> mdl_rh = ny.vision.retinotopy_model('benson17','rh')
>>> with open('rh_labels.txt','w') as f:
...     for item in mdl_rh.area_id_to_name:
...             f.write("%s\n" % mdl_rh.area_id_to_name[item])

Once you have done the above, you can import into mrTools. In matlab navigate to where you saved the files lh_retino.mat and rh_retino.mat

[lh rh] = mlrImportNeuropythy('lh_retino','rh_retino');

The code should be able to open the files and then will ask you to find the surface files. Navigate the file structure to the freesurfer directory with surfRelax and click on left_GM.off (it shouldn't matter which one you click on though as it will guess the rest of the names accordingly.

If things work correctly, it should show you the ROIs on the surface

You can see the different overlays, by selecting them in the dialog box that comes up. For instance, you should be able to see the polar angle:

This will return two structures (one for each hemisphere) that has fields rois with the rois in them.

If you want to check in MLR, you can have the program generate a temporary MLR folder and display the ROIs in MLR.

[lh rh] = mlrImportNeuropythy('lh_retino','rh_retino','doTestInMLR=1');

It should then also bring up the MLR view after it is done importing:

When you are done viewing, do dbcont and it will automatically shutdown mrTools and delete the temporary mrTools directory

dbcont

There are some options - for example, you can read in text file labels (generated from ptyhon above) and set the location of the surfaces:

[lh rh] = mlrImportNeuropythy('lh_retino','rh_retino','surfPath','~/data/atlas/freesurfer/jg/surfRelax/jg_left_GM.off','lh_labels=~/lh_labels.txt','rh_labels=~/rh_labels.txt') 

Also, if you want to save all the rois to a directory

mlrImportNeuropythy('lh_retino','rh_retino','saveDir=~/Desktop/ROIs');

You can import labels from freesurfer as ROIs. There are generated automatically with recon_all and give you a few anatomical ROIs that may be useful.

% pass in the directory where you have your freesurfer labels
rois = mlrImportFreesurferLabel('~/data/atlas/freesurfer/jg/label');

You will need to navigate to the left gray matter surface:

You can automatically display them in a temporary MLR session by doing:

% pass in the directory where you have your freesurfer labels
rois = mlrImportFreesurferLabel('~/data/atlas/freesurfer/jg/label','doTestInMLR=1');

It should look something like this:

When you are done viewing the rois, you can do dbcont and it will automatically delete the temporary mlr directory

dbcont

You can automatically save all the rois into a directory you specify:

rois = mlrImportFreesurferLabel('~/data/atlas/freesurfer/jg/label','saveDir=~/Desktop/ROIs');

If you want to convert annotation files, you will need to convert them first to labels using mri_annotation2label

The Glasser atlas is another tool, similar to the Benson atlas, that predicts ROIs for individual subjects. It does so by aligning the subject's brain to a reference (fsaverage, the free surfer average of many different subjects) and extrapolating ROIs from the reference brain. It actually does this backwards the way I've just described - it takes a labeled brain (fsaverage) and transforms it to match the target (your subject) brain, then uses those transformed ROIs.

How do we do that? First, you want to run the FreeSurfer reconstruction (via recon-all - probably on luxardo). You then want to align your target to a reference by calling mri_surf2surf like so:

mri_surf2surf --srcsubject fsaverage --trgsubject s0811 --srcsurfval atlasmgz/rh.Glasser2016.nii --trgsurfval s0811/atlas/rh.Glasser2016.nii --hemi rh

This is the example for subject s0811. In this case, I've run this in ~/freesurfer/subjects on luxardo. fsaverage exists there. s0810 also exists there, because I ran the reconstruction. I created an empty folder called “atlas” in the s0810 folder to store the outputs before running surf2surf. The call above does the right hemisphere, then you can do it for the left by changing the srcsurfval argument, the trgsurfval argument, and the hemi argument.

It's worth putting that call in the context of the explanation in the first paragraph: you are transforming a source (src) subject (the fsaverage) with drawn ROIs into the target (trg) subject space by matching the surfaces. When you run these, you should get lh.Glasser.2016 and rh.Galsser.2016 in your subject/atlas folder. These match your subject surfaces and have ROIs.

From here, the process is very similar to getting the Benson ROIs. Copy the subject folder to your computer (you need to have FreeSurfer set up - I guess you could do this part on luxardo, too, but I prefer to do it on my machine). Make sure you have both Glasser hemispheres. Next you will load and save the ROIs with python by calling:

python loadSaveGlasserROIs.py s0811

Make sure that the paths in your script are correct. They default to Akshay's paths. It should be obvious what they should point to. This should save a Matlab file in the atlas directory.

We are ready to start up Matlab and save some ROIs! Start up Matlab.

First, go do your subject folder and run

mlrImportFreeSurfer

This should make a surfRelax folder in your subject directory. You need to point the next function to the left gray matter surface, which will be in surfRelax.

Now, to get the actual ROIs, run:

mlrImportGlasser

Make sure your paths point to the right place. I just took all the paths out and run this is the subject-specific atlas folder, which should have a Matlab file called “glasser.mat” from the last step. Make sure that you have defined a save directory in your script - this takes a long time to run (~15 minutes), and if you haven't specified a save file, it won't save at the end!!

That should be it. It should save the ROIs the same way the Benson atlas does.

Glasser atlas