{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\nTutorial 1: Building your first gradient\n=================================================\nIn this example, we will derive a gradient and do some basic inspections to\ndetermine which gradients may be of interest and what the multidimensional\norganization of the gradients looks like.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We\u2019ll first start by loading some sample data. Note that we\u2019re using\nparcellated data for computational efficiency.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from brainspace.datasets import load_group_fc, load_parcellation, load_conte69\n\n# First load mean connectivity matrix and Schaefer parcellation\nconn_matrix = load_group_fc('schaefer', scale=400)\nlabeling = load_parcellation('schaefer', scale=400, join=True)\n\n# and load the conte69 surfaces\nsurf_lh, surf_rh = load_conte69()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Let\u2019s first look at the parcellation scheme we\u2019re using.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from brainspace.plotting import plot_hemispheres\n\nplot_hemispheres(surf_lh, surf_rh, array_name=labeling, size=(1200, 200),\n                 cmap='tab20', zoom=1.85)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "and let\u2019s construct our gradients.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from brainspace.gradient import GradientMaps\n\n# Ask for 10 gradients (default)\ngm = GradientMaps(n_components=10, random_state=0)\ngm.fit(conn_matrix)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Note that the default parameters are diffusion embedding approach, 10\ncomponents, and no kernel (use raw data). Once you have your gradients, a\ngood first step is to simply inspect what they look like. Let\u2019s have a look\nat the first two gradients.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import numpy as np\n\nfrom brainspace.utils.parcellation import map_to_labels\n\nmask = labeling != 0\n\ngrad = [None] * 2\nfor i in range(2):\n    # map the gradient to the parcels\n    grad[i] = map_to_labels(gm.gradients_[:, i], labeling, mask=mask, fill=np.nan)\n\nplot_hemispheres(surf_lh, surf_rh, array_name=grad, size=(1200, 400), cmap='viridis_r',\n                 color_bar=True, label_text=['Grad1', 'Grad2'], zoom=1.55)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "But which gradients should you keep for your analysis? In some cases you may\nhave an a priori interest in some previously defined set of gradients. When\nyou do not have a pre-defined set, you can instead look at the lambdas\n(eigenvalues) of each component in a scree plot. Higher eigenvalues (or lower\nin Laplacian eigenmaps) are more important, so one can choose a cut-off based\non a scree plot.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import matplotlib.pyplot as plt\n\nfig, ax = plt.subplots(1, figsize=(5, 4))\nax.scatter(range(gm.lambdas_.size), gm.lambdas_)\nax.set_xlabel('Component Nb')\nax.set_ylabel('Eigenvalue')\n\nplt.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "This concludes the first tutorial. In the next tutorial we will have a look\nat how to customize the methods of gradient estimation, as well as gradient\nalignments.\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.6"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}