docs/subplots.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Subplots features"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Automatic layout"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "By default, ProPlot *automatically* determines the suitable figure width and height for your subplot grid. The figure dimensions are constrained by the dimensions of the *reference* subplot. In practice, this usually sets the properties for *all* subplots, unless your subplots have different aspect ratios or your subplot grid is very complex.\n",
    "\n",
    "This feature is controlled by a variety of `~proplot.subplots.subplots` keyword arguments.\n",
    "\n",
    "* To set the reference subplot, use `ref` (default is ``1``, i.e. the subplot in the upper left corner). To set the refernce subplot aspect ratio, use `aspect` (default is ``1``).\n",
    "* If you use *either* `axwidth` or `axheight`, both figure dimensions are determined automatically and the reference subplot aspect ratio is preserved (default is ``axwidth=2``).\n",
    "* If you use *either* `width` or `height`, the other figure dimension is determined automatically and the reference subplot aspect ratio is preserved.\n",
    "* If you use *both* `width` and `height` (or `figsize`, which is a ``(width, height)`` tuple), the figure dimensions are fixed and the reference subplot aspect ratio is *not* preserved.\n",
    "* When the `ref` subplot `aspect ratio mode <https://matplotlib.org/2.0.2/examples/pylab_examples/equal_aspect_ratio.html>`__ is set to ``'equal'``, as with :ref:`Geographic and polar plots` and `~matplotlib.axes.Axes.imshow` plots, the existing aspect will be used instead of the input `aspect`.\n",
    "\n",
    "By default, ProPlot also applies a *tight layout* algorithm to every figure. This algorithm automatically adjusts the space between subplot rows and columns and the figure edge to accomadate labels.\n",
    "Matplotlib has `its own tight layout algorithm <https://matplotlib.org/3.1.1/tutorials/intermediate/tight_layout_guide.html>`__,\n",
    "but ProPlot's algorithm may change the figure dimensions (depending on the keyword arguments you passed to `~proplot.subplots.subplots`) and permits *variable spacing* between subsequent subplot rows and columns, thanks to the new `~proplot.subplots.GridSpec` class.\n",
    "\n",
    "ProPlot's tight layout algorithm can also be easily overridden. When you pass a spacing argument like `left`, `right`, `top`, `bottom`, `wspace`, or `hspace` to `~proplot.subplots.subplots`, that value is *always respected*.\n",
    "\n",
    "* If you pass ``left='2em'`` to `~proplot.subplots.subplots`, the left margin is fixed but the right, bottom, and top margins are determined automatically.\n",
    "* If you pass ``wspace=('3em', None)`` and ``ncols=3`` to `~proplot.subplots.subplots`, the space between the first two columns is fixed, while the space between the second two columns is determined automatically.\n",
    "\n",
    "The below examples are *stress tests* of the tight layout algorithm and demonstrate how \"reference axes\" affect the figure appearence. Note that since ProPlot colorbar and panel widths are specified in physical units, they are held fixed during resizing. This helps us avoid colorbars that look \"too skinny\" or \"too fat\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import proplot as plot\n",
    "for ref in (1, 2):\n",
    "    f, axs = plot.subplots(\n",
    "        ref=ref, nrows=3, ncols=3, wratios=(3, 2, 2),\n",
    "        axwidth=1.1, share=0)\n",
    "    axs[ref-1].format(\n",
    "        title='reference axes', titleweight='bold',\n",
    "        titleloc='uc', titlecolor='red9')\n",
    "    axs[4].format(\n",
    "        title='title\\ntitle\\ntitle',\n",
    "        suptitle='Tight layout with simple grids')\n",
    "    axs[1].format(ylabel='ylabel\\nylabel\\nylabel')\n",
    "    axs[:4:2].format(xlabel='xlabel\\nxlabel\\nxlabel')\n",
    "    axs.format(rowlabels=['Row 1', 'Row 2', 'Row 3'],\n",
    "               collabels=['Column 1', 'Column 2', 'Column 3'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import proplot as plot\n",
    "for ref in (4, 2):\n",
    "    f, axs = plot.subplots(\n",
    "        [[1, 1, 2], [3, 3, 2], [4, 5, 5], [4, 6, 6]],\n",
    "        hratios=(1, 1, 2, 2), wratios=(3, 2, 3),\n",
    "        ref=ref, axwidth=1.1, span=False)\n",
    "    axs[ref-1].format(\n",
    "        title='reference axes', titleweight='bold',\n",
    "        titleloc='uc', titlecolor='red9')\n",
    "    axs.format(xlabel='xlabel', ylabel='ylabel', suptitle='Super title')\n",
    "    axs[0].format(xlabel='xlabel\\nxlabel\\nxlabel')\n",
    "    axs[1].format(\n",
    "        ylabel='ylabel\\nylabel\\nylabel', ytickloc='both',\n",
    "        yticklabelloc='both', ctitle='Title')\n",
    "    axs[2:4].format(\n",
    "        yformatter='null', ctitle='Title',\n",
    "        ytickloc='both', yticklabelloc='both')\n",
    "    axs[4:].format(yformatter='null', xlabel='xlabel\\nxlabel\\nxlabel')\n",
    "    axs.format(suptitle='Tight layout with complex grids', rowlabels=[\n",
    "               'Row 1', 'Row 2', 'Row 3'], collabels=['Column 1', 'Column 2'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Arbitrary physical units"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "ProPlot supports *arbitrary physical units* for controlling the figure `width` and `height`; the reference subplot `axwidth` and `axheight`; the gridspec spacing values `left`, `right`, `bottom`, `top`, `wspace`, and `hspace`; and in a few other places.\n",
    "\n",
    "If a sizing argument is numeric, the units are inches or points, and if string, the units are interpreted by `~proplot.utils.units`. A table of acceptable units is found in the `~proplot.utils.units` documentation. They include centimeters, millimeters, pixels, `em-heights <https://en.wikipedia.org/wiki/Em_(typography)>`__, and `points <https://en.wikipedia.org/wiki/Point_(typography)>`__."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import proplot as plot\n",
    "import numpy as np\n",
    "with plot.rc.context(small='12px', large='15px', linewidth='0.5mm'):\n",
    "    f, axs = plot.subplots(\n",
    "        ncols=3, width='13cm', height='2in',\n",
    "        wspace=('10pt', '20pt'), right='10mm')\n",
    "panel = axs[2].panel_axes('r', width='2em')\n",
    "axs.format(suptitle='Arguments with arbitrary units',\n",
    "           xlabel='x axis', ylabel='y axis')\n",
    "plot.rc.reset()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Subplot numbers and labels"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "ProPlot assigns unique numbers to subplots. The number order determines the order the subplots appear in the `~proplot.subplots.subplot_grid` and the order of \"a-b-c\" labels generated by `~proplot.axes.Axes.format`. If you did not provide a 2D array, the number order is row-major by default but can be made column-major by passing ``order='F'`` to `~proplot.subplots.subplots`. The \"a-b-c\" label position and style can be changed with `~proplot.axes.Axes.format`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import proplot as plot\n",
    "f, axs = plot.subplots(nrows=8, ncols=8, axwidth=0.7, space=0)\n",
    "axs.format(abc=True, abcloc='ur', xlabel='x axis', ylabel='y axis',\n",
    "           xticks=[], yticks=[], suptitle='Flush subplot grid')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Shared and spanning labels"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Matplotlib has an \"axis sharing\" feature that holds axis limits the same for axes within a grid of subplots. But this has no effect on the axis labels and tick labels, which can lead to lots of redundancies.\n",
    "\n",
    "To help you eliminate these redundancies, ProPlot introduces *four axis-sharing options* and a new *spanning label option*, controlled by the `share`, `sharex`, `sharey`, `span`, `spanx`, and `spany` `~proplot.subplots.subplots` keyword args. \"Sharing level\" ``1`` hides inner *x* and *y* axis labels. \"Sharing level\" ``2`` is the same as ``1``, but the *x* and *y* axis limits are locked. \"Sharing level\" ``3`` is the same as ``2``, but the *x* and *y* tick labels are hidden. \"Spanning labels\" are centered *x* and *y* axis labels used for subplots whose spines are on the same row or column. See the below example.\n",
    "\n",
    "Note that the the \"shared\" and \"spanning\" axes are determined automatically based on the extent of each subplot in the `~proplot.subplots.GridSpec`. Since ProPlot uses just one `~proplot.subplots.GridSpec` per figure, this can be done with zero ambiguity."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import proplot as plot\n",
    "import numpy as np\n",
    "N = 50\n",
    "M = 40\n",
    "state = np.random.RandomState(51423)\n",
    "colors = plot.Colors('grays_r', M, left=0.1, right=0.8)\n",
    "datas = []\n",
    "for scale in (1, 3, 7, 0.2):\n",
    "    data = scale * (state.rand(N, M) - 0.5).cumsum(axis=0)[N//2:, :]\n",
    "    datas.append(data)\n",
    "for share in (0, 1, 2, 3):\n",
    "    f, axs = plot.subplots(ncols=4, aspect=1, axwidth=1.2,\n",
    "                           sharey=share, spanx=share//2)\n",
    "    for ax, data in zip(axs, datas):\n",
    "        ax.plot(data, cycle=colors)\n",
    "        ax.format(suptitle=f'Axis-sharing level: {share}, spanning labels {[\"off\",\"on\"][share//2]}',\n",
    "                  grid=False, xlabel='spanning', ylabel='shared')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import proplot as plot\n",
    "import numpy as np\n",
    "plot.rc.reset()\n",
    "plot.rc.cycle = 'Set3'\n",
    "state = np.random.RandomState(51423)\n",
    "titles = ['With redundant labels', 'Without redundant labels']\n",
    "for mode in (0, 1):\n",
    "    f, axs = plot.subplots(nrows=4, ncols=4, share=3*mode,\n",
    "                           span=1*mode, axwidth=1)\n",
    "    for ax in axs:\n",
    "        ax.plot((state.rand(100, 20) - 0.4).cumsum(axis=0))\n",
    "    axs.format(\n",
    "        xlabel='xlabel', ylabel='ylabel', suptitle=titles[mode],\n",
    "        abc=mode, abcloc='ul',\n",
    "        grid=False, xticks=25, yticks=5)"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Raw Cell Format",
  "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.3"
  },
  "toc": {
   "colors": {
    "hover_highlight": "#ece260",
    "navigate_num": "#000000",
    "navigate_text": "#000000",
    "running_highlight": "#FF0000",
    "selected_highlight": "#fff968",
    "sidebar_border": "#ffffff",
    "wrapper_background": "#ffffff"
   },
   "moveMenuLeft": false,
   "nav_menu": {
    "height": "12px",
    "width": "250px"
   },
   "navigate_menu": true,
   "number_sections": true,
   "sideBar": true,
   "threshold": 4,
   "toc_cell": false,
   "toc_section_display": "block",
   "toc_window_display": true,
   "widenNotebook": false
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}