Add documentation to MultiGraphics

src/sage/plot/graphics.py

@@ -17,7 +17,7 @@
 
 - Eric Gourgoulhon (2015-03-19): Add parameter axes_labels_size (:trac:`18004`)
 
-- Eric Gourgoulhon (2019-05-18): :class:`~sage.plot.multigraphics.GraphicsArray`
+- Eric Gourgoulhon (2019-05-24): :class:`~sage.plot.multigraphics.GraphicsArray`
   moved to new module :mod:`~sage.plot.multigraphics`; various improvements and
   fixes in :meth:`Graphics.matplotlib` and ``Graphics._set_scale``; new method
   :meth:`Graphics.inset`

src/sage/plot/multigraphics.py

@@ -11,7 +11,7 @@
 
 AUTHORS:
 
-- Eric Gourgoulhon (2019-05-14): initial version, refactoring the class
+- Eric Gourgoulhon (2019-05-24): initial version, refactoring the class
   ``GraphicsArray`` that was defined in the module :mod:`~sage.plot.graphics`.
 
 """
@@ -44,7 +44,7 @@ class MultiGraphics(WithEqualityById, SageObject):
 
       - a pair ``(graphics, position)``, where ``graphics`` is a
         :class:`~sage.plot.graphics.Graphics` object and ``position`` is the
-        4-tupe ``(left, bottom, width, height)`` specifying the location and
+        4-tuple ``(left, bottom, width, height)`` specifying the location and
         size of the graphics on the canvas, all quantities being in fractions
         of the canvas width and height
 
@@ -514,7 +514,7 @@ def save_image(self, filename=None, *args, **kwds):
 
         EXAMPLES::
 
-            sage: plots = [[plot(m*cos(x + n*pi/4), (x,0, 2*pi))
+            sage: plots = [[plot(m*cos(x + n*pi/4), (x, 0, 2*pi))
             ....:           for n in range(3)] for m in range(1,3)]
             sage: G = graphics_array(plots)
             sage: G.save_image(tmp_filename(ext='.png'))
@@ -647,10 +647,11 @@ def inset(self, graphics, pos=None, fontsize=None):
         - ``graphics`` -- the graphics object (instance of :class:`Graphics`)
           to be added as an inset
 
-        - ``pos`` -- (default: ``None``) 4-tupe ``(left, bottom, width, height)``
-          specifying the location and relative size of the inset on the canvas,
-          all quantities being expressed in fractions of the canvas width and
-          height; if ``None``, the value ``(0.70, 068, 0.2, 0.2)`` is used
+        - ``pos`` -- (default: ``None``) 4-tuple
+          ``(left, bottom, width, height)`` specifying the location and
+          relative size of the inset on the canvas, all quantities being
+          expressed in fractions of the canvas width and height; if ``None``,
+          the value ``(0.70, 068, 0.2, 0.2)`` is used
 
         - ``fontsize`` -- (default: ``None``)  integer, font size (in points)
           for the inset; if ``None``, the value of 6 points is used, unless
@@ -764,6 +765,33 @@ def _add_subplot(self, figure, index, **options):
 
         - a Matplotlib ``Axes`` object
 
+        EXAMPLES::
+
+            sage: g0 = circle((0,0), 1)
+            sage: g1 = plot(sin)
+            sage: G = multi_graphics([g0, (g1, (0.2, 0.3, 0.4, 0.1))])
+            sage: from matplotlib.figure import Figure
+            sage: fig = Figure()
+            sage: fig
+            <Figure size 640x480 with 0 Axes>
+            sage: ax0 = G._add_subplot(fig, 0)
+            sage: type(ax0)
+            <class 'matplotlib.axes._axes.Axes'>
+            sage: fig
+            <Figure size 640x480 with 1 Axes>
+            sage: ax1 = G._add_subplot(fig, 1)
+            sage: fig
+            <Figure size 640x480 with 2 Axes>
+
+        TESTS::
+
+            sage: [ax0, ax1] == fig.get_axes()
+            True
+            sage: G.position(1)
+            (0.2, 0.3, 0.4, 0.1)
+            sage: ax1.get_position().bounds  # tol 1.0e-13
+            (0.2, 0.3, 0.4000000000000001, 0.10000000000000003)
+
         """
         # Note: using label=str(index) ensures that a new Axes is generated
         # for each element of ``self``, even if some elements share the same
