{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Fetching atlases and annotations\n\nThis example demonstrates how to use :mod:`neuromaps.datasets` to fetch\natlases and annotations.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Much of the functionality of the ``neuromaps`` toolbox relies on the\natlases and atlas files provided with it. In many cases these atlases are\nfetched \"behind-the-scenes\" when you call functions that depend on them, but\nthey can be accessed directly.\n\nThere is a general purpose :func:`neuromaps.datasets.fetch_atlas`\nfunction that can fetch any of the atlases provided with ``neuromaps``:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from neuromaps import datasets\n\nfslr = datasets.fetch_atlas(atlas='fslr', density='32k')\nprint(fslr.keys())"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The values corresponding to the keys of the atlas dictionary are length-2\nlists containing filepaths to the downloaded data. All surface atlas files\nare provide in gifti format (whereas MNI files are in gzipped nifti format).\n\nYou can load them directly with ``nibabel`` to confirm their validity:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import nibabel as nib\nlsphere, rsphere = fslr['sphere']\nlvert, ltri = nib.load(lsphere).agg_data()\nprint(lvert.shape, ltri.shape)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The other datasets that are provided with ``neuromaps`` are annotations\n(i.e., brain maps!). While we are slowly making more and more of these openly\navailable, for now only a subset are accessible to the general public; these\nare returned by default via :func:`datasets.available_annotations`.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "annotations = datasets.available_annotations()\nprint(f'Available annotations: {len(annotations)}')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The :func:`~.available_annotations` function accepts a number of keyword\narguments that you can use to query specific datasets. For example, providing\nthe `format='volume`' argument will return only those annotations that\nare, by default, a volumetric image:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "volume_annotations = datasets.available_annotations(format='volume')\nprint(f'Available volumetric annotations: {len(volume_annotations)}')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "There are a number of keyword arguments we can specify to reduce the scope of\nthe annotations returned. Here, `source` specifies where the annotation came\nfrom (i.e., a dataset from a manuscript or a data repository or toolbox),\n`desc` refers to a brief description of the annotation, `space` clarifies\nwhich space the annotation is in, and `den` (specific to surface annotations)\nclarifies the density of the surface on which the annotation is defined:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "annot = datasets.available_annotations(source='abagen', desc='genepc1',\n                                       space='fsaverage', den='10k')\nprint(annot)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Annotations also have tags to help sort them into categories. You can see\nwhat tags can be used to query annotations with the :func:`~.available_tags`\nfunctions:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "tags = datasets.available_tags()\nprint(tags)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Tags can be used as a keyword argumnet with :func:`~.available_annotations`.\nYou can supply either a single tag or a list of tags. Note that supplying a\nlist will only return those annotations that match ALL supplied tags:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fmri_annotations = datasets.available_annotations(tags='fMRI')\nprint(fmri_annotations)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Once we have an annotation that we want we can use the\n:func:`neuromaps.datasets.fetch_annotation` to actually download the\nfiles. This has a very similar signature to the\n:func:`~.available_annotations` function, accepting almost all the same\nkeyword arguments to specify which annotations are desired.\n\nHere, we'll grab the first principal component of gene expression across the\nbrain (from the Allen Human Brain Atlas):\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "abagen = datasets.fetch_annotation(source='abagen', desc='genepc1')\nprint(abagen)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Notice that the returned annotation ``abagen`` is a dictionary. We can subset\nthe dictionary with the appropriate key or, if we know that our query is\ngoing to return only one annotation, also provide the `return_single=True`\nargument to the fetch call:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "abagen = datasets.fetch_annotation(source='abagen', desc='genepc1',\n                                   return_single=True)\nprint(abagen)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "And that's it! This example provided a quick overview on how to fetch the\nvarious atlases and datasets provided with ``neuromaps``. For more\ninformation please refer to the `API reference <ref_datasets>`.\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.7.9"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}