matplotlib-devel Mailing List for matplotlib

Michael Droettboom <mdroe@...> writes:
> 
> On 08/26/2012 05:33 AM, Anton Akhmerov wrote:
> > Michael Droettboom <mdroe@...> writes:
> >
> >>
> >> 
> >> Working with the documentation this past week has me a little
> >> frustrated with the state of it. Enough to write a MEP.
> > https://github.com/matplotlib/matplotlib/wiki/Mep10
> >> In particular, it would be nice to compile a list of concerns about
> >> the docstrings and documentation layout so that we can address as
> >> much as possible in a single pass. Also, let me know if there are
> >> any relevant PRs and Issues.
> >> In particular, I think PR #1032, as it is a large structural
> >> reorganization, my dovetail well with the proposed reorganization of
> >> the docs.
> >> Mike
> > The proposal looks great. I would like to comment on one issue that it 
touches,
> > and which I found very uncomfortable to work with as a newcomer. I think 
that
> > matplotlib style of using *args and **kwargs for delegation of arguments is 
a
> > rather bad practice, which is hard to solve by just updating documentation. 
It
> > breaks many rules of pep 20: it is implicit, since it is not allowing
> > introspection, it is nested, since it always involves nested calls, it 
allows
> > for alternative ways to do things, and I also don't think it's anyhow 
beautiful.
> > Most of the things passed with *args, **kwargs can be done with an added
> > function call, like:
> >
> > points = ax.scatter(data)
> > points.update(*args, **kwargs)
> >
> > What would be the disadvantage of abolishing this practice?
> >
> I understand the comments about the difficulty of introspection. The 
> reason it works the way it does is so that additional parameters can be 
> added to the artist layer without needing to update every single 
> plotting function. A real world example of this is when hatching was 
> added -- that feature only had to be added in one place and most artists 
> were able to use it. In that sense, I think this approach is very 
> beautiful in terms of code maintainability and extensibility.
First of all, to be clear, I am not trying to be negative about the current 
situation, I rather search for ways to improve on it. I also realize that any 
changes like this would be very serious and require a lot of thinking and of 
course work. Let me first point some drawbacks of the current kwargs usage 
before discussing the solution. Let me know if you agree.
1. Currenly the aims of extensibility and maintainability are not completely 
reached, as seen from this part of Axes.scatter docstring:
 Optional kwargs control the
 :class:`~matplotlib.collections.Collection` properties; in
 particular:
 *edgecolors*:
 The string 'none' to plot faces with no outlines
 *facecolors*:
 The string 'none' to plot unfilled outlines
So the explicit descriptions of useful **kwargs are provided. If a new useful 
property of collections appears, it stays unknown.
2. Yet another problem that **kwargs cause is that it is sometimes completely 
unclear where an argument ends up. `Axes` methods have a reasonably well-
documented kwargs, while, e.g. axis module often fails to mention what happens 
to kwargs. Another example of misuse is figure.add_axes, where the docstring 
declares:
"""...kwargs are legal Axes kwargs plus projection which sets the projection 
type of the axes. (For backward compatibility, polar=True may also be provided, 
which is equivalent to projection='polar'). Valid values for projection are: 
[‘aitoff’, ‘hammer’, ‘lambert’, ‘mollweide’, ‘polar’, ‘rectilinear’]. Some of 
these projections support additional kwargs, which may be provided to 
add_axes()."""
Despite this is an extensible interface, I still wouldn't call it user-friendly; 
kwargs are passed to at least two places: Axes and projection.
3. About the hatching: I think this is solved in a rather elegant fashion with 
symbols for scatter plot: the interpretation of the format is deferred to 
`mmarkers.MarkerStyle(marker)`. This means that `marker` is in fact already 
effectively a style object, corresponding to the style object format that you 
suggested. One can also easily refer to the MarkerStyle docstring in order to 
make the description complete.
4. The idea behind kwargs, if I understand it correctly, is to let high-level 
functions, such as all the plot functions handle low-level objects in full 
generality. This aim cannot be achieved anyway, because high-level functions 
often generate more than one low-level object. This is why something like this:
axis.label.set_text(r"$\theta = 60^{\circ}$")
Is still provided as a separate command, and cannot be done via kwargs to 
scatter. So the user already doesn't have a situation where a single function 
call is sufficient.
---------------------
These altogether seem serious enough to consider changing the behavior in one or 
another way. They are often also directly related to documentation quality.
Best,
Anton