@@ -808,13 +836,79 @@ def append(self, graphics, pos=None):
         - ``graphics`` -- the graphics object (instance of :class:`Graphics`)
           to be added to ``self``
 
-        - ``pos`` -- (default: ``None``) 4-tupe ``(left, bottom, width, height)``
-          specifying the location and size of ``graphics`` on the canvas, all
-          quantities being in fractions of the canvas width and height; if
-          ``None``, ``graphics`` is assumed to occupy the whole canvas, except
-          for some padding; this corresponds to the default position
+        - ``pos`` -- (default: ``None``) 4-tuple
+          ``(left, bottom, width, height)`` specifying the location and size
+          of ``graphics`` on the canvas, all quantities being in fractions of
+          the canvas width and height; if ``None``, ``graphics`` is assumed to
+          occupy the whole canvas, except for some padding; this corresponds to
+          the default position
           ``(left, bottom, width, height) = (0.125, 0.11, 0.775, 0.77)``
 
+        EXAMPLES:
+
+        Let us consider a multigraphics with 2 elements::
+
+            sage: g1 = plot(chebyshev_T(4, x), (x, -1, 1), title='n=4')
+            sage: g2 = plot(chebyshev_T(8, x), (x, -1, 1), title='n=8',
+            ....:           color='red')
+            sage: G = multi_graphics([(g1, (0.125, 0.2, 0.4, 0.4)),
+            ....:                     (g2, (0.55, 0.4, 0.4, 0.4))])
+            sage: G
+            Multigraphics with 2 elements
+
+        .. PLOT::
+
+            g1 = plot(chebyshev_T(4, x), (x, -1, 1), title='n=4')
+            g2 = plot(chebyshev_T(8, x), (x, -1, 1), title='n=8', color='red')
+            G = multi_graphics([(g1, (0.125, 0.2, 0.4, 0.4)), \
+                                (g2, (0.55, 0.4, 0.4, 0.4))])
+            sphinx_plot(G)
+
+        We append a third plot to it::
+
+            sage: g3 = plot(chebyshev_T(16, x), (x, -1, 1), title='n=16',
+            ....:           color='brown')
+            sage: G.append(g3, pos=(0.55, 0.11, 0.4, 0.15))
+            sage: G
+            Multigraphics with 3 elements
+
+        .. PLOT::
+
+            g1 = plot(chebyshev_T(4, x), (x, -1, 1), title='n=4')
+            g2 = plot(chebyshev_T(8, x), (x, -1, 1), title='n=8', color='red')
+            G = multi_graphics([(g1, (0.125, 0.2, 0.4, 0.4)), \
+                                (g2, (0.55, 0.4, 0.4, 0.4))])
+            g3 = plot(chebyshev_T(16, x), (x, -1, 1), title='n=16', \
+                      color='brown')
+            G.append(g3, pos=(0.55, 0.11, 0.4, 0.15))
+            sphinx_plot(G)
+
+        We may use ``append`` to add a title::
+
+            sage: title = text("Chebyshev polynomials", (0, 0), fontsize=16,
+            ....:              axes=False)
+            sage: G.append(title, pos=(0.18, 0.8, 0.7, 0.1))
+            sage: G
+            Multigraphics with 4 elements
+
+        .. PLOT::
+
+            g1 = plot(chebyshev_T(4, x), (x, -1, 1), title='n=4')
+            g2 = plot(chebyshev_T(8, x), (x, -1, 1), title='n=8', color='red')
+            G = multi_graphics([(g1, (0.125, 0.2, 0.4, 0.4)), \
+                                (g2, (0.55, 0.4, 0.4, 0.4))])
+            g3 = plot(chebyshev_T(16, x), (x, -1, 1), title='n=16', \
+                      color='brown')
+            G.append(g3, pos=(0.55, 0.11, 0.4, 0.15))
+            title = text("Chebyshev polynomials", (0, 0), fontsize=16, \
+                         axes=False)
+            G.append(title, pos=(0.18, 0.8, 0.7, 0.1))
+            sphinx_plot(G)
+
+        .. SEEALSO::
+
+            :meth:`inset`
+
         """
         from matplotlib import rcParams
         if not isinstance(graphics, Graphics):
@@ -1081,6 +1175,7 @@ def __str__(self):
             'Graphics Array of size 2 x 3'
             sage: str(G)
             'Graphics Array of size 2 x 3'
+
         """
         return "Graphics Array of size {} x {}".format(self._rows, self._cols)
 
