Merge branch 'docs' into develop

Author: GaelleChapuis

examples/atlas/atlas_swanson_flatmap.ipynb

@@ -30,13 +30,116 @@
    "outputs": [],
    "source": [
     "import numpy as np\n",
-    "from ibllib.atlas.flatmaps import plot_swanson\n",
+    "from ibllib.atlas.flatmaps import swanson, plot_swanson\n",
     "from ibllib.atlas import BrainRegions\n",
+    "\n",
     "br = BrainRegions()\n",
     "\n",
-    "plot_swanson(br=br, annotate=True)\n"
+    "# Plot Swanson map will default colors and acronyms\n",
+    "plot_swanson(br=br, annotate=True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "### What regions are represented in the Swanson flatmap"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "The Swanson map holds 318 brain region acronyms, some of which are an aggregate of distinct brain regions in the Allen or Beryl parcellation.\n",
+    "To find the acronyms of the regions represented in Swanson, use:"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "swanson_ac = np.sort(br.acronym[np.unique(swanson())])"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Regions which are \"children\" of a Swanson region will not be included in the acronyms. For example `PTLp` is in Swanson, but its children `VISa` and `VISrl`(i.e. a finer parcellation of `PTLp`) are not:"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "# Example: Check if PTLp is in Swanson\n",
+    "np.isin(['PTLp'], swanson_ac)\n",
+    "# Example: Check if VISa and VISrl are in Swanson\n",
+    "np.isin(['VISa', 'VISrl'], swanson_ac)"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "As such, you can only plot value for a given region that is in Swanson. This was done to ensure there is no confusion about how data is aggregated and represented per region (for example, if you were to input values for both `VISa` and `VISrl`, it is unclear whether the mean, median or else should have been plotted onto the `PTLp` area - instead, we ask you to do the aggregation yourself and pass this into the plotting function).\n",
+    "\n",
+    "For example,"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "from ibllib.atlas.flatmaps import plot_swanson_vector\n",
+    "\n",
+    "# 'PTLp', 'CA1', 'VPM' as in Swanson and all 3 are plotted\n",
+    "acronyms = ['PTLp', 'CA1', 'VPM']\n",
+    "values = np.array([1.5, 3, 4])\n",
+    "plot_swanson_vector( acronyms, values, annotate=True, annotate_list=['PTLp', 'CA1', 'VPM'],empty_color='silver')\n",
+    "\n",
+    "# 'VISa','VISrl' are not in Swanson, only 'CA1', 'VPM' are plotted\n",
+    "acronyms = ['VISa','VISrl', 'CA1', 'VPM']\n",
+    "values = np.array([1, 2, 3, 4])\n",
+    "plot_swanson_vector( acronyms, values, annotate=True, annotate_list=['VISa','VISrl', 'CA1', 'VPM'],empty_color='silver')\n"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [],
+   "metadata": {
+    "collapsed": false
+   }
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -180,4 +283,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 1
-}
+}