> Michael,
>
> Thank you, this sounds good. Although we can deal with it as a patch if
> necessary, it would be greatly preferable to see it as a github PR:
> http://matplotlib.sourceforge.net/devel/gitwash/git_development.html#git-development
>
> Are you willing to give that a try?
>
> Eric
Yes i suppose so. Give me a couple of days. I will post a note when done.
cheers,
Michael

>>> right angles are no longer right angles: noob error. Apologies.
Forgiven; on the basis that you provided such an entertainingly colourful
initial report! :-)

On Mon, Aug 27, 2012 at 01:26:49PM -0400, Michael Droettboom wrote:
> I'm not sure this is a bug. The transformation is being applied in data 
> space, and then the mapping to physical space is not square in the x and 
> y dimensions.
> 
> I think calling set_aspect('equal') on the axes should fix this -- if it 
> doesn't, that's indeed a bug.
>
Awesome, it worked. Honestly, I probably should have realised that when
you don't have square axes, right angles are no longer right angles:
noob error. Apologies.
> 
> Mike
> 
> On 08/27/2012 01:05 PM, Damon McDougall wrote:
> > My cherubs,
> >
> > With my new found free time, I may have discovered a sneaky bug to which
> > you are not aware. Unless, of course, my example code is incorrect.
> >
> > I do normal setup:
> >
> > from matplotlib.backends.backend_pdf import FigureCanvasPdf as FigureCanvas
> > from matplotlib.figure import Figure
> > from matplotlib.patches import Rectangle
> > from matplotlib.transforms import Affine2D
> >
> > fig = Figure()
> > canvas = FigureCanvas(fig)
> > ax = fig.add_subplot(1, 1, 1)
> >
> > # Make a sexy rectangle at the origin
> > r = Rectangle((0.0, 0.0), 0.6, 0.4)
> >
> > # Construct a mind-blowing transformation: rotation by 30 degrees
> > t = Affine2D().rotate_deg(30.0)
> >
> > # Make sure to add in the already-known axes data transformation
> > t += ax.transData
> >
> > # Rotate that shizzle
> > r.set_transform(t)
> >
> > # Plottify
> > ax.add_patch(r)
> >
> > fig.savefig('my_awesome_TRAPEZIUM.pdf')
> >
> > Or you can look at my output here: http://i.imgur.com/2l439.png
> >
> > Rotation by 30 degrees is an angle-preserving linear transformation. So
> > this shouldn't happen.
> >
> > Here's what's messing shiz up: the figure dimensions are not square.
> > Look what happens when I use a square figure and make the axes fit
> > exactly to the figure dimensions:
> >
> > ...
> > fig = Figure((4, 4))
> > ...
> > ax = fig.add_axes([0, 0, 1, 1])
> > ...
> > ...
> > fig.savefig('my_awesome_RECTANGLE.pdf')
> >
> > You can see the output here: http://i.imgur.com/baXiH.png
> >
> > Boom.
> >
> > I have no idea how to fix it. I came across it while trying to address
> > https://github.com/matplotlib/matplotlib/issues/987 but it may or may
> > not also be related to
> > https://github.com/matplotlib/matplotlib/issues/1113
> >
> > Let me know if it's worth putting in github issue. I'm dont want to
> > create a duplicate ticket should it transpire that this problem is
> > actually #1113 in disguise.
> >
> > Best,
> > Damon
> >
> 
> 
> ------------------------------------------------------------------------------
> Live Security Virtual Conference
> Exclusive live event will cover all the ways today's security and 
> threat landscape has changed and how IT managers can respond. Discussions 
> will include endpoint security, mobile security and the latest in malware 
> threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
-- 
Damon McDougall
http://www.damon-is-a-geek.com
B2.39
Mathematics Institute
University of Warwick
Coventry
West Midlands
CV4 7AL
United Kingdom

