sensible defaults for aspect ratio

[jasongrout]

We have two concepts of "aspect ratio" that we'd like to expose to the user.

This patch exposes the following behavior:

    * Figure aspect ratio -- controls the final image size, including any text labels, etc. This will be set using the following options:
          o figsize
                + single number - use this as a base size for the width of the figure canvas
                + two numbers - an actual figure size in inches
                + None - use the default size in Matplotlib
          o fit_tight
                + if True, clip or extend the resulting figure to the plot objects (so the resulting figure will probably not have figsize dimensions
                + if False, the resulting figure has exactly figsize dimensions, but items in the plot may be clipped or there may be excessive padding around drawn objects
    * Pixel aspect ratio
          o aspect_ratio -- the ratio height/width for a unit square
                + 1 -- a unit square appears to have equal height and width.  This will be the default for Graphics objects (so if a default is not explicitly set, the default is this.)
                + 'auto' -- plot the given data limits in the given (or computed) figsize, filling the figure (default for plot and list_plot)
                + number -- ratio of height to width.

To patchbot/reviewers: Apply attachment: trac_2100-aspect-ratio-rebase.patch and attachment: trac_2100-auto-automatic-and-vector.patch

CC: @kcrisman @sagetrac-mhampton @qed777

Component: graphics

Keywords: sd31

Author: Jason Grout, Karl-Dieter Crisman

Reviewer: Andrey Novoseltsev, Karl-Dieter Crisman, Ryan Grout

Merged: sage-4.7.2.alpha0

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

[jasongrout]

comment:1

For reference, in Mathematica (see http://reference.wolfram.com/mathematica/ref/AspectRatio.html?q=AspectRatio&lang=en )

• Graphics objects use Automatic aspect ratio
• plot and listplot use 1/golden ratio
• parametric plot uses automatic
• contour plot uses aspect ratio of 1

Automatic is an aspect ratio determined by the pixels in the plot. It does not distort the plot (i.e., circles are still circles).

[sagetrac-mabshoff]

comment:2

Jason,

didn't we fix this recently?

Cheers,

Michael

[jasongrout]

comment:4

#9813 takes care of two cases of these.

Interestingly, from the above list, it seems like the golden ratio is only used for a minority of functions (i.e., "plot" and "list_plot"). So maybe we ought to change the global default to aspect_ratio=1 and just set plot and list_plot to have default golden ratio aspect ratios.

[jasongrout]

comment:5

Matplotlib aspect ratio setting	Matplotlib adjustable setting	Mathematica AspectRatio setting	Explanation
'auto'	doesn't seem to matter	Full	Make the current data limits fill the available sized box
'equal' or 1	'box'	Automatic	Make each pixel be square (aspect ratio 1)

It appears that specifying a number in matplotlib ('box' adjustable) makes the pixels have a certain height-to-width ratio (e.g., a circle in the picture will appear to have the given aspect ratio), but in Mathematica, a number specifies the overall ratio of the image height-to-width.  Thus the numbers are not directly comparable.

Plus, in matplotlib, you can have the 'datalim' be adjustable, which changes the data limits on your plot to make the pixels have a certain aspect ratio.

[jasongrout]

comment:6

Matplotlib's fig_aspect seems to do the sort of thing that mma's aspect ratio number setting does:

!http://matplotlib.sourceforge.net/api/figure_api.html#matplotlib.figure.figaspect

[jasongrout]

comment:8

One other note: setting bbox_inches='tight' in the savefig method seems to override the figure size specified.

[jasongrout]

comment:9

We have two concepts of "aspect ratio" that we'd like to expose to the user.

• Figure aspect ratio -- controls the final image size, including any text labels, etc.  This will be set using the following options:
  • fig_aspect_ratio
    • number - make an image with the specified aspect ratio (within reason) using the figaspect matplotlib function (which tries to be marginally smart, which actually may be a dumb thing to do...)
    • 'auto' (default) - use bbox_inches='tight' to create a figure that holds the drawn objects
  • figsize
    • single number - use this as a base size for fig_aspect_ratio calculations (i.e., bigger numbers = bigger figures)
    • two numbers - an actual figure size in inches
• Pixel aspect ratio
  • aspect_ratio -- the aspect ratio of a pixel in the image (or of a unit square in data coordinates, for example).  The default here will change depending on the type of plot
    • 'equal' or 1 -- square pixels.  This will be the default for most things
    • 'auto' -- plot the given data limits in the given (or computed) figsize, filling the figure
    • number -- ratio of width to height (or height to width; I can't remember).  For plot() and list_plot(), this will default to giving a golden ratio aspect ratio
  • aspect_ratio_adjust -- what should we adjust to achieve the desired aspect ratio for the items drawn?  Note that by default, the axes limits are enlarged slightly; to eliminate this, set axes_pad=0
    • 'box' (default) -- the frame axes
    • 'datalim' -- the data limits

What do people think?

[jasongrout]

comment:10

Helpful matplotlib mailing list post (read the thread): !http://www.mail-archive.com/matplotlib-users@lists.sourceforge.net/msg15623.html

[jasongrout]

comment:11

Moving the proposal up to the description so we can edit it. Ignore the proposal in the comments now.

[jasongrout]

comment:12

Update the proposal.

[jasongrout]

comment:13

I've attached two files.  First, a work-in-progress rewrite of the aspect ratio stuff.  Second, the plot.py file before this patch was applied.  The plot.py file is the version from 4.6.alpha1 with tickets #9740, #9746, and #4342 applied, in order.

[jasongrout]

comment:14

This ticket is still needs_work.  Remaining items include:

• Updating docs to reflect changes, including
  • Most aspect ratios now default to 1
  • new/changed options:
    •  fig_tight
    • the new definition of aspect_ratio (= 1/old definition)
    • aspect_ratio_adjustable
• Make GraphicsArray work (likely using the nice features of matplotlib in 1.0 for doing multiple subplots!)

Warning: this patch changes the definition of aspect_ratio.  Before, it was width/height, but now it is height/width.  The new meaning is consistent with matplotlib and Mathematica.

Since the patch now changes a very fundamental thing about Sage (the meaning of aspect ratio), it probably should be put off until a major release.

[jasongrout]

Author: Jason Grout

[jasongrout]

comment:15

Also todo: set barchart and scatterplot to have default aspect ratios of 'auto'.

[jasongrout]

comment:16

Replying to @jasongrout:

Warning: this patch changes the definition of aspect_ratio. Before, it was width/height, but now it is height/width. The new meaning is consistent with matplotlib and Mathematica. Since the patch now changes a very fundamental thing about Sage (the meaning of aspect ratio), it probably should be put off until a major release.

Apparently this statement isn't true. The old aspect_ratio and new aspect_ratio mean the same thing. I was basing the statement on reading the docs. Either the current docs are backwards, or I was misreading them.

So, in short, things are good to go for finishing this patch and getting it into Sage as soon as possible.

[jasongrout]

Attachment: 2100-aspect_ratio.2.patch.gz

apply instead of previous patch

[jasongrout]

comment:17

New patch revamping the aspect ratio calculations in Sage (and defaults!)

[jasongrout]

comment:18

Updating description to reflect changes in the patch.

[sagetrac-ryan]

Changed reviewer from Andrey Novoseltsev, Karl-Dieter Crisman to Andrey Novoseltsev, Karl-Dieter Crisman, Ryan Grout

[sagetrac-ryan]

comment:68

Patch looks good. Confirmed that kcrisman's code looks 'good' after the patch too :) Positive Review. Great job guys.

Note: I do get doctest failures on plot_field.py, but the failures are not caused by the patches to this ticket.

[novoselt]

comment:69

Replying to @sagetrac-ryan:

Note: I do get doctest failures on plot_field.py, but the failures are not caused by the patches to this ticket.

What exactly do you mean by this? That a clean public release of Sage has doctest failures in plot_field.py?

[kcrisman]

comment:70

Correct - or to be more precise, warnings that do not cause the doctest to fail. They are known, and not from Sage.

[jdemeyer]

comment:72

Please rebase this patch to be applied on top of #11491.

[jdemeyer]

Work Issues: rebase

[kcrisman]

comment:73

Replying to @jdemeyer:

Please rebase this patch to be applied on top of #11491.

Thanks - another rebase where a major improvement takes second rank to a trivial adjustment. Especially since Ryan and I were involved on both tickets, it would have been nice to ask first. Rebasing is not so trivial for the setups some of us have.

But no point crying over spilt milk. Sigh... patches coming up.

[kcrisman]

Attachment: trac_2100-auto-automatic-and-vector.patch.gz

Apply after rebase patch

[kcrisman]

comment:74

Okay, now we should hopefully be at positive review!

[jdemeyer]

comment:75

Replying to @kcrisman:

Especially since Ryan and I were involved on both tickets, it would have been nice to ask first.

I have done that in the past and people complained: http://groups.google.com/group/sage-devel/browse_frm/thread/abd5fb944769e052/8e4057172b97f2e5

[kcrisman]

comment:76

Right, and my point is that this sort of feels the same way. I am not suggesting unmerging something positively reviewed - definitely not the direction I'm going.

What I'm suggesting (and only suggesting, because I can only imagine how much work release management is) is that perhaps sending a ping via Trac on two closely related tickets which have some overlap would be good before deciding which one to merge first. Especially since in this case #11491 is so clearly much more trivial than this one, and also much older. I'm sure Ryan and I would have agreed that this one was higher priority.

Anyway, it turned out I had time for fixing it - it was a very small overlap, luckily. Thanks for all the hard work; the final releases really are noticeably more polished nowadays, and it's a great thing.

[jdemeyer]

comment:77

Replying to @kcrisman:

Right, and my point is that this sort of feels the same way. I am not suggesting unmerging something positively reviewed - definitely not the direction I'm going.

What I'm suggesting (and only suggesting, because I can only imagine how much work release management is) is that perhaps sending a ping via Trac on two closely related tickets which have some overlap would be good before deciding which one to merge first. Especially since in this case #11491 is so clearly much more trivial than this one, and also much older. I'm sure Ryan and I would have agreed that this one was higher priority.

It is not easy for me to determine a priori which patches conflict with eachother, so what you propose isn't really possible. It's not that I looked at both patches and decided which one to merge. What happened is that I already decided to merge #11491 before I even considered the patch here.

Since the sage-devel discussion I mentioned, there is an agreement that once a patch is merged (even in a future alpha version), it should stay merged if possible.

[jdemeyer]

Changed work issues from rebase to none

[jdemeyer]

comment:78

Replying to @kcrisman:

Thanks for all the hard work; the final releases really are noticeably more polished nowadays, and it's a great thing.

You should really also thank Mitesh Patel for managing the buildbot.

[kcrisman]

comment:79

It is not easy for me to determine a priori which patches conflict with eachother, so what you propose isn't really possible. It's not that I looked at both patches and decided which one to merge. What happened is that I already decided to merge #11491 before I even considered the patch here.

Understood.

Since the sage-devel discussion I mentioned, there is an agreement that once a patch is merged (even in a future alpha version), it should stay merged if possible.

Yes, that definitely makes sense, as I hope I make clear above. :)

[jdemeyer]

Merged: sage-4.7.2.alpha0