diff --git a/docs/user_guide/annotations.rst b/docs/user_guide/annotations.rst index f18bcde6..6f4b95e7 100644 --- a/docs/user_guide/annotations.rst +++ b/docs/user_guide/annotations.rst @@ -6,7 +6,7 @@ Brain maps and annotations Beyond standard atlases, the ``neuromaps`` toolbox offers access to a repository of brain maps (which we frequently refer to as brain annotations). These annotations are spatial maps representing some feature of interest and -are available in one of the four standard coordinate systems. +are available in at least one of the four standard coordinate systems. We have curated a set of brain annotations that we make available through a standard interface. You can search for available annotations using the @@ -39,7 +39,9 @@ second entry in the tuple provides a brief description of what the map represents. (Because these descriptors are encoded directly in the filenames of the relevant maps we are somewhat limited in terms of space.) The last two entries in the tuple correspond to the coordinate system and density/resolution -in which the annotations are provided. +in which the annotations are provided. More details on each annotation, as well +as papers to cite if you use the data, exist on our `Wiki +`_. This function also accepts keyword arguments in case we want to narrow down the list of returned annotations: diff --git a/docs/user_guide/transformations.rst b/docs/user_guide/transformations.rst index 97b87335..eb3cf8c4 100644 --- a/docs/user_guide/transformations.rst +++ b/docs/user_guide/transformations.rst @@ -54,6 +54,13 @@ It's just as easy to transform the data to a different space: >>> print(fsavg_lh.agg_data().shape) (163842,) +.. important:: + + Partial volume effects (PVE) in PET images are increased when volumetric + data is transformed to the surface, resulting in maps that are heavily + biased by the underlying curvature of the surface. For this reason, it is + generally not recommended to transform PET volumes to the surface. + Note that you can also transform between different resolutions within the MNI152 coordinate system: diff --git a/neuromaps/datasets/annotations.py b/neuromaps/datasets/annotations.py index d3bb4e0b..d424540b 100644 --- a/neuromaps/datasets/annotations.py +++ b/neuromaps/datasets/annotations.py @@ -7,6 +7,8 @@ from pathlib import Path import re import shutil +import numpy as np +import warnings from nilearn.datasets.utils import _fetch_file @@ -228,4 +230,14 @@ def fetch_annotation(*, source=None, desc=None, space=None, den=None, res=None, shutil.move(dl_file, fn) data.append(str(fn)) + # warning for specific maps + warn = [np.logical_and(np.logical_or(dset['source'] == 'beliveau2017', + dset['source'] == 'norgaard2021'), + dset['space'] == 'MNI152') for dset in info] + if any(warn): + warnings.warn('Data from beliveau2017 and norgaard2021 is best used in' + ' the provided fsaverage space ' + '(e.g. source=\'beliveau2017\', space=\'fsaverage\', ' + 'den=\'164k\'). MNI152 maps should only be used for ' + 'subcortical data.') return _groupby_match(data, return_single=return_single) diff --git a/neuromaps/datasets/data/osf.json b/neuromaps/datasets/data/osf.json index c4595fc7..6d5d3089 100644 --- a/neuromaps/datasets/data/osf.json +++ b/neuromaps/datasets/data/osf.json @@ -226,6 +226,48 @@ "6196cb28bbe37803c059ee6d" ] }, + { + "source": "beliveau2017", + "desc": "az10419369", + "space": "fsaverage", + "den": "164k", + "hemi": "R", + "format": "surface", + "fname": "source-beliveau2017_desc-az10419369_space-fsaverage_den-164k_hemi-R_feature.func.gii", + "rel_path": "beliveau2017/az10419369/fsaverage/", + "checksum": "df01756cd50af0e9ebcc2c6df0405135", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "638543a2c86e2818da88f993" + ] + }, + { + "source": "beliveau2017", + "desc": "az10419369", + "space": "fsaverage", + "den": "164k", + "hemi": "L", + "format": "surface", + "fname": "source-beliveau2017_desc-az10419369_space-fsaverage_den-164k_hemi-L_feature.func.gii", + "rel_path": "beliveau2017/az10419369/fsaverage/", + "checksum": "23501cf62b1e7c2881d830cdf4d0ebff", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "638543b0723a11190518c8a6" + ] + }, { "source": "beliveau2017", "desc": "cimbi36", @@ -246,6 +288,48 @@ "6196cb34bbe37803bd59f194" ] }, + { + "source": "beliveau2017", + "desc": "cimbi36", + "space": "fsaverage", + "den": "164k", + "hemi": "R", + "format": "surface", + "fname": "source-beliveau2017_desc-cimbi36_space-fsaverage_den-164k_hemi-R_feature.func.gii", + "rel_path": "beliveau2017/cimbi36/fsaverage/", + "checksum": "d31200bc45b31953f6d8c3632b5d7044", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "638543cdc86e2818da88f9e7" + ] + }, + { + "source": "beliveau2017", + "desc": "cimbi36", + "space": "fsaverage", + "den": "164k", + "hemi": "L", + "format": "surface", + "fname": "source-beliveau2017_desc-cimbi36_space-fsaverage_den-164k_hemi-L_feature.func.gii", + "rel_path": "beliveau2017/cimbi36/fsaverage/", + "checksum": "2dcf2c82b5fb96ac6921d560a3416e64", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "638543bf228a5a18987bc2c1" + ] + }, { "source": "beliveau2017", "desc": "cumi101", @@ -266,6 +350,48 @@ "6196cb3f0b0c1e03d87fbf65" ] }, + { + "source": "beliveau2017", + "desc": "cumi101", + "space": "fsaverage", + "den": "164k", + "hemi": "R", + "format": "surface", + "fname": "source-beliveau2017_desc-cumi101_space-fsaverage_den-164k_hemi-R_feature.func.gii", + "rel_path": "beliveau2017/cumi101/fsaverage/", + "checksum": "7b5bab02f7edbdc255b5c72c93189d4e", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "638543dbc86e2818d988f7ea" + ] + }, + { + "source": "beliveau2017", + "desc": "cumi101", + "space": "fsaverage", + "den": "164k", + "hemi": "L", + "format": "surface", + "fname": "source-beliveau2017_desc-cumi101_space-fsaverage_den-164k_hemi-L_feature.func.gii", + "rel_path": "beliveau2017/cumi101/fsaverage/", + "checksum": "e76c623cb51a28f2105d26dab0f2ebe0", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "638543ea1daa6b183975935a" + ] + }, { "source": "beliveau2017", "desc": "dasb", @@ -286,6 +412,48 @@ "6196cb1c0b0c1e03ca7fd263" ] }, + { + "source": "beliveau2017", + "desc": "dasb", + "space": "fsaverage", + "den": "164k", + "hemi": "R", + "format": "surface", + "fname": "source-beliveau2017_desc-dasb_space-fsaverage_den-164k_hemi-R_feature.func.gii", + "rel_path": "beliveau2017/dasb/fsaverage/", + "checksum": "e4921dcc6da907318ef47d7b15250b84", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "63854385c86e2818da88f94b" + ] + }, + { + "source": "beliveau2017", + "desc": "dasb", + "space": "fsaverage", + "den": "164k", + "hemi": "L", + "format": "surface", + "fname": "source-beliveau2017_desc-dasb_space-fsaverage_den-164k_hemi-L_feature.func.gii", + "rel_path": "beliveau2017/dasb/fsaverage/", + "checksum": "21fb41e524fbb5cdf2d60a3ffdd49712", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "63854394228a5a18987bc26e" + ] + }, { "source": "beliveau2017", "desc": "sb207145", @@ -306,6 +474,48 @@ "6196cb10bbe37803b559fe58" ] }, + { + "source": "beliveau2017", + "desc": "sb207145", + "space": "fsaverage", + "den": "164k", + "hemi": "R", + "format": "space", + "fname": "source-beliveau2017_desc-sb207145_space-fsaverage_den-164k_hemi-R_feature.func.gii", + "rel_path": "beliveau2017/sb207145/fsaverage/", + "checksum": "4bb6b0f54f2cdf3b3dba9e63cf3daa8d", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "638542b2a98e5f1ac2103866" + ] + }, + { + "source": "beliveau2017", + "desc": "sb207145", + "space": "fsaverage", + "den": "164k", + "hemi": "L", + "format": "space", + "fname": "source-beliveau2017_desc-sb207145_space-fsaverage_den-164k_hemi-L_feature.func.gii", + "rel_path": "beliveau2017/sb207145/fsaverage/", + "checksum": "5520fb0ed11a4037b22de7b63fa9704b", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "638542c2c86e2818d588f461" + ] + }, { "source": "ding2010", "desc": "mrb", @@ -1533,13 +1743,13 @@ ] }, { - "source": "norgaard2020", + "source": "norgaard2021", "desc": "flumazenil", "space": "MNI152", "res": "1mm", "format": "volume", - "fname": "source-norgaard2020_desc-flumazenil_space-MNI152_res-1mm_feature.nii.gz", - "rel_path": "norgaard2020/flumazenil/MNI152/", + "fname": "source-norgaard2021_desc-flumazenil_space-MNI152_res-1mm_feature.nii.gz", + "rel_path": "norgaard2021/flumazenil/MNI152/", "checksum": "e4eab79ed371d7362741f66bb44388d8", "title": null, "tags": [ @@ -1549,7 +1759,49 @@ "redir": null, "url": [ "4mw3a", - "6196caeb0b0c1e03bf7fdd23" + "638553fe228a5a18d67bcac8" + ] + }, + { + "source": "norgaard2021", + "desc": "flumazenil", + "space": "fsaverage", + "den": "164k", + "hemi": "R", + "format": "surface", + "fname": "source-norgaard2021_desc-flumazenil_space-fsaverage_den-164k_hemi-R_feature.func.gii", + "rel_path": "norgaard2021/flumazenil/fsaverage/", + "checksum": "4f711daa3327499295fb7e9b13552197", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "6385540d228a5a18d67bcadd" + ] + }, + { + "source": "norgaard2021", + "desc": "flumazenil", + "space": "fsaverage", + "den": "164k", + "hemi": "L", + "format": "surface", + "fname": "source-norgaard2021_desc-flumazenil_space-fsaverage_den-164k_hemi-L_feature.func.gii", + "rel_path": "norgaard2021/flumazenil/fsaverage/", + "checksum": "3735d34649c932a9eecce57ff688030c", + "title": null, + "tags": [ + "receptors", + "PET" + ], + "redir": null, + "url": [ + "4mw3a", + "638553fe228a5a18d67bcac8" ] }, {