{
"cells": [
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": false
},
"outputs": [],
"source": [
"%matplotlib inline"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n\n# Overview of :mod:`mpl_toolkits.axes_grid1`\n\n:mod:`.axes_grid1` provides the following features:\n\n- Helper classes (ImageGrid_, RGBAxes_, AxesDivider_) to ease the layout of\n axes displaying images with a fixed aspect ratio while satisfying additional\n constraints (matching the heights of a colorbar and an image, or fixing the\n padding between images);\n- ParasiteAxes_ (twinx/twiny-like features so that you can plot different data\n (e.g., different y-scale) in a same Axes);\n- AnchoredArtists_ (custom artists which are placed at an anchored position,\n similarly to legends).\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png\n :target: ../../gallery/axes_grid1/demo_axes_grid.html\n :align: center\n\n## axes_grid1\n\n### ImageGrid\n\nIn Matplotlib, axes location and size are usually specified in normalized\nfigure coordinates (0 = bottom left, 1 = top right), which makes\nit difficult to achieve a fixed (absolute) padding between images.\n`~.axes_grid1.axes_grid.ImageGrid` can be used to achieve such a padding; see\nits docs for detailed API information.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axesgrid_001.png\n :target: ../../gallery/axes_grid1/simple_axesgrid.html\n :align: center\n\n* The position of each axes is determined at the drawing time (see\n AxesDivider_), so that the size of the entire grid fits in the\n given rectangle (like the aspect of axes). Note that in this example,\n the paddings between axes are fixed even if you change the figure\n size.\n\n* Axes in the same column share their x-axis, and axes in the same row share\n their y-axis (in the sense of `~.Axes.sharex`, `~.Axes.sharey`).\n Additionally, Axes in the same column all have the same width, and axes in\n the same row all have the same height. These widths and heights are scaled\n in proportion to the axes' view limits (xlim or ylim).\n\n .. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axesgrid2_001.png\n :target: ../../gallery/axes_grid1/simple_axesgrid2.html\n :align: center\n\nThe examples below show what you can do with ImageGrid.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png\n :target: ../../gallery/axes_grid1/demo_axes_grid.html\n :align: center\n\n### AxesDivider Class\n\nBehind the scenes, ImageGrid (and RGBAxes, described below) rely on\n`~.axes_grid1.axes_divider.AxesDivider`, whose role is to calculate the\nlocation of the axes at drawing time.\n\nUsers typically do not need to directly instantiate dividers\nby calling `~.axes_grid1.axes_divider.AxesDivider`; instead,\n`~.axes_grid1.axes_divider.make_axes_locatable` can be used to create a divider\nfor an Axes::\n\n ax = subplot(1, 1, 1)\n divider = make_axes_locatable(ax)\n\n`.AxesDivider.append_axes` can then be used to create a new axes on a given\nside (\"left\", \"right\", \"top\", \"bottom\") of the original axes.\n\n### colorbar whose height (or width) is in sync with the main axes\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_colorbar_001.png\n :target: ../../gallery/axes_grid1/simple_colorbar.html\n :align: center\n\n#### scatter_hist.py with AxesDivider\n\nThe :doc:`/gallery/lines_bars_and_markers/scatter_hist` example can be\nrewritten using `~.axes_grid1.axes_divider.make_axes_locatable`::\n\n axScatter = plt.subplot()\n axScatter.scatter(x, y)\n axScatter.set_aspect(1.)\n\n # create new axes on the right and on the top of the current axes.\n divider = make_axes_locatable(axScatter)\n axHistx = divider.append_axes(\"top\", size=1.2, pad=0.1, sharex=axScatter)\n axHisty = divider.append_axes(\"right\", size=1.2, pad=0.1, sharey=axScatter)\n\n # the scatter plot:\n # histograms\n bins = np.arange(-lim, lim + binwidth, binwidth)\n axHistx.hist(x, bins=bins)\n axHisty.hist(y, bins=bins, orientation='horizontal')\n\nSee the full source code below.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_scatter_hist_locatable_axes_001.png\n :target: ../../gallery/axes_grid1/scatter_hist_locatable_axes.html\n :align: center\n\nThe :doc:`/gallery/axes_grid1/scatter_hist_locatable_axes` using the\nAxesDivider has some advantages over the\noriginal :doc:`/gallery/lines_bars_and_markers/scatter_hist` in Matplotlib.\nFor example, you can set the aspect ratio of the scatter plot, even with the\nx-axis or y-axis is shared accordingly.\n\n### ParasiteAxes\n\nThe ParasiteAxes is an Axes whose location is identical to its host\naxes. The location is adjusted in the drawing time, thus it works even\nif the host change its location (e.g., images).\n\nIn most cases, you first create a host axes, which provides a few\nmethods that can be used to create parasite axes. They are ``twinx``,\n``twiny`` (which are similar to ``twinx`` and ``twiny`` in the matplotlib) and\n``twin``. ``twin`` takes an arbitrary transformation that maps between the\ndata coordinates of the host axes and the parasite axes. The ``draw``\nmethod of the parasite axes are never called. Instead, host axes\ncollects artists in parasite axes and draws them as if they belong to\nthe host axes, i.e., artists in parasite axes are merged to those of\nthe host axes and then drawn according to their zorder. The host and\nparasite axes modifies some of the axes behavior. For example, color\ncycle for plot lines are shared between host and parasites. Also, the\nlegend command in host, creates a legend that includes lines in the\nparasite axes. To create a host axes, you may use ``host_subplot`` or\n``host_axes`` command.\n\n#### Example 1. twinx\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_parasite_simple_001.png\n :target: ../../gallery/axes_grid1/parasite_simple.html\n :align: center\n\n#### Example 2. twin\n\n``twin`` without a transform argument assumes that the parasite axes has the\nsame data transform as the host. This can be useful when you want the\ntop(or right)-axis to have different tick-locations, tick-labels, or\ntick-formatter for bottom(or left)-axis. ::\n\n ax2 = ax.twin() # now, ax2 is responsible for \"top\" axis and \"right\" axis\n ax2.set_xticks([0., .5*np.pi, np.pi, 1.5*np.pi, 2*np.pi],\n labels=[\"0\", r\"$\\frac{1}{2}\\pi$\",\n r\"$\\pi$\", r\"$\\frac{3}{2}\\pi$\", r\"$2\\pi$\"])\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axisline4_001.png\n :target: ../../gallery/axes_grid1/simple_axisline4.html\n :align: center\n\nA more sophisticated example using twin. Note that if you change the\nx-limit in the host axes, the x-limit of the parasite axes will change\naccordingly.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_parasite_simple2_001.png\n :target: ../../gallery/axes_grid1/parasite_simple2.html\n :align: center\n\n### AnchoredArtists\n\n:mod:`.axes_grid1.anchored_artists` is a collection of artists whose location\nis anchored to the (axes) bbox, similarly to legends. These artists derive\nfrom `.offsetbox.OffsetBox`, and the artist need to be drawn in canvas\ncoordinates. There is limited support for arbitrary transforms. For example,\nthe ellipse in the example below will have width and height in data coordinates.\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_anchored_artists_001.png\n :target: ../../gallery/axes_grid1/simple_anchored_artists.html\n :align: center\n\n### InsetLocator\n\n.. seealso::\n `.Axes.inset_axes` and `.Axes.indicate_inset_zoom` in the main library.\n\n:mod:`.axes_grid1.inset_locator` provides helper classes and functions to\nplace inset axes at an anchored position of the parent axes, similarly to\nAnchoredArtist.\n\n`.inset_locator.inset_axes` creates an inset axes whose size is either fixed,\nor a fixed proportion of the parent axes::\n\n inset_axes = inset_axes(parent_axes,\n width=\"30%\", # width = 30% of parent_bbox\n height=1., # height = 1 inch\n loc='lower left')\n\ncreates an inset axes whose width is 30% of the parent axes and whose\nheight is fixed at 1 inch.\n\n`.inset_locator.zoomed_inset_axes` creates an inset axes whose data scale is\nthat of the parent axes multiplied by some factor, e.g. ::\n\n inset_axes = zoomed_inset_axes(ax,\n 0.5, # zoom = 0.5\n loc='upper right')\n\ncreates an inset axes whose data scale is half of the parent axes. This can be\nuseful to mark the zoomed area on the parent axes:\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_inset_locator_demo_001.png\n :target: ../../gallery/axes_grid1/inset_locator_demo.html\n :align: center\n\n`.inset_locator.mark_inset` allows marking the location of the area represented\nby the inset axes:\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_inset_locator_demo2_001.png\n :target: ../../gallery/axes_grid1/inset_locator_demo2.html\n :align: center\n\n### RGBAxes\n\nRGBAxes is a helper class to conveniently show RGB composite\nimages. Like ImageGrid, the location of axes are adjusted so that the\narea occupied by them fits in a given rectangle. Also, the xaxis and\nyaxis of each axes are shared. ::\n\n from mpl_toolkits.axes_grid1.axes_rgb import RGBAxes\n\n fig = plt.figure()\n ax = RGBAxes(fig, [0.1, 0.1, 0.8, 0.8], pad=0.0)\n r, g, b = get_rgb() # r, g, b are 2D images.\n ax.imshow_rgb(r, g, b)\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_rgb_001.png\n :target: ../../gallery/axes_grid1/demo_axes_rgb.html\n :align: center\n\n## AxesDivider\n\nThe :mod:`mpl_toolkits.axes_grid1.axes_divider` module provides helper classes\nto adjust the axes positions of a set of images at drawing time.\n\n* :mod:`~mpl_toolkits.axes_grid1.axes_size` provides a class of\n units that are used to determine the size of each axes. For example,\n you can specify a fixed size.\n\n* `~mpl_toolkits.axes_grid1.axes_divider.Divider` is the class that\n calculates the axes position. It divides the given rectangular area into\n several areas. The divider is initialized by setting the lists of horizontal\n and vertical sizes on which the division will be based. Then use\n :meth:`~mpl_toolkits.axes_grid1.axes_divider.Divider.new_locator`, which\n returns a callable object that can be used to set the axes_locator of the\n axes.\n\nHere, we demonstrate how to achieve the following layout: we want to position\naxes in a 3x4 grid (note that `.Divider` makes row indices start from the\n*bottom*\\(!) of the grid):\n\n```none\n+--------+--------+--------+--------+\n| (2, 0) | (2, 1) | (2, 2) | (2, 3) |\n+--------+--------+--------+--------+\n| (1, 0) | (1, 1) | (1, 2) | (1, 3) |\n+--------+--------+--------+--------+\n| (0, 0) | (0, 1) | (0, 2) | (0, 3) |\n+--------+--------+--------+--------+\n```\nsuch that the bottom row has a fixed height of 2 (inches) and the top two rows\nhave a height ratio of 2 (middle) to 3 (top). (For example, if the grid has\na size of 7 inches, the bottom row will be 2 inches, the middle row also 2\ninches, and the top row 3 inches.)\n\nThese constraints are specified using classes from the\n:mod:`~mpl_toolkits.axes_grid1.axes_size` module, namely::\n\n from mpl_toolkits.axes_grid1.axes_size import Fixed, Scaled\n vert = [Fixed(2), Scaled(2), Scaled(3)]\n\n(More generally, :mod:`~mpl_toolkits.axes_grid1.axes_size` classes define a\n``get_size(renderer)`` method that returns a pair of floats -- a relative size,\nand an absolute size. ``Fixed(2).get_size(renderer)`` returns ``(0, 2)``;\n``Scaled(2).get_size(renderer)`` returns ``(2, 0)``.)\n\nWe use these constraints to initialize a `.Divider` object::\n\n rect = [0.2, 0.2, 0.6, 0.6] # Position of the grid in the figure.\n vert = [Fixed(2), Scaled(2), Scaled(3)] # As above.\n horiz = [...] # Some other horizontal constraints.\n divider = Divider(fig, rect, horiz, vert)\n\nthen use `.Divider.new_locator` to create an `.AxesLocator` instance for a\ngiven grid entry::\n\n locator = divider.new_locator(nx=0, ny=1) # Grid entry (1, 0).\n\nand make it responsible for locating the axes::\n\n ax.set_axes_locator(locator)\n\nThe `.AxesLocator` is a callable object that returns the location and size of\nthe cell at the first column and the second row.\n\nLocators that spans over multiple cells can be created with, e.g.::\n\n # Columns #0 and #1 (\"0-2 range\"), row #1.\n locator = divider.new_locator(nx=0, nx1=2, ny=1)\n\nSee the example,\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider1_001.png\n :target: ../../gallery/axes_grid1/simple_axes_divider1.html\n :align: center\n\nYou can also adjust the size of each axes according to its x or y\ndata limits (AxesX and AxesY).\n\n.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider3_001.png\n :target: ../../gallery/axes_grid1/simple_axes_divider3.html\n :align: center\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.10.4"
}
},
"nbformat": 4,
"nbformat_minor": 0
}