@@ -1107,12 +1202,12 @@ def _add_subplot(self, figure, index, **options):
             sage: c = circle((0,0), 1)
             sage: G = graphics_array([c, c])
             sage: from matplotlib.figure import Figure
-            sage: figure = Figure()
-            sage: ax1 = G._add_subplot(figure, 0)
+            sage: fig = Figure()
+            sage: ax1 = G._add_subplot(fig, 0)
             sage: type(ax1)
             <class 'matplotlib.axes._subplots.AxesSubplot'>
-            sage: ax2 = G._add_subplot(figure, 1)
-            sage: figure.get_axes() == [ax1, ax2]
+            sage: ax2 = G._add_subplot(fig, 1)
+            sage: fig.get_axes() == [ax1, ax2]
             True
 
         """
@@ -1222,4 +1317,3 @@ def position(self, index):
             axes = figure.get_axes()
             self._positions = [ax.get_position().bounds for ax in axes]
         return self._positions[index]
-

src/sage/plot/plot.py

@@ -257,10 +257,10 @@
 
     sage: L = [[cos(pi*i/100)^3,sin(pi*i/100)] for i in range(200)]
     sage: p = line(L, rgbcolor=(1/4,1/8,3/4))
-    sage: t = text('A Bulb', (1.5, 0.25))
-    sage: x = text('x axis', (1.5,-0.2))
-    sage: y = text('y axis', (0.4,0.9))
-    sage: g = p+t+x+y
+    sage: tt = text('A Bulb', (1.5, 0.25))
+    sage: tx = text('x axis', (1.5,-0.2))
+    sage: ty = text('y axis', (0.4,0.9))
+    sage: g = p + tt + tx + ty
     sage: g.show(xmin=-1.5, xmax=2, ymin=-1, ymax=1)
 
 .. PLOT::
@@ -277,9 +277,23 @@
     g.ymax(1)
     sphinx_plot(g)
 
+We can add a graphics object to another one as an inset::
+
+    sage: g1 = plot(x^2*sin(1/x), (x, -2, 2), axes_labels=['$x$', '$y$'])
+    sage: g2 = plot(x^2*sin(1/x), (x, -0.3, 0.3), axes_labels=['$x$', '$y$'],
+    ....:           frame=True)
+    sage: g1.inset(g2, pos=(0.18, 0.68, 0.25, 0.25))
+    Multigraphics with 2 elements
+
+.. PLOT::
+
+    g1 = plot(x**2*sin(1/x), (x, -2, 2), axes_labels=['$x$', '$y$'])
+    g2 = plot(x**2*sin(1/x), (x, -0.3, 0.3), axes_labels=['$x$', '$y$'], \
+              frame=True)
+    sphinx_plot(g1.inset(g2, pos=(0.18, 0.68, 0.25, 0.25)))
+
 We can add a title to a graph::
 
-    sage: x = var('x')
     sage: plot(x^2, (x,-2,2), title='A plot of $x^2$')
     Graphics object consisting of 1 graphics primitive
 
@@ -545,6 +559,8 @@ def f(x): return (x-3)*(x-5)*(x-7)+40
 - Aaron Lauve (2016-07-13): reworked handling of 'color' when passed
   a list of functions; now more in-line with other CAS's. Added list functionality
   to linestyle and legend_label options as well. (:trac:`12962`)
+
+- Eric Gourgoulhon (2019-04-24): add :func:`multi_graphics` and insets
 """
 #*****************************************************************************
 #       Copyright (C) 2006 Alex Clemesha <clemesha@gmail.com>