Refactor GraphicsArray, fixing various issues

[egourgoulhon]

This ticket makes GraphicsArray derive from a new class, MultiGraphics, which is more generic (arbitrary positions of graphics objects on a canvas) and paves the way towards graphics insets in #27866.

GraphicsArray is now endowed with a matplotlib() function (inheritated from MultiGraphics). This fixes the issues reported in #10466, #10657, #11160 and #12591 (see :comment:3 and comment:5 below for a summary).
Moreover, this simplifies sphinx_plot() (defined in src/doc/common/conf.py), avoiding code duplication.

Beside introducing matplotlib() at the graphics array level, two bugs had to be corrected in Graphics.matplotlib():

• _set_scale was called on the whole figure, while it should be called on the current subplot
• tick_params was called on figure.get_axes()[0], i.e. the first subplot of the figure, while it should be called on the current subplot.

The documentation of Graphics.matplotlib() is also improved in this ticket.

Another bug has been corrected in Graphics.save(): contrary to what was claimed in the documentation g.save("filename") with "filename" having no extension did not save in a sobj file but yielded to an error.

Another modification is the introduction of the helper function _parse_figsize() in src/sage/plot/graphics.py to avoid code duplication: it is used in Graphics.matplotlib(), MultiGraphics.matplotlib() and sphinx_plot().

Since the file src/sage/plot/graphics.py was already quite long (3736 lines!), the class GraphicsArray was moved to the new file src/sage/plot/multigraphics.py, which contains the definition of the base class MultiGraphics. This makes things more consistent:

• src/sage/plot/graphics.py: only Graphics objects
• src/sage/plot/multigraphics.py: only MultiGraphics objects

Besides the bugs reported in the tickets #10466, #10657, #11160 and #12591, this ticket fixes two other bugs:

• if any plot in the array had a log scale, the latter was erroneously applied to the first plot of the array

• the computation of nrows and ncols in the function graphics_array() (defined in src/sage/plot/plot.py) yielded unnecessary large numbers in certain cases. For instance we have in Sage 8.7:

sage: graphics_array([plot(sin)]*4, ncols=4)
Graphics Array of size 2 x 4

with the second raw that is entirely blank. With the code in this ticket the output is

Graphics Array of size 1 x 4

This fix explains the change of doctest outputs in src/sage/categories/finite_posets.py and src/sage/repl/rich_output/pretty_print.py