I'm not sure this is a bug. The transformation is being applied in data 
space, and then the mapping to physical space is not square in the x and 
y dimensions.
I think calling set_aspect('equal') on the axes should fix this -- if it 
doesn't, that's indeed a bug.
Mike
On 08/27/2012 01:05 PM, Damon McDougall wrote:
> My cherubs,
>
> With my new found free time, I may have discovered a sneaky bug to which
> you are not aware. Unless, of course, my example code is incorrect.
>
> I do normal setup:
>
> from matplotlib.backends.backend_pdf import FigureCanvasPdf as FigureCanvas
> from matplotlib.figure import Figure
> from matplotlib.patches import Rectangle
> from matplotlib.transforms import Affine2D
>
> fig = Figure()
> canvas = FigureCanvas(fig)
> ax = fig.add_subplot(1, 1, 1)
>
> # Make a sexy rectangle at the origin
> r = Rectangle((0.0, 0.0), 0.6, 0.4)
>
> # Construct a mind-blowing transformation: rotation by 30 degrees
> t = Affine2D().rotate_deg(30.0)
>
> # Make sure to add in the already-known axes data transformation
> t += ax.transData
>
> # Rotate that shizzle
> r.set_transform(t)
>
> # Plottify
> ax.add_patch(r)
>
> fig.savefig('my_awesome_TRAPEZIUM.pdf')
>
> Or you can look at my output here: http://i.imgur.com/2l439.png
>
> Rotation by 30 degrees is an angle-preserving linear transformation. So
> this shouldn't happen.
>
> Here's what's messing shiz up: the figure dimensions are not square.
> Look what happens when I use a square figure and make the axes fit
> exactly to the figure dimensions:
>
> ...
> fig = Figure((4, 4))
> ...
> ax = fig.add_axes([0, 0, 1, 1])
> ...
> ...
> fig.savefig('my_awesome_RECTANGLE.pdf')
>
> You can see the output here: http://i.imgur.com/baXiH.png
>
> Boom.
>
> I have no idea how to fix it. I came across it while trying to address
> https://github.com/matplotlib/matplotlib/issues/987 but it may or may
> not also be related to
> https://github.com/matplotlib/matplotlib/issues/1113
>
> Let me know if it's worth putting in github issue. I'm dont want to
> create a duplicate ticket should it transpire that this problem is
> actually #1113 in disguise.
>
> Best,
> Damon
>

My cherubs,
With my new found free time, I may have discovered a sneaky bug to which
you are not aware. Unless, of course, my example code is incorrect.
I do normal setup:
from matplotlib.backends.backend_pdf import FigureCanvasPdf as FigureCanvas
from matplotlib.figure import Figure
from matplotlib.patches import Rectangle
from matplotlib.transforms import Affine2D
fig = Figure()
canvas = FigureCanvas(fig)
ax = fig.add_subplot(1, 1, 1)
# Make a sexy rectangle at the origin
r = Rectangle((0.0, 0.0), 0.6, 0.4)
# Construct a mind-blowing transformation: rotation by 30 degrees
t = Affine2D().rotate_deg(30.0)
# Make sure to add in the already-known axes data transformation
t += ax.transData
# Rotate that shizzle
r.set_transform(t)
# Plottify
ax.add_patch(r)
fig.savefig('my_awesome_TRAPEZIUM.pdf')
Or you can look at my output here: http://i.imgur.com/2l439.png
Rotation by 30 degrees is an angle-preserving linear transformation. So
this shouldn't happen.
Here's what's messing shiz up: the figure dimensions are not square.
Look what happens when I use a square figure and make the axes fit
exactly to the figure dimensions:
...
fig = Figure((4, 4))
...
ax = fig.add_axes([0, 0, 1, 1])
...
...
fig.savefig('my_awesome_RECTANGLE.pdf')
You can see the output here: http://i.imgur.com/baXiH.png
Boom.
I have no idea how to fix it. I came across it while trying to address
https://github.com/matplotlib/matplotlib/issues/987 but it may or may
not also be related to
https://github.com/matplotlib/matplotlib/issues/1113
Let me know if it's worth putting in github issue. I'm dont want to
create a duplicate ticket should it transpire that this problem is
actually #1113 in disguise.
Best,
Damon
-- 
Damon McDougall
http://www.damon-is-a-geek.com
B2.39
Mathematics Institute
University of Warwick
Coventry
West Midlands
CV4 7AL
United Kingdom