Merge pull request #64 from rmarkello/cammoun2012

[ENH] Adds fsaverage5/6 annotation files for Cammoun 2012

Author: rmarkello

netneurotools/data/osf.json

@@ -7,13 +7,27 @@
             ],
             "md5": "c3435f2720da6a74c3d55db54ebdbfff"
         },
-        "surface": {
+        "fsaverage": {
             "url": [
                 "mb37e",
                 "5ce6c30523fec40017e83439"
             ],
             "md5": "478599b362a88198396fdb15ad999f9e"
         },
+        "fsaverage5": {
+            "url": [
+                "mb37e",
+                "5e189a1c57341903868036dd"
+            ],
+            "md5": "e96a456f14fd30f26734a7dfbcbb18e0"
+        },
+        "fsaverage6": {
+            "url": [
+                "mb37e",
+                "5e189a1b5734190380804072"
+            ],
+            "md5": "b220fb658e1abdfdf8bdb55b26f2acf3"
+        },
         "volume": {
             "url": [
                 "mb37e",

netneurotools/datasets/fetchers.py

@@ -7,6 +7,7 @@
 import json
 import os
 import os.path as op
+import warnings
 
 from nilearn.datasets.utils import _fetch_files
 import numpy as np
@@ -23,10 +24,10 @@ def fetch_cammoun2012(version='volume', data_dir=None, url=None, resume=True,
 
     Parameters
     ----------
-    version : {'volume', 'surface', 'gcs'}
+    version : {'volume', 'fsaverage', 'fsaverage5', 'fsaverage6', 'gcs'}
         Specifies which version of the dataset to download, where 'volume' will
-        return .nii.gz atlas files defined in MNI152 space, 'surface' will
-        return .annot files defined in fsaverage space (FreeSurfer 6.0.1), and
+        return .nii.gz atlas files defined in MNI152 space, 'fsaverageX' will
+        return .annot files defined in fsaverageX space (FreeSurfer 6.0.1), and
         'gcs' will return FreeSurfer-style .gcs probabilistic atlas files for
         generating new, subject-specific parcellations
     data_dir : str, optional
@@ -61,7 +62,9 @@ def fetch_cammoun2012(version='volume', data_dir=None, url=None, resume=True,
     License: https://raw.githubusercontent.com/LTS5/cmp/master/COPYRIGHT
     """
 
-    versions = ['volume', 'surface', 'gcs']
+    versions = [
+        'volume', 'surface', 'gcs', 'fsaverage', 'fsaverage5', 'fsaverage6'
+    ]
     if version not in versions:
         raise ValueError('The version of Cammoun et al., 2012 parcellation '
                          'requested "{}" does not exist. Must be one of {}'
@@ -70,6 +73,13 @@ def fetch_cammoun2012(version='volume', data_dir=None, url=None, resume=True,
     dataset_name = 'atl-cammoun2012'
     keys = ['scale033', 'scale060', 'scale125', 'scale250', 'scale500']
 
+    if version == 'surface':
+        warnings.warn('Providing `version="surface"` is deprecated and will '
+                      'be removed in a future release. For consistent '
+                      'behavior please use `version="fsaverage"` instead. ',
+                      DeprecationWarning, stacklevel=2)
+        version = 'fsaverage'
+
     data_dir = _get_data_dir(data_dir=data_dir)
     info = _get_dataset_info(dataset_name)[version]
     if url is None:
@@ -87,10 +97,10 @@ def fetch_cammoun2012(version='volume', data_dir=None, url=None, resume=True,
             'atl-Cammoun2012_space-MNI152NLin2009aSym_res-{}_deterministic{}'
             .format(res[-3:], suff) for res in keys for suff in ['.nii.gz']
         ] + ['atl-Cammoun2012_space-MNI152NLin2009aSym_info.csv']
-    elif version == 'surface':
+    elif version in ('fsaverage', 'fsaverage5', 'fsaverage6'):
         filenames = [
-            'atl-Cammoun2012_space-fsaverage_res-{}_hemi-{}_deterministic{}'
-            .format(res[-3:], hemi, suff) for res in keys
+            'atl-Cammoun2012_space-{}_res-{}_hemi-{}_deterministic{}'
+            .format(version, res[-3:], hemi, suff) for res in keys
             for hemi in ['L', 'R'] for suff in ['.annot']
         ]
     else:
@@ -106,7 +116,7 @@ def fetch_cammoun2012(version='volume', data_dir=None, url=None, resume=True,
 
     if version == 'volume':
         keys += ['info']
-    elif version == 'surface':
+    elif version in ('fsaverage', 'fsaverage5', 'fsaverage6'):
         data = [data[i:i + 2] for i in range(0, len(data), 2)]
     else:
         data = [data[::2][i:i + 2] for i in range(0, len(data) // 2, 2)]

netneurotools/tests/test_datasets.py

@@ -73,7 +73,9 @@ def test_fetch_fsaverage(tmpdir, version):
 
 @pytest.mark.parametrize('version, expected', [
     ('volume', [1, 1, 1, 1, 1]),
-    ('surface', [2, 2, 2, 2, 2]),
+    ('fsaverage', [2, 2, 2, 2, 2]),
+    ('fsaverage5', [2, 2, 2, 2, 2]),
+    ('fsaverage6', [2, 2, 2, 2, 2]),
     ('gcs', [2, 2, 2, 2, 6])
 ])
 def test_fetch_cammoun2012(tmpdir, version, expected):
@@ -90,6 +92,10 @@ def test_fetch_cammoun2012(tmpdir, version, expected):
         else:
             assert isinstance(out, str) and out.endswith('.nii.gz')
 
+    if 'fsaverage' in version:
+        with pytest.warns(DeprecationWarning):
+            datasets.fetch_cammoun2012('surface', data_dir=tmpdir, verbose=0)
+
 
 @pytest.mark.parametrize('dataset, expected', [
     ('celegans', ['conn', 'dist', 'labels', 'ref']),
@@ -134,7 +140,8 @@ def test_fetch_schaefer2018(tmpdir, version):
 
 
 @pytest.mark.parametrize('dset, expected', [
-    ('atl-cammoun2012', ['volume', 'surface', 'gcs']),
+    ('atl-cammoun2012', ['volume', 'fsaverage', 'fsaverage5', 'fsaverage6',
+                         'gcs']),
     ('tpl-conte69', ['url', 'md5']),
     ('atl-pauli2018', ['url', 'md5', 'name']),
     ('tpl-fsaverage', ['fsaverage' + f for f in ['', '3', '4', '5', '6']]),

resources/generate_atl-cammoun2012_surface.py

@@ -16,11 +16,17 @@
 import re
 import shutil
 
-from netneurotools import datasets, freesurfer
 import nibabel as nib
 import numpy as np
 import pandas as pd
 
+from netneurotools import datasets, freesurfer
+from netneurotools.utils import check_fs_subjid, run
+
+
+cmd = 'mri_surf2surf --srcsubject fsaverage --trgsubject {trgsubject} ' \
+      '--sval-annot {annot} --tval {tval} --hemi {hemi} --seed 1234'
+
 
 def combine_cammoun_500(lhannot, rhannot, subject_id, annot=None,
                         subjects_dir=None, use_cache=True, quiet=False):
@@ -63,7 +69,6 @@ def combine_cammoun_500(lhannot, rhannot, subject_id, annot=None,
     cammoun500 : list
         List of created annotation files
     """
-    from netneurotools.utils import check_fs_subjid, run
 
     tolabel = 'mri_annotation2label --subject {subject_id} --hemi {hemi} ' \
               '--outdir {label_dir} --annotation {annot} --sd {subjects_dir}'
@@ -183,3 +188,24 @@ def combine_cammoun_500(lhannot, rhannot, subject_id, annot=None,
             src, tar = src[sidx], tar[sidx]
             labels = tar[np.searchsorted(src, labels)]
             nib.freesurfer.write_annot(annot, labels, ctab, names)
+
+    #####
+    # this should work now!
+    annotations = datasets.fetch_cammoun2012('surface')
+
+    # map (via surf2surf) fsaverage to fsaverage5/6 so we can provide those
+    for trg in ['fsaverage5', 'fsaverage6']:
+        for scale, (lh, rh) in annotations.items():
+            for annot, hemi in [(lh, 'lh'), (rh, 'rh')]:
+                tval = annot.replace('space-fsaverage', 'space-{}'.format(trg))
+
+                msg = f'Generating annotation file: {tval}'
+                print(msg, end='\r', flush=True)
+
+                run(cmd.format(trgsubject=trg,
+                               annot=annot,
+                               tval=tval,
+                               hemi=hemi),
+                    quiet=True)
+
+    print(' ' * len(msg) + '\b' * len(msg), end='', flush=True)