A preview (including the functionalities introduced in #27866) is available here.

CC: @kcrisman @fchapoton @dkrenn @jdemeyer @embray

Component: graphics

Keywords: graphics_array, matplotlib

Author: Eric Gourgoulhon

Branch/Commit: 36c0f17

Reviewer: Frédéric Chapoton

Issue created by migration from https://trac.sagemath.org/ticket/27865

[egourgoulhon]

Commit: 3a5ef55

[egourgoulhon]

Last 10 new commits:

4bbdf88	Add helper function _parse_figsize in module graphics and use it in matplotlib() methods of classes Graphics and MultiGraphics
788a53d	Add documentation in module multigraphics
7d61e86	Improve documentation of GraphicsArray
af6d312	More documentation in classes MultiGraphics and GraphicsArray
58b3ca3	Completed documentation of MultiGraphics and GraphicsArray
1bf8ad1	Small cleaning in MultiGraphics
ccff60c	Fix some doctests after the improved computation of nrows and ncols in graphics_array
26180ab	Some cleaning in MultiGraphics.matplotlib
3bd6a56	Minor cleaning in GraphicsArray
3a5ef55	Change index range in GraphicsArray._add_subplot()

[egourgoulhon]

Branch: public/graphics/multi_graphics

[egourgoulhon]

Author: Eric Gourgoulhon

[egourgoulhon]

Description changed:

--- 
+++ 
@@ -1,4 +1,4 @@
-This ticket makes `GraphicsArray` derive from a new class, `MultiGraphics`, which is more generic (arbitrary positions of graphics objects on a canvas) and paves the way towards graphics insets in #...
+This ticket makes `GraphicsArray` derive from a new class, `MultiGraphics`, which is more generic (arbitrary positions of graphics objects on a canvas) and paves the way towards graphics insets in #27866.
 
 `GraphicsArray` is now endowed with a `matplotlib()` function (inheritated from  `MultiGraphics`). This fixes the issues reported in #10466, #10657, #11160 and #12591. 
 Moreover, this simplifies `sphinx_plot()` (defined in `src/doc/common/conf.py`), avoiding code duplication. 
@@ -35,4 +35,4 @@
 ```
   This fix explains the change of doctest outputs in `src/sage/categories/finite_posets.py` and `src/sage/repl/rich_output/pretty_print.py`
 
-A preview (including the functionalities introduced in #...) is available [here](https://sagemanifolds.obspm.fr/preview/graphics_inset/reference/plotting/sage/plot/multigraphics.html).
+A preview (including the functionalities introduced in #27866) is available [here](https://sagemanifolds.obspm.fr/preview/graphics_inset/reference/plotting/sage/plot/multigraphics.html).

[egourgoulhon]

Attachment: graphics_array_bug.png

[egourgoulhon]

Attachment: graphics_array_ok.png

[egourgoulhon]

comment:3

Here is an example summarizing some the GraphicsArray issues. In Sage 8.7, the following code:

sage: g1 = plot(sin(x^2), (x, 0, 6), 
....:           axes_labels=[r'$\theta$', r'$\sin(\theta^2)$'], fontsize=14)
sage: g2 = circle((0,0), 1, fill=True, color='red', alpha=0.4, axes=False) \
....:      + text("This is a disk", (0.9, 1.1), color='red', alpha=0.4, 
....:             fontsize=12)
sage: g3 = plot(x^3, (x, 1, 100), axes_labels=[r'$x$', r'$y$'], 
....:           legend_label=r'$y = x^3$', scale='semilogy', frame=True, 
....:           gridlines='minor') \
....:      + text("This is a semilogy plot", (80, 1e5), color='red', alpha=0.4, 
....:             fontsize=12)
sage: graphics_array([g1, g2, g3])

results in this figure:

We see that

• the semilogy scale asked for g3 is actually applied to g1
• the fontsize asked for g1 is not taken into account (this is options for items in a GraphicsArray() should be set independently #10657)
• the option axes=False asked for g2 is not taken into account (graphics_array does not respect axes, ticks options with matrix_plot objects #10466 and options for items in a GraphicsArray() should be set independently #10657)
• the legend of g3 is doubled (same color shows up different in graphics_array #12591)
• the color of the text in g3 is not the same as in g2, while they both defined as color='red', alpha=0.4 (same color shows up different in graphics_array #12591)

With the code introduced in this ticket, the output becomes

We see that all the above issues are gone.

[egourgoulhon]

comment:5

Another bug fixed by this ticket regards the options passed to the method GraphicsArray.show(). This bug shows up in the
2D plotting section of the reference manual. In the example starting with "The basic options for filling a plot", the figure resulting from

sage: p1 = plot(sin(x), -pi, pi, fill='axis')
sage: p2 = plot(sin(x), -pi, pi, fill='min', fillalpha=1)
sage: p3 = plot(sin(x), -pi, pi, fill='max')
sage: p4 = plot(sin(x), -pi, pi, fill=(1-x)/3, fillcolor='blue', fillalpha=.2)
sage: graphics_array([[p1, p2], [p3, p4]]).show(frame=True, axes=False)

has obviously some axes and no frame...

Compare with the figure produced by the code in this ticket here.

[egourgoulhon]

Description changed:

--- 
+++ 
@@ -1,6 +1,6 @@
 This ticket makes `GraphicsArray` derive from a new class, `MultiGraphics`, which is more generic (arbitrary positions of graphics objects on a canvas) and paves the way towards graphics insets in #27866.
 
-`GraphicsArray` is now endowed with a `matplotlib()` function (inheritated from  `MultiGraphics`). This fixes the issues reported in #10466, #10657, #11160 and #12591. 
+`GraphicsArray` is now endowed with a `matplotlib()` function (inheritated from  `MultiGraphics`). This fixes the issues reported in #10466, #10657, #11160 and #12591 (see :comment:3 and [comment:5](#comment%3A5) below for a summary). 
 Moreover, this simplifies `sphinx_plot()` (defined in `src/doc/common/conf.py`), avoiding code duplication. 
 
 Beside introducing `matplotlib()` at the graphics array level, two bugs had to be corrected in `Graphics.matplotlib()`: