{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# Tutorial 6: Regions and Parcellations\n\nThis tutorial demonstrates how to plot brain regions.\n\nRegions and parcellations can be plotted with ``brainplot`` as one or more \nlayers, and it's possible to add region outlines by simply adding a layer with\nthe `as_outline` parameter.\n\n## Parcellations\n\nMultiple brain regions can be plotted as a single layer as long as the vertices \nin different regions have different numerical labels/values, which is typical \nfor any parcelation. To demonstrate, we can use the \n:func:`~brainspace.datasets.load_parcellation` from ``Brainspace`` to load the\n`Schaefer 400 parcellation`_.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from neuromaps.datasets import fetch_fslr\nfrom surfplot import Plot\nfrom brainspace.datasets import load_parcellation\n\nsurfaces = fetch_fslr()\nlh, rh = surfaces['inflated']\np = Plot(lh, rh)\n\n# add schaefer parcellation (no color bar needed)\nlh_parc, rh_parc = load_parcellation('schaefer')\np.add_layer({'left': lh_parc, 'right': rh_parc}, cbar=False)\n\nfig = p.build()\nfig.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Now can add a second layer of just the region outlines. This is done by \nsetting `as_outline=True`. The color of the outlines are set by the `cmap` \nparameter, as with any data. To show black outlines, we can just use the \n`gray` colormap.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "p.add_layer({'left': lh_parc, 'right': rh_parc}, cmap='gray', \n            as_outline=True, cbar=False)\nfig = p.build()\nfig.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Regions of Interest\n\nOften times we want to show a selection of regions, instead of all regions. \nThese could be regions from a parcellation, regions defined from a \nfunctional localizer, etc. \n\nLet's select two regions from the Schaefer parcellation and zero-out the \nremaining regions. We'll just stick with the left hemisphere here.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import numpy as np\nregion_numbers = [71, 72]\n# zero-out all regions except 71 and 72\nregions = np.where(np.isin(lh_parc, region_numbers), lh_parc, 0)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Although we can use a pre-defined color map, we might want to define a \ncustom colormap where we can define the exact color for each region. This is\npossible using ``matplotlib``:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from matplotlib.colors import ListedColormap\n\ncolors = ['orange', 'steelblue']\ncmap = ListedColormap(colors, 'regions', N=2)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Now we can plot both regions with their outlines:\nonly need to show the left lateral view\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "p = Plot(lh, views='lateral')\np.add_layer(regions, cmap=cmap, cbar=False)\np.add_layer(regions, cmap='gray', as_outline=True, cbar=False)\n\nfig = p.build()\nfig.show()\n# sphinx_gallery_thumbnail_number = 3"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "<div class=\"alert alert-info\"><h4>Note</h4><p>Multiple regions can also be plotted as individual layers, rather\n  than combined as a single layer, as shown here. In this case, the vertex \n  array(s) for each layer would be binary.</p></div>\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.8.15"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}