{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# Tutorial 1: Quick Start\n\nThis tutorial gives a quick overview of ``surfplot`` before diving into more\ndetail in subsequent tutorials. The aim here is to get a flavour of how \n``surfplot`` works and what can be plotted. \n\n## Getting surfaces\n\nFirst, we need to get some brain surfaces. Here, we'll use the Conte69 Human \nConnectome Project surface (A.K.A `fsLR` surfaces). We can import and call the \n:func:`neuromaps.datasets.fetch_fslr` function, and then select the \n'inflated' surface, which will give the file paths of the left and right \nhemisphere GIFTI files:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from neuromaps.datasets import fetch_fslr\n\nsurfaces = fetch_fslr()\nlh, rh = surfaces['inflated']"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Making a plot\n\nBrain plots are created using the :class:`brainspace.plotting.Plot` class. We can \npass both of our surfaces to the `surf_lh` and `surf_rh` parameters. \nThese parameters accept file paths/names, or preloaded surfaces from \n:func:`brainspace.mesh.mesh_io.read_surface`. \n\nThen, we can call :func:`build` method to make the figure, which returns a\n``matplotlib`` figure, `fig`.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from surfplot import Plot\n\np = Plot(surf_lh=lh, surf_rh=rh)\nfig = p.build()\n# show figure, as you typically would with matplotlib\nfig.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Adding layers\nOnce the plot has been set up by instantiating the :class:`~brainspace.plotting.Plot` class, \nadding data is as simple as adding plotting layers using the \n:func:`~brainspace.plotting.Plot.add_layer` method. \n\nLet's first add some shading. We already have the Freesurfer sulc maps in \nour `surface` variable, which are accessed here with the 'sulc' key. \n\nWe can pass our sulc maps to the :func:`~brainspace.plotting.Plot.add_layer` \nmethod with the first positional parameter, `data`, which accepts either a \ndictionary with 'left' and 'right' keys, or a ``numpy`` array. \n`sphx_glr_auto_examples_plot_tutorial_03.py` covers what types \nof data can be passed to the `data` parameter.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "sulc_lh, sulc_rh = surfaces['sulc']\np.add_layer({'left': sulc_lh, 'right': sulc_rh}, cmap='binary_r', cbar=False)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Above, we've also used a grayscale colormap (`cmap`) and turned off the \ncolorbar (`cbar`) for this particular layer.\n\nNow, let's plot our updated figure:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fig = p.build()\nfig.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Finally, let's add some statistical data. We can load some example data \npackaged with ``surfplot`` using \n:func:`~surfplot.datasets.load_example_data`. By default, it loads an \n[association map of the term 'default mode' computed from Neurosynth](https://www.neurosynth.org/analyses/terms/default%20mode/). \nFor convenience, this map has already been projected from a volume in MNI152 \ncoordinates to a fsLR surface using ``neuromaps``, and the `lh_data`\nand `rh_data` variables are just numpy arrays of the vertices:  \n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from surfplot.datasets import load_example_data\nlh_data, rh_data = load_example_data()\nprint(lh_data)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We can add each array as a layer using a dictionary like before. By\ndefault a colorbar will be added for this layer, and its range is determined \nby the minimum and maximum values (this can be adjusted with the \n`color_range` parameter).\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "p.add_layer({'left': lh_data, 'right': rh_data}, cmap='YlOrRd_r')\nfig = p.build()\nfig.show()\n# sphinx_gallery_thumbnail_number = 3"
      ]
    }
  ],
  "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
}