Merge pull request #103 from VinceBaz/master

Added plot_fslr() function and a yerkes19 fetcher

Author: rmarkello

netneurotools/data/osf.json

@@ -76,6 +76,13 @@
         ],
         "md5": "bd944e3f9f343e0e51e562b440960529"
     },
+    "tpl-yerkes19": {
+        "url": [
+            "mb37e",
+            "60ae93d504e91a005f1761ab"
+        ],
+        "md5": "9ee4f1605fb690a85b04b61549d62925"
+    },
     "tpl-fsaverage": {
         "fsaverage": {
             "url": [

netneurotools/datasets/__init__.py

@@ -10,9 +10,9 @@
 ]
 
 from .fetchers import (fetch_cammoun2012, fetch_pauli2018, fetch_fsaverage,
-                       fetch_conte69, fetch_connectome, available_connectomes,
-                       fetch_vazquez_rodriguez2019, fetch_schaefer2018,
-                       fetch_hcp_standards, fetch_voneconomo, fetch_mmpall,
-                       fetch_civet)
+                       fetch_conte69, fetch_yerkes19, fetch_connectome,
+                       available_connectomes, fetch_vazquez_rodriguez2019,
+                       fetch_schaefer2018, fetch_hcp_standards,
+                       fetch_voneconomo, fetch_mmpall, fetch_civet)
 from .generators import (make_correlated_xy)
 from .mirchi import (fetch_mirchi2018)

netneurotools/datasets/fetchers.py

@@ -217,6 +217,75 @@ def fetch_conte69(data_dir=None, url=None, resume=True, verbose=1):
     return Bunch(**dict(zip(keys + ['info'], data)))
 
 
+def fetch_yerkes19(data_dir=None, url=None, resume=None, verbose=1):
+    """
+    Downloads files for Donahue et al., 2016 Yerkes19 template
+
+    Parameters
+    ----------
+    data_dir : str, optional
+        Path to use as data directory. If not specified, will check for
+        environmental variable 'NNT_DATA'; if that is not set, will use
+        `~/nnt-data` instead. Default: None
+    url : str, optional
+        URL from which to download data. Default: None
+    resume : bool, optional
+        Whether to attempt to resume partial download, if possible. Default:
+        True
+    verbose : int, optional
+        Modifies verbosity of download, where higher numbers mean more updates.
+        Default: 1
+
+    Returns
+    -------
+    filenames : :class:`sklearn.utils.Bunch`
+        Dictionary-like object with keys ['midthickness', 'inflated',
+        'vinflated'], where corresponding values are lists of filepaths to
+        downloaded template files.
+
+    References
+    ----------
+    https://balsa.wustl.edu/reference/show/976nz
+
+    Donahue, C. J., Sotiropoulos, S. N., Jbabdi, S., Hernandez-Fernandez, M.,
+    Behrens, T. E., Dyrby, T. B., ... & Glasser, M. F. (2016). Using diffusion
+    tractography to predict cortical connection strength and distance: a
+    quantitative comparison with tracers in the monkey. Journal of
+    Neuroscience, 36(25), 6758-6770.
+
+    Notes
+    -----
+    License: ???
+    """
+
+    dataset_name = 'tpl-yerkes19'
+    keys = ['midthickness', 'inflated', 'vinflated']
+
+    data_dir = _get_data_dir(data_dir=data_dir)
+    info = _get_dataset_info(dataset_name)
+    if url is None:
+        url = info['url']
+
+    opts = {
+        'uncompress': True,
+        'md5sum': info['md5'],
+        'move': '{}.tar.gz'.format(dataset_name)
+    }
+
+    filenames = [
+        'tpl-yerkes19/tpl-yerkes19_space-fsLR32k_{}.{}.surf.gii'
+        .format(res, hemi) for res in keys for hemi in ['L', 'R']
+    ]
+
+    data = _fetch_files(data_dir, files=[(f, url, opts) for f in filenames],
+                        resume=resume, verbose=verbose)
+
+    # bundle hemispheres together
+    data = [SURFACE(*data[i:i + 2]) for i in range(0, 6, 2)]
+
+    return Bunch(**dict(zip(keys + ['info'], data)))
+
+
 def fetch_pauli2018(data_dir=None, url=None, resume=True, verbose=1):
     """
     Downloads files for Pauli et al., 2018 subcortical parcellation

netneurotools/plotting.py

@@ -258,37 +258,105 @@ def plot_conte69(data, lhlabel, rhlabel, surf='midthickness',
         Default: (0, 0, 0)
     kwargs : key-value mapping
         Keyword arguments for `mayavi.mlab.triangular_mesh()`
+    Returns
+    -------
+    scene : mayavi.Scene
+        Scene object containing plot
+    """
+
+    return plot_fslr(data, lhlabel, rhlabel, surf_atlas='conte69',
+                     surf_type=surf, vmin=vmin, vmax=vmax, colormap=colormap,
+                     colorbar=colorbar, num_labels=num_labels,
+                     orientation=orientation, colorbartitle=colorbartitle,
+                     backgroundcolor=backgroundcolor,
+                     foregroundcolor=foregroundcolor, **kwargs)
+
+
+def plot_fslr(data, lhlabel, rhlabel, surf_atlas='conte69',
+              surf_type='midthickness', vmin=None, vmax=None,
+              colormap='viridis', colorbar=True, num_labels=4,
+              orientation='horizontal', colorbartitle=None,
+              backgroundcolor=(1, 1, 1), foregroundcolor=(0, 0, 0),
+              **kwargs):
+
+    """
+    Plots surface `data` on a given fsLR32k atlas
+
+    Parameters
+    ----------
+    data : (N,) array_like
+        Surface data for N parcels
+    lhlabel : str
+        Path to .gii file (generic GIFTI file) containing labels to N/2 parcels
+        on the left hemisphere
+    rhlabel : str
+        Path to .gii file (generic GIFTI file) containing labels to N/2 parcels
+        on the right hemisphere
+    surf_atlas: {'conte69', 'yerkes19'}, optional
+        Surface atlas on which to plot 'data'. Default: 'conte69'
+    surf_type : {'midthickness', 'inflated', 'vinflated'}, optional
+        Type of brain surface. Default: 'midthickness'
+    vmin : float, optional
+        Minimum value to scale the colormap. If None, the min of the data will
+        be used. Default: None
+    vmax : float, optional
+        Maximum value to scale the colormap. If None, the max of the data will
+        be used. Default: None
+    colormap : str, optional
+        Any colormap from matplotlib. Default: 'viridis'
+    colorbar : bool, optional
+        Wheter to display a colorbar. Default: True
+    num_labels : int, optional
+        The number of labels to display on the colorbar.
+        Available only if colorbar=True. Default: 4
+    orientation : str, optional
+        Defines the orientation of colorbar. Can be 'horizontal' or 'vertical'.
+        Available only if colorbar=True. Default: 'horizontal'
+    colorbartitle : str, optional
+        The title of colorbar. Available only if colorbar=True. Default: None
+    backgroundcolor : tuple of float values with RGB code in [0, 1], optional
+        Defines the background color. Default: (1, 1, 1)
+    foregroundcolor : tuple of float values with RGB code in [0, 1], optional
+        Defines the foreground color (e.g., colorbartitle color).
+        Default: (0, 0, 0)
+    kwargs : key-value mapping
+        Keyword arguments for `mayavi.mlab.triangular_mesh()`
 
     Returns
     -------
     scene : mayavi.Scene
         Scene object containing plot
     """
 
-    from .datasets import fetch_conte69
+    from .datasets import fetch_conte69, fetch_yerkes19
     try:
         from mayavi import mlab
     except ImportError:
-        raise ImportError('Cannot use plot_conte69() if mayavi is not '
+        raise ImportError('Cannot use plot_fslr() if mayavi is not '
                           'installed. Please install mayavi and try again.')
 
     opts = dict()
     opts.update(**kwargs)
 
     try:
-        surface = fetch_conte69()[surf]
+        if surf_atlas == 'conte69':
+            surface = fetch_conte69()[surf_type]
+        elif surf_atlas == 'yerkes19':
+            surface = fetch_yerkes19()[surf_type]
+
     except KeyError:
         raise ValueError('Provided surf "{}" is not valid. Must be one of '
                          '[\'midthickness\', \'inflated\', \'vinflated\']'
-                         .format(surf))
+                         .format(surf_type))
+
     lhsurface, rhsurface = [nib.load(s) for s in surface]
 
     lhlabels = nib.load(lhlabel).darrays[0].data
     rhlabels = nib.load(rhlabel).darrays[0].data
     lhvert, lhface = [d.data for d in lhsurface.darrays]
     rhvert, rhface = [d.data for d in rhsurface.darrays]
 
-    # add NaNs for subcortex
+    # add NaNs for medial wall
     data = np.append(np.nan, data)
 
     # get lh and rh data
@@ -510,7 +578,7 @@ def plot_fsaverage(data, *, lhannot, rhannot, order='lr', mask=None,
 
         vtx_data.append(vtx)
 
-    brain = plot_fsvertex(np.hstack(vtx_data), order=order, mask=None,
+    brain = plot_fsvertex(np.hstack(vtx_data), order='lr', mask=None,
                           subject_id=subject_id, subjects_dir=subjects_dir,
                           vmin=vmin, vmax=vmax, **kwargs)
 

netneurotools/tests/test_datasets.py

@@ -52,6 +52,12 @@ def test_fetch_conte69(tmpdir):
                ['midthickness', 'inflated', 'vinflated', 'info'])
 
 
+def test_fetch_yerkes19(tmpdir):
+    conte = datasets.fetch_yerkes19(data_dir=tmpdir, verbose=0)
+    assert all(hasattr(conte, k) for k in
+               ['midthickness', 'inflated', 'vinflated'])
+
+
 def test_fetch_pauli2018(tmpdir):
     pauli = datasets.fetch_pauli2018(data_dir=tmpdir, verbose=0)
     assert all(hasattr(pauli, k) and os.path.isfile(pauli[k]) for k in