matplotlib-devel Mailing List for matplotlib

On Fri, Oct 25, 2013 at 3:32 PM, Todd <tod...@gm...> wrote:

> I think one thing that contributes a lot to the API issues is the
> inconsistency between pyplot API and the OO API.  There isn't any reason
> the APIs need to be so different.
>

indeed.

I hadn't even realized how different they were.


> So the idea would be to have essentially all of the pyplot functions just
> be wrappers for methods from other classes, using the same name and same
> call signature (minus "self").  All of the actual functionality would be
> implemented in the methods, the pyplot functions should not have any logic
> or tests.
>

+ inf

However, doing this with full backward compatibility could be a real
challenge...

This will make it easy to transition between the two, learning to use the
> OO interface would just involve learning what object the pyplot function is
> targeting (this should be in the pyplot function docstring).
>

That would help, though a namespace without any non-OO stuff would be still
be good, and, of course, docs and tutorials.

-Chris

-- 

Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R            (206) 526-6959   voice
7600 Sand Point Way NE   (206) 526-6329   fax
Seattle, WA  98115       (206) 526-6317   main reception

Chr...@no...

Thank you all for the thoughts so far

I have raised a pull request:
https://github.com/matplotlib/matplotlib/pull/2554

To be clear, this is a 'structure only' pull request, I have made no
documentation changes as yet.

I see this as a part of the process.  If we can agree structure we can
work on aspects of the user guide, adding content into appropriate
sections.

all the best
mark

On Wed, 25 Sep 2013 08:19:59 +0000
mark <ma...@me...> wrote:

> hi matplotlib developers
> 
> I have been considering the matplotlib user guide structure and it
> has occured to me that there are two user guides interleaved here:
>   1. Introduction for new users
>   2. Library tour for developers
> 
> I think that this structure makes it challenging for new users to
> benefit from the user guide as much as they could.  
> 
> I would like to see the user guide separated into two sections, with
> the two different audiences in mind.  I feel this would enable new
> users of the library to have a more targeted introduction to some of
> the neat features without getting bogged down in details they are
> unlikely to need (or comprehend). 
> 
> I am very happy to have a go at this and put up a set of suggested
> changes but I would value input from the community on this approach
> and my category suggestions before I submit a pull request.
> 
> many thanks
> mark
> 
> 
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the
> most from the latest Intel processors and coprocessors. See abstracts
> and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk
> _______________________________________________ Matplotlib-devel
> mailing list Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

On 10/25/2013 06:42 PM, Todd wrote:
> I think another problem is having pyplot and axes as dumping grounds 
> for all plot types.  This probably made sense back when there were 
> only a few types of plots, but now there is a massive number of them.  
> They all end up in one large class with one large documentation page, 
> making it very hard to find exactly what you are looking for.
>
> In order to make the plots really useful, I definitely think a 
> reorganization is in order.  I think matplotlib needs an general 
> module, perhaps "plots", that contains sub-modules for different types 
> of plots (like bar plots), and those sub-modules contain functions, 
> all of which have an axes object as their first argument.  These could 
> still be attached to axes as methods at least as a transition, but it 
> would leave the axes class with methods that really have to do with 
> axes, and not plotting per se.  This would also make it possible to 
> put code shared between plot types with those plot types in their module.

Nelle Varaquoax has already started this work on master.  The separation 
of core axes functionality from plotting functionality has already been 
done, and the next steps involve organizing the plotting functionality 
further.  This is a gargantuan task, and I'm sure Nelle would appreciate 
some assistance if you wanted to coordinate with her.

Mike

>
> On Thu, Oct 24, 2013 at 8:39 PM, Chris Barker <chr...@no... 
> <mailto:chr...@no...>> wrote:
>
>     On Thu, Oct 24, 2013 at 8:29 AM, Michael Droettboom
>     <md...@st... <mailto:md...@st...>> wrote:
>     > Here are the notes with action items from the meeting:
>
>     thanks for posting that. I see:
>
>     pylab - should it stay or should it go?
>
>     Comment from the peanut gallery:
>
>     Go.
>
>     But beyond that, matplotlib.pyplot is a big mess of both the
>     matlab-style state-machine current figure, current axis stuff, and
>     what you need to do (at least reasonably on the command line) OO
>     interface.
>
>     This makes it really hard to teach to newbies -- I just did this last
>     night, and made a point to use tutorials that emphasize the OO
>     interface (Thanks Ben Root, Katy Huff, and Antony Scopatz, and I'm
>     sure others that helped put the materials together that I stole
>     from...). However, there were still a number of examples in there that
>     just called "plot()" or whatever, and even if there were not, the
>     namespace is really cluttered with stuff!
>
>     Anyone like the idea of an matplotlib.ooplot namespace that would have
>     just what you need to use the oo style?
>
>     -Chris
>
>     --
>
>     Christopher Barker, Ph.D.
>     Oceanographer
>
>     Emergency Response Division
>     NOAA/NOS/OR&R (206) 526-6959 <tel:%28206%29%20526-6959>   voice
>     7600 Sand Point Way NE (206) 526-6329 <tel:%28206%29%20526-6329>   fax
>     Seattle, WA  98115 (206) 526-6317 <tel:%28206%29%20526-6317>  
>     main reception
>
>     Chr...@no... <mailto:Chr...@no...>
>
>     ------------------------------------------------------------------------------
>     October Webinars: Code for Performance
>     Free Intel webinars can help you accelerate application performance.
>     Explore tips for MPI, OpenMP, advanced profiling, and more. Get
>     the most from
>     the latest Intel processors and coprocessors. See abstracts and
>     register >
>     http://pubads.g.doubleclick.net/gampad/clk?id=60135991&iu=/4140/ostg.clktrk
>     _______________________________________________
>     Matplotlib-devel mailing list
>     Mat...@li...
>     <mailto:Mat...@li...>
>     https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>
>
>
>
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60135991&iu=/4140/ostg.clktrk
>
>
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel


-- 
                    _
|\/|o _|_  _. _ | | \.__  __|__|_|_  _  _ ._ _
|  ||(_| |(_|(/_| |_/|(_)(/_|_ |_|_)(_)(_)| | |

http://www.droettboom.com

When calling the save dialog in a gtk backend

Traceback (most recent call last):
  File "/home/fariza/workspace/matplotlib/lib/matplotlib/backends/backend_gtk.py",
line 752, in save_figure
    chooser = self.get_filechooser()
  File "/home/fariza/workspace/matplotlib/lib/matplotlib/backends/backend_gtk.py",
line 747, in get_filechooser
    default_filetype=self.canvas.get_default_filetype())
  File "/home/fariza/workspace/matplotlib/lib/matplotlib/backends/backend_gtk.py",
line 835, in __init__
    self.sorted_filetypes = list(six.iteritems(filetypes.items))
  File "/usr/lib/python2.7/dist-packages/six.py", line 254, in iteritems
    return iter(getattr(d, _iteritems)())
AttributeError: 'builtin_function_or_method' object has no attribute 'iteritems'


I created a pull request to fix it.
https://github.com/matplotlib/matplotlib/pull/2553

Federico

-- 
Y yo que culpa tengo de que ellas se crean todo lo que yo les digo?

-- Antonio Alducin --

On Fri, Oct 25, 2013 at 2:34 PM, Pierre Haessig <pie...@cr...>wrote:

>  Hi,
>
> Le 22/10/2013 19:14, Todd a écrit :
>
>  Thanks for the feedback. I agree that your documentation does make clear
>> the distinction between "phase" and "angle" and that it has a consistency.
>> I just feel that this distinction does not exist "outside" ...
>>
>> But beyond this question of phase vs. angle, I must say I don't see that
>> big a use case for phase/angle spectrums[*] (as opposed to magnitude which
>> are much used).
>>
>
> I personally use phase and angle spectrums a huge amount.  In signal
> processing it is extremely important.  It is a critical component in
> acoustics.  It is also used a lot to separate out signals that have been
> mixed together.  Knowing the phases of signals can also be very important
> in certain optics applications and for radio signals and RADAR.  Changes in
> the phase spectrum over time (like you would get from a phase spectrogram)
> is important for doppler analysis both with optical and acoustic signals.
>
>  Also, from an educational perspective, anyone taking a digital signal
> processing course will need to produce magnitude/phase plots, probably both
> with and without wrapping (since any decent digital signal processing
> course will teach you about the pitfalls that occur due to phase
> wrapping).  So this will make matplotlib much more useful for such courses.
>
>
>> Also, in many cases, "spectrum" is synonymous with spectral density,
>> which implies "magnitude". In the end I wonder whether the notion of phase
>> even makes sense for a spectrogram ?
>>
>
>  Yes, particularly electrical engineering.  But there are many other
> fields where spectral density is rarely used, and where more "ordinary"
> magnitude and phase plots are the norm, as I explained in the previous
> paragraphs.
>
> Thanks for dealing with my ignorance. It's true that I have a biased view
> on these frequency functions, because I mostly deal with random signals
> these days.
>
> In fact I'd like to understand a bit more how phase spectorgram works.
> Since the signal must be cut into chunks to make the plot along time, how
> is the phase computations "synchronised", that is, how does it use a common
> time reference. (because I would imagine that otherwise the phase would
> make "jumps" between each window frame). Do you have a pointer for how this
> is solved ? (or is this problem just non-existing?).
>
> best,
> Pierre
>

This could certainly be an issue, and no it isn't dealt with (nor am I
aware of a way it could be dealt with).

There are really several different questions here.

First, is it worthwhile having 1-D phase and angle spectrums
(phase_spectrum and angle_spectrum).  I would argue that this is definitely
the case, as I already explained.

Second, is it worthwhile adding these to specgram?  Frankly. probably not.
They have some robustness issues.

Third, given that implementing phase_spectrum and angle_spectrum
automatically gets us phase and angle specgrams, and that it would actually
take more code to turn them off than to leave them in, is there any reason
to explicitly disable these plot type?  I would say no.  It is a tool.  It
may not be useful to very many people, and the people who do use it may
need to be careful to use it properly.  But since we get it for free
anyway, I don't see a good reason to put in the extra code to remove
functionality that may be useful to someone but hurts no one.

On Fri, Oct 25, 2013 at 2:57 PM, Pierre Haessig <pie...@cr...>wrote:

>  Hello,
>
>
> Now that that PR #2522 is merged, I don't know how much futher commenting
> is useful, but I think there are two API details that I feel could be
> better :
>
> 1) API dissymetry
>
> The new pyplot/axes API is now:
>
>  * 1 function *spectgram* now uses a mode argument to tune this behavior :
>
> *mode*: [ 'default' | 'psd' | 'magnitude' | 'angle' | 'phase' ]
>              What sort of spectrum to use.  Default is 'psd'. which takes
>              the power spectral density.  'complex' returns the
> complex-valued
>              frequency spectrum.  'magnitude' returns the magnitude
> spectrum.
>             'angle' returns the phase spectrum without unwrapping.  'phase'
>              returns the phase spectrum with unwrapping.
>
> * 3 new functions *phase_spectrum, angle_spectrum, magnitude_spectrum*which complement the exising psd/csd
>
> -> I think this contributes to overcrowding axes/pyplot API. I like much
> better what is done with specgram so I would propose to add just one new
> function, for example *spectrum*(...mode='magnitude/angle/phase'). Using
> the same *mode *keyword as for specgram would increase the coherence of
> the API
>

Although it may reduce the number of functions, I don't think it increases
the coherence of the API.  Quite the opposite, in fact.  Besides the
inconsistency with psd and csd, I think having the plot types separate
makes sense because they really are not the same plots, they plot different
things in different ways and different units and using parameters.
Specgram, on the other hand, plots things in the same way with similar
units and mostly the same paramaters.  So I think specgram plots group
together much more cleanly than the other spectrum-related plots.

On Fri, Oct 25, 2013 at 3:06 PM, Pierre Haessig <pie...@cr...>wrote:

>  Hi,
>
> Le 21/10/2013 15:58, Todd a écrit :
>
>   2) Should there be two separate functions for these two, or just one
>>
>> function, with a switch argument `unwrap` ? (I guess it would be True by
>> default)
>>
>
>  I originally was going to do that, but decided against it.  The problem
> is with specgram.  Here, I thought it would be needlessly complicated to
> add an "unwrap" parameter that is only useful for one "mode".  To make it
> obvious to users, I wanted to keep specgram as similar as possible to the
> other plot types, and that involved keeping the parameter.
>
> Further, this approach is simpler to code and easier to maintain. Having
> to deal with the "unwrap" parameter would have been more difficult to
> program.  Dealing with both an "unwrap" parameter in some cases and a
> separate "mode" in others would have been even more complicated.
>
> Further, _spectral_helper and specgram already have a huge number of
> arguments.  This way I was able to get away with just adding one new
> argument rather than two.
>
>
> You've convinced me. I didn't have the big picture of your PR when writing
> my previous messages. I like the approach you took for specgram, which put
> "magnitude", "phase", "angle" on the same level. This indeed reduce the
> number of keywords.
>
> Coming back to the readability, what do you think of replacing "phase",
> "angle" by "unwrapped phase", "phase". Beyond readability, it also
> emphasizes for the reader the idea of "postprocessing" to get the unwrapped
> phase, i.e. a something that can have it's issue.
>

 I considering that.  The problem is that people have to type all that.
"magnitude_spectrum" is long enough as it is, but
"unwrapped_phase_spectrum" is just a huge function name (24 characters).  I
wanted something more concise.  I think the documentation makes it clear
enough.  I don't think we lose that much, the users only have to read the
docstring once, and they will avoid a lot of annoyance typing out such a
huge function name over and over.

I think another problem is having pyplot and axes as dumping grounds for
all plot types.  This probably made sense back when there were only a few
types of plots, but now there is a massive number of them.  They all end up
in one large class with one large documentation page, making it very hard
to find exactly what you are looking for.

In order to make the plots really useful, I definitely think a
reorganization is in order.  I think matplotlib needs an general module,
perhaps "plots", that contains sub-modules for different types of plots
(like bar plots), and those sub-modules contain functions, all of which
have an axes object as their first argument.  These could still be attached
to axes as methods at least as a transition, but it would leave the axes
class with methods that really have to do with axes, and not plotting per
se.  This would also make it possible to put code shared between plot types
with those plot types in their module.

On Thu, Oct 24, 2013 at 8:39 PM, Chris Barker <chr...@no...> wrote:

> On Thu, Oct 24, 2013 at 8:29 AM, Michael Droettboom <md...@st...>
> wrote:
> > Here are the notes with action items from the meeting:
>
> thanks for posting that. I see:
>
> pylab - should it stay or should it go?
>
> Comment from the peanut gallery:
>
> Go.
>
> But beyond that, matplotlib.pyplot is a big mess of both the
> matlab-style state-machine current figure, current axis stuff, and
> what you need to do (at least reasonably on the command line) OO
> interface.
>
> This makes it really hard to teach to newbies -- I just did this last
> night, and made a point to use tutorials that emphasize the OO
> interface (Thanks Ben Root, Katy Huff, and Antony Scopatz, and I'm
> sure others that helped put the materials together that I stole
> from...). However, there were still a number of examples in there that
> just called "plot()" or whatever, and even if there were not, the
> namespace is really cluttered with stuff!
>
> Anyone like the idea of an matplotlib.ooplot namespace that would have
> just what you need to use the oo style?
>
> -Chris
>
> --
>
> Christopher Barker, Ph.D.
> Oceanographer
>
> Emergency Response Division
> NOAA/NOS/OR&R            (206) 526-6959   voice
> 7600 Sand Point Way NE   (206) 526-6329   fax
> Seattle, WA  98115       (206) 526-6317   main reception
>
> Chr...@no...
>
>
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most
> from
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60135991&iu=/4140/ostg.clktrk
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>

I think one thing that contributes a lot to the API issues is the
inconsistency between pyplot API and the OO API.  There isn't any reason
the APIs need to be so different.

To continue with this example, pyplot.subplot and Figure.add_subplot do
basically the same thing, but they have different names.  In practice
pyplot.subplot essentially acts as a wrapper for gcf().add_subplot, but it
isn't exactly the same internally, it has some checks that are not present
in Figure.add_subplot but really should be.

On the other hand, pyplot.subplots doesn't exist at all in Figure, all the
functionality is implemented in pyplot.

So the idea would be to have essentially all of the pyplot functions just
be wrappers for methods from other classes, using the same name and same
call signature (minus "self").  All of the actual functionality would be
implemented in the methods, the pyplot functions should not have any logic
or tests.

So pyplot.subplot would be just be a wrapper for gcf().subplot,
pyplot.subplots would just be a wrapper for gcf().subplots, while
pyplot.plot would just be a wrapper for gcf().gca().plot.

This will make it easy to transition between the two, learning to use the
OO interface would just involve learning what object the pyplot function is
targeting (this should be in the pyplot function docstring).

On Fri, Oct 25, 2013 at 7:21 PM, Thomas A Caswell <tca...@uc...>wrote:

> There needs to be layers to the interface.  At the bottom there is super
> general stuff that will cover (we hope) 100% of use cases.  However, the
> cost is a very verbose interface with lots of knobs.  To cope with this
> there are higher level function which can deal with 90% of the use cases
> and do so by hiding some of the knobs (compare making a 3x3 grid
> `subplots(3, 3)` with using  `GridSpec` to figuring out where the axes
> edges should go and using `add_subplot([t, l, w, h])` ).  I want to make an
> analogy to projecting from a higher dimensional parameter space to a lower
> one.
>
> The 'proper' api to use is the simplest one that achieves your goal.  If
> you just need a grid of evenly spaced equal size axes use `subplots`, if
> you need a grid but with some axes that span columns/rows use `GridSpec`,
> if you need 5 axes that partially overlap in the shape of your school logo,
> use `add_subplot`.
>
> The point of the high-level APIs is to be easy to use.  If that means
> matching the MATLAB api to make it easier for people to switch, then fine.
>  I am sympathetic to the notion that the state-machine interface is
> confusing (because it maintains hidden state), but it is in fact very
> convenient.
>
>
> On Fri, Oct 25, 2013 at 10:26 AM, Daniele Nicolodi <da...@gr...>wrote:
>
>> On 25/10/2013 15:34, Benjamin Root wrote:
>>
>> > This has already been done. We have the GridSpec API that everything
>> > else maps to, for compatibility. But most people still like
>> > add_subplot() and subplots() for some odd reason... I think the primary
>> > issue is one of documentation, and we are currently in the process of
>> > upgrading that. We always welcome contributions to that effort!
>>
>> Hello Benjamin,
>>
>> thanks for your comments.  I'm aware of the solutions you propose, but I
>> maintain that the status quo is confusing for new users.
>>
>> The fact that there are multiple ways of doing the same thing, through
>> apparently unrelated interfaces makes the API more difficult to learn
>> and less discoverable that it needs to be.  This is probably a
>> conseqence of the organic growth of the library with time.
>>
>> I agree that the primary issue is the documentation, but at the root of
>> that I also feel there is the lack of well established best practices
>> for the use of Matplotlib. For example you write that people still like
>> add_subplot() and subplots() for odd reasons, which are the methods
>> others in the lists pointed to. What would be the proper API to use in
>> your opinion?  I believe convergence on best practices is paramount to
>> the update of the documentation.
>>
>> I also don't really buy the argument that it is desirable to keep and
>> promote APIs that try to emulate the Matlab interface.  Matplotlib is
>> different enough to make a 1:1 translation difficult and the Matlab
>> design is anyhow broken, IMHO.
>>
>> Best,
>> Daniele
>>
>> PS: with a new job also came the possibility to finally drop Matlab and
>> embrace Python as the main data analysis tool. This means that I can
>> dedicate some (at the moment very few) spare cycles to contribute to
>> Matplotlib. I would be happy to do so!
>>
>>
>>
>> ------------------------------------------------------------------------------
>> October Webinars: Code for Performance
>> Free Intel webinars can help you accelerate application performance.
>> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most
>> from
>> the latest Intel processors and coprocessors. See abstracts and register >
>>
>> http://pubads.g.doubleclick.net/gampad/clk?id=60135991&iu=/4140/ostg.clktrk
>> _______________________________________________
>> Matplotlib-devel mailing list
>> Mat...@li...
>> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>>
>
>
>
> --
> Thomas A Caswell
> PhD Candidate University of Chicago
> Nagel and Gardel labs
> tca...@uc...
> jfi.uchicago.edu/~tcaswell
> o: 773.702.7204
>
>
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most
> from
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60135991&iu=/4140/ostg.clktrk
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>
>

On Fri, Oct 25, 2013 at 6:34 AM, Benjamin Root <ben...@ou...> wrote:

> It doesn't feel weird. It feels generalized.
>

or both ;-)

It is the same way to add any number of plots, regardless if it is just
> one, or twenty. If you don't want to do it that way, you can just simply do:
>
> fig = plt.figure()
> ax = fig.gca()  # "get current axes" automatically creates an axes if one
>

rally ugly -- the whole point here is to get away from the concept of a
"current" anything -- I'm actually surprised that that's a figure method at
all...

 It does:

http://matplotlib.org/api/figure_api.html#matplotlib.figure.Figure.add_subplot
> This is *the* function that does axes creation for a figure, whether it is
> one, or many.
>


> subplots() is a recent addition.
>

And a nice one -- I've been wanting that for years! (and I
first discovered it in your tutorial, Ben!) The trick has always been that
plot() actually creates (If not re-using) three objects you might want to
work with: figure, axes, and line objects, so an oo interface that lets you
do that with one call is tricky -- I think this is a nice compromise.

We are in the process of updating our documentation. But add_subplot() is
> not going away because it works just fine, and it is very familiar to users
> of Matlab and Octave.
>

I've lost track a bit if there is support for a new OO-only API
(namespace), in which case, maybe some of this could be cleaned up as well.

I'd kind of like to see a fig.subplots() that has the same API as
plt.subplots(), for symmetry's sake, and because add_subplot() has a kind
of crufty API. Except it wouldn't return the figure instance (though it
could).

-Chris













>
>
>> In principle I think the current API violates the "There should be one--
>> and preferably only one --obvious way to do it" rule here, and elsewhere
>> :-)
>>
>>
> I feel the way forward should be to create a cleaner API and map the
>> current one through a compatibility layer to that.
>>
>>
> This has already been done. We have the GridSpec API that everything else
> maps to, for compatibility. But most people still like add_subplot() and
> subplots() for some odd reason... I think the primary issue is one of
> documentation, and we are currently in the process of upgrading that. We
> always welcome contributions to that effort!
>
> Cheers!
> Ben Root
>
>
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most
> from
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60135991&iu=/4140/ostg.clktrk
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>
>


-- 

Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R            (206) 526-6959   voice
7600 Sand Point Way NE   (206) 526-6329   fax
Seattle, WA  98115       (206) 526-6317   main reception

Chr...@no...

On Oct 24, 2013 8:40 PM, "Chris Barker" <chr...@no...> wrote:
>
> On Thu, Oct 24, 2013 at 8:29 AM, Michael Droettboom <md...@st...>
wrote:
> > Here are the notes with action items from the meeting:
>
> thanks for posting that. I see:
>
> pylab - should it stay or should it go?
>
> Comment from the peanut gallery:
>
> Go.

I agree, but that leads to another question: go where?

Some of the stuff there is clearly redundant and should be removed entirely.

Others I think are functionality that should be merged into numpy, although
whether they would agree I don't know.

Others are useful but I don't know exactly where they could end up.

I think we need to go through on a case-by-case basis and figure out what
to do with each class and function.

I think it would probably be good to do something similar with cbook.  Both
are dumping grounds for largely unrelated functions. At the very least they
should be organized into modules by their purpose, but I do think some
should be dropped or upstreamed.

There needs to be layers to the interface.  At the bottom there is super
general stuff that will cover (we hope) 100% of use cases.  However, the
cost is a very verbose interface with lots of knobs.  To cope with this
there are higher level function which can deal with 90% of the use cases
and do so by hiding some of the knobs (compare making a 3x3 grid
`subplots(3, 3)` with using  `GridSpec` to figuring out where the axes
edges should go and using `add_subplot([t, l, w, h])` ).  I want to make an
analogy to projecting from a higher dimensional parameter space to a lower
one.

The 'proper' api to use is the simplest one that achieves your goal.  If
you just need a grid of evenly spaced equal size axes use `subplots`, if
you need a grid but with some axes that span columns/rows use `GridSpec`,
if you need 5 axes that partially overlap in the shape of your school logo,
use `add_subplot`.

The point of the high-level APIs is to be easy to use.  If that means
matching the MATLAB api to make it easier for people to switch, then fine.
 I am sympathetic to the notion that the state-machine interface is
confusing (because it maintains hidden state), but it is in fact very
convenient.


On Fri, Oct 25, 2013 at 10:26 AM, Daniele Nicolodi <da...@gr...>wrote:

> On 25/10/2013 15:34, Benjamin Root wrote:
>
> > This has already been done. We have the GridSpec API that everything
> > else maps to, for compatibility. But most people still like
> > add_subplot() and subplots() for some odd reason... I think the primary
> > issue is one of documentation, and we are currently in the process of
> > upgrading that. We always welcome contributions to that effort!
>
> Hello Benjamin,
>
> thanks for your comments.  I'm aware of the solutions you propose, but I
> maintain that the status quo is confusing for new users.
>
> The fact that there are multiple ways of doing the same thing, through
> apparently unrelated interfaces makes the API more difficult to learn
> and less discoverable that it needs to be.  This is probably a
> conseqence of the organic growth of the library with time.
>
> I agree that the primary issue is the documentation, but at the root of
> that I also feel there is the lack of well established best practices
> for the use of Matplotlib. For example you write that people still like
> add_subplot() and subplots() for odd reasons, which are the methods
> others in the lists pointed to. What would be the proper API to use in
> your opinion?  I believe convergence on best practices is paramount to
> the update of the documentation.
>
> I also don't really buy the argument that it is desirable to keep and
> promote APIs that try to emulate the Matlab interface.  Matplotlib is
> different enough to make a 1:1 translation difficult and the Matlab
> design is anyhow broken, IMHO.
>
> Best,
> Daniele
>
> PS: with a new job also came the possibility to finally drop Matlab and
> embrace Python as the main data analysis tool. This means that I can
> dedicate some (at the moment very few) spare cycles to contribute to
> Matplotlib. I would be happy to do so!
>
>
>
> ------------------------------------------------------------------------------
> October Webinars: Code for Performance
> Free Intel webinars can help you accelerate application performance.
> Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most
> from
> the latest Intel processors and coprocessors. See abstracts and register >
> http://pubads.g.doubleclick.net/gampad/clk?id=60135991&iu=/4140/ostg.clktrk
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>



-- 
Thomas A Caswell
PhD Candidate University of Chicago
Nagel and Gardel labs
tca...@uc...
jfi.uchicago.edu/~tcaswell
o: 773.702.7204

On 25/10/2013 15:34, Benjamin Root wrote:

> This has already been done. We have the GridSpec API that everything
> else maps to, for compatibility. But most people still like
> add_subplot() and subplots() for some odd reason... I think the primary
> issue is one of documentation, and we are currently in the process of
> upgrading that. We always welcome contributions to that effort!

Hello Benjamin,

thanks for your comments.  I'm aware of the solutions you propose, but I
maintain that the status quo is confusing for new users.

The fact that there are multiple ways of doing the same thing, through
apparently unrelated interfaces makes the API more difficult to learn
and less discoverable that it needs to be.  This is probably a
conseqence of the organic growth of the library with time.

I agree that the primary issue is the documentation, but at the root of
that I also feel there is the lack of well established best practices
for the use of Matplotlib. For example you write that people still like
add_subplot() and subplots() for odd reasons, which are the methods
others in the lists pointed to. What would be the proper API to use in
your opinion?  I believe convergence on best practices is paramount to
the update of the documentation.

I also don't really buy the argument that it is desirable to keep and
promote APIs that try to emulate the Matlab interface.  Matplotlib is
different enough to make a 1:1 translation difficult and the Matlab
design is anyhow broken, IMHO.

Best,
Daniele

PS: with a new job also came the possibility to finally drop Matlab and
embrace Python as the main data analysis tool. This means that I can
dedicate some (at the moment very few) spare cycles to contribute to
Matplotlib. I would be happy to do so!

Daniele,

On Fri, Oct 25, 2013 at 8:45 AM, Daniele Nicolodi <da...@gr...>wrote:

> On 24/10/2013 21:26, Paul Ivanov wrote:
> > One quick reply:
> >
> > Daniele Nicolodi, on 2013-10-24 21:03,  wrote:
> >> One thing I dislike is, for example, the add_subplot() method:
> >>
> >> f = plt.figure()
> >> a = f.add_subplot(111)
> >> a.plot(x, y)
> >>
> >> it feels completely out of place (why I need to add a subplot if the
> >> only thing I want to do is to create a figure with a single plot in it?)
> >> and kind of magic (what is the number 111?).
> >
> >   f, a = plt.subplots()
> >   a.plot(x, y)
>
> That's better, however to create _sub_ plots to have a single plot into
> a figure still feels weird,


It doesn't feel weird. It feels generalized. It is the same way to add any
number of plots, regardless if it is just one, or twenty. If you don't want
to do it that way, you can just simply do:

fig = plt.figure()
ax = fig.gca()  # "get current axes" automatically creates an axes if one
doesn't exist already

You also have
http://matplotlib.org/api/figure_api.html#matplotlib.figure.Figure.add_axes


> also I would expect it to be a method of the
> Figure class and not a top level function.


It does:
http://matplotlib.org/api/figure_api.html#matplotlib.figure.Figure.add_subplot
This is *the* function that does axes creation for a figure, whether it is
one, or many.



>  Furthermore, most
> documentation refers to add_subplot() and not subplots() which has a
> more understandable function signature.
>
>
subplots() is a recent addition. We are in the process of updating our
documentation. But add_subplot() is not going away because it works just
fine, and it is very familiar to users of Matlab and Octave.



> In principle I think the current API violates the "There should be one--
> and preferably only one --obvious way to do it" rule here, and elsewhere
> :-)
>
>
I feel the way forward should be to create a cleaner API and map the
> current one through a compatibility layer to that.
>
>
This has already been done. We have the GridSpec API that everything else
maps to, for compatibility. But most people still like add_subplot() and
subplots() for some odd reason... I think the primary issue is one of
documentation, and we are currently in the process of upgrading that. We
always welcome contributions to that effort!

Cheers!
Ben Root

Le 25/10/2013 14:57, Pierre Haessig a écrit :
> 2) default NFFT value being hidden from views
>
> used to be def specgram(x, NFFT=256,  Fs=2, ...
> now is     def specgram(x, NFFT=None, Fs=None
>
> I think that NFFT is an important parameter of the spectrum
> computation. It should not be /hidden from the immediate view of the
> user/. The fact it is set to 256 is an arbitrary choice and I think it
> even teaches something to the user (if he doesn't know what it is).
> Such a fixed value is an "invitation to change it". Now with
> NFFT=None, it is more likely to imply "a good choice was made for
> you", which is not true (because there is no such good choice for all
> datasets).
My, mistake, this 2nd point is pointless!

I got confused because I'm not familiar with the docstring convention
which make signatures are hard-written in the docstring. Thanks Todd for
pointing me this.

best,
Pierre

Hi,

Le 21/10/2013 15:58, Todd a écrit :
>
>     2) Should there be two separate functions for these two, or just one
>     function, with a switch argument `unwrap` ? (I guess it would be
>     True by
>     default)
>
>
> I originally was going to do that, but decided against it.  The
> problem is with specgram.  Here, I thought it would be needlessly
> complicated to add an "unwrap" parameter that is only useful for one
> "mode".  To make it obvious to users, I wanted to keep specgram as
> similar as possible to the other plot types, and that involved keeping
> the parameter.
>
> Further, this approach is simpler to code and easier to maintain.
> Having to deal with the "unwrap" parameter would have been more
> difficult to program.  Dealing with both an "unwrap" parameter in some
> cases and a separate "mode" in others would have been even more
> complicated.
>
> Further, _spectral_helper and specgram already have a huge number of
> arguments.  This way I was able to get away with just adding one new
> argument rather than two.

You've convinced me. I didn't have the big picture of your PR when
writing my previous messages. I like the approach you took for specgram,
which put "magnitude", "phase", "angle" on the same level. This indeed
reduce the number of keywords.

Coming back to the readability, what do you think of replacing "phase",
"angle" by "unwrapped phase", "phase". Beyond readability, it also
emphasizes for the reader the idea of "postprocessing" to get the
unwrapped phase, i.e. a something that can have it's issue.

best,
Pierre

Hello,


Now that that PR #2522 is merged, I don't know how much futher
commenting is useful, but I think there are two API details that I feel
could be better :

1) API dissymetry

The new pyplot/axes API is now:

 * 1 function *spectgram* now uses a mode argument to tune this behavior :

*mode*: [ 'default' | 'psd' | 'magnitude' | 'angle' | 'phase' ]
             What sort of spectrum to use.  Default is 'psd'. which takes
             the power spectral density.  'complex' returns the
complex-valued
             frequency spectrum.  'magnitude' returns the magnitude
spectrum.
            'angle' returns the phase spectrum without unwrapping.  'phase'
             returns the phase spectrum with unwrapping.

* 3 new functions *phase_spectrum, angle_spectrum, magnitude_spectrum*
which complement the exising psd/csd

-> I think this contributes to overcrowding axes/pyplot API. I like much
better what is done with specgram so I would propose to add just one new
function, for example *spectrum*(...mode='magnitude/angle/phase'). Using
the same /mode /keyword as for specgram would increase the coherence of
the API.



2) default NFFT value being hidden from views

used to be def specgram(x, NFFT=256,  Fs=2, ...
now is     def specgram(x, NFFT=None, Fs=None

I think that NFFT is an important parameter of the spectrum computation.
It should not be /hidden from the immediate view of the user/. The fact
it is set to 256 is an arbitrary choice and I think it even teaches
something to the user (if he doesn't know what it is). Such a fixed
value is an "invitation to change it". Now with NFFT=None, it is more
likely to imply "a good choice was made for you", which is not true
(because there is no such good choice for all datasets).



best,
Pierre

On 24/10/2013 21:26, Paul Ivanov wrote:
> One quick reply:
> 
> Daniele Nicolodi, on 2013-10-24 21:03,  wrote:
>> One thing I dislike is, for example, the add_subplot() method:
>>
>> f = plt.figure()
>> a = f.add_subplot(111)
>> a.plot(x, y)
>>
>> it feels completely out of place (why I need to add a subplot if the
>> only thing I want to do is to create a figure with a single plot in it?)
>> and kind of magic (what is the number 111?).
>  
>   f, a = plt.subplots()
>   a.plot(x, y)

That's better, however to create _sub_ plots to have a single plot into
a figure still feels weird, also I would expect it to be a method of the
Figure class and not a top level function.  Furthermore, most
documentation refers to add_subplot() and not subplots() which has a
more understandable function signature.

In principle I think the current API violates the "There should be one--
and preferably only one --obvious way to do it" rule here, and elsewhere :-)

I feel the way forward should be to create a cleaner API and map the
current one through a compatibility layer to that.

Cheers,
Daniele

Hi,

Le 22/10/2013 19:14, Todd a écrit :
>
>     Thanks for the feedback. I agree that your documentation does make
>     clear the distinction between "phase" and "angle" and that it has
>     a consistency. I just feel that this distinction does not exist
>     "outside" ...
>
>     But beyond this question of phase vs. angle, I must say I don't
>     see that big a use case for phase/angle spectrums[*] (as opposed
>     to magnitude which are much used). 
>
>
> I personally use phase and angle spectrums a huge amount.  In signal
> processing it is extremely important.  It is a critical component in
> acoustics.  It is also used a lot to separate out signals that have
> been mixed together.  Knowing the phases of signals can also be very
> important in certain optics applications and for radio signals and
> RADAR.  Changes in the phase spectrum over time (like you would get
> from a phase spectrogram) is important for doppler analysis both with
> optical and acoustic signals.
>
> Also, from an educational perspective, anyone taking a digital signal
> processing course will need to produce magnitude/phase plots, probably
> both with and without wrapping (since any decent digital signal
> processing course will teach you about the pitfalls that occur due to
> phase wrapping).  So this will make matplotlib much more useful for
> such courses.
>  
>
>     Also, in many cases, "spectrum" is synonymous with spectral
>     density, which implies "magnitude". In the end I wonder whether
>     the notion of phase even makes sense for a spectrogram ?
>
>
> Yes, particularly electrical engineering.  But there are many other
> fields where spectral density is rarely used, and where more
> "ordinary" magnitude and phase plots are the norm, as I explained in
> the previous paragraphs.
Thanks for dealing with my ignorance. It's true that I have a biased
view on these frequency functions, because I mostly deal with random
signals these days.

In fact I'd like to understand a bit more how phase spectorgram works.
Since the signal must be cut into chunks to make the plot along time,
how is the phase computations "synchronised", that is, how does it use a
common time reference. (because I would imagine that otherwise the phase
would make "jumps" between each window frame). Do you have a pointer for
how this is solved ? (or is this problem just non-existing?).

best,
Pierre

On Thu, Oct 24, 2013 at 12:03 PM, Daniele Nicolodi <da...@gr...> wrote:

> PS: Chris, would you mind sharing the material you put together and
> links to material from which you stole from? Thanks!

I honestly don't think my stuff is any better than the originals: I like these:

Ben Root's Scipy Tutorial -- really nice, Ben!
  https://github.com/WeatherGod/AnatomyOfMatplotlib

>From the software carpentry site:
  https://github.com/swcarpentry/bc/tree/gh-pages/lessons/thw-matplotlib
(apparently originally from Katy and Antony)

-Chris

-- 

Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R            (206) 526-6959   voice
7600 Sand Point Way NE   (206) 526-6329   fax
Seattle, WA  98115       (206) 526-6317   main reception

Chr...@no...

Michael Droettboom, on 2013-10-24 09:41,  wrote:
> I'll post a public URL to watch along once it begins as well.

Here's the youtube video link (which I got from Mike's G+):
https://www.youtube.com/watch?feature=player_embedded&v=hWA6dMiSUiU

best,
-- 
                   _
                  / \
                A*   \^   -
             ,./   _.`\\ / \
            / ,--.S    \/   \
           /  `"~,_     \    \
     __o           ?
   _ \<,_         /:\
--(_)/-(_)----.../ | \
--------------.......J
Paul Ivanov
http://pirsquared.org

One quick reply:

Daniele Nicolodi, on 2013-10-24 21:03,  wrote:
> One thing I dislike is, for example, the add_subplot() method:
> 
> f = plt.figure()
> a = f.add_subplot(111)
> a.plot(x, y)
>
> it feels completely out of place (why I need to add a subplot if the
> only thing I want to do is to create a figure with a single plot in it?)
> and kind of magic (what is the number 111?).
 
  f, a = plt.subplots()
  a.plot(x, y)

that's the way to go there. And if you need to make a regular
grid of subplots, you can pass it the number of rows and number
of columns, and get a 2D array of subplots out for the second
argument.

  f, axes = plt.subplots(2,3)
  axes[0,2].plot(range(10))
  axes[1,1].plot(-np.arange(10))
  f.canvas.draw()

best,
-- 
                   _
                  / \
                A*   \^   -
             ,./   _.`\\ / \
            / ,--.S    \/   \
           /  `"~,_     \    \
     __o           ?
   _ \<,_         /:\
--(_)/-(_)----.../ | \
--------------.......J
Paul Ivanov
http://pirsquared.org

On 24/10/2013 20:39, Chris Barker wrote:
> On Thu, Oct 24, 2013 at 8:29 AM, Michael Droettboom <md...@st...> wrote:
>> Here are the notes with action items from the meeting:
> 
> thanks for posting that. I see:
> 
> pylab - should it stay or should it go?
> 
> Comment from the peanut gallery:
> 
> Go.
> 
> But beyond that, matplotlib.pyplot is a big mess of both the
> matlab-style state-machine current figure, current axis stuff, and
> what you need to do (at least reasonably on the command line) OO
> interface.
> 
> This makes it really hard to teach to newbies -- I just did this last
> night, and made a point to use tutorials that emphasize the OO
> interface (Thanks Ben Root, Katy Huff, and Antony Scopatz, and I'm
> sure others that helped put the materials together that I stole
> from...). However, there were still a number of examples in there that
> just called "plot()" or whatever, and even if there were not, the
> namespace is really cluttered with stuff!
> 
> Anyone like the idea of an matplotlib.ooplot namespace that would have
> just what you need to use the oo style?

Hello,

I agree that the matlab like API should be at least discouraged, however
I think there are some shortcomings both in the documentation and
examples and in the object oriented API and functions exposed through
the pyplot namespace that make switching more cumbersome that it has to bee.

One thing I dislike is, for example, the add_subplot() method:

f = plt.figure()
a = f.add_subplot(111)
a.plot(x, y)

it feels completely out of place (why I need to add a subplot if the
only thing I want to do is to create a figure with a single plot in it?)
and kind of magic (what is the number 111?).

The API is also very old fashion python (getter and setter methods for
example) and many methods try to emulate too much of the bad API design
of matlab (doing completely different things depending on the kind and
number of parameters).

I believe it would be possible to come up with a more modern and lean
API that would be easier and nicer to use.  If we have to deprecate the
matlab style API, maybe it would be worth to replace it with something
substantially better.

PS: Chris, would you mind sharing the material you put together and
links to material from which you stole from? Thanks!


Cheers,
Daniele

On Thu, Oct 24, 2013 at 8:29 AM, Michael Droettboom <md...@st...> wrote:
> Here are the notes with action items from the meeting:

thanks for posting that. I see:

pylab - should it stay or should it go?

Comment from the peanut gallery:

Go.

But beyond that, matplotlib.pyplot is a big mess of both the
matlab-style state-machine current figure, current axis stuff, and
what you need to do (at least reasonably on the command line) OO
interface.

This makes it really hard to teach to newbies -- I just did this last
night, and made a point to use tutorials that emphasize the OO
interface (Thanks Ben Root, Katy Huff, and Antony Scopatz, and I'm
sure others that helped put the materials together that I stole
from...). However, there were still a number of examples in there that
just called "plot()" or whatever, and even if there were not, the
namespace is really cluttered with stuff!

Anyone like the idea of an matplotlib.ooplot namespace that would have
just what you need to use the oo style?

-Chris

-- 

Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R            (206) 526-6959   voice
7600 Sand Point Way NE   (206) 526-6329   fax
Seattle, WA  98115       (206) 526-6317   main reception

Chr...@no...

Three weeks time... see you all there!

(I've also added it to the matplotlib Google Calendar here: 
https://www.google.com/calendar/feeds/79hk8jhvlks8jn8ds4ri1e6q4g%40group.calendar.google.com/public/basic)

Mike

-- 
                    _
|\/|o _|_  _. _ | | \.__  __|__|_|_  _  _ ._ _
|  ||(_| |(_|(/_| |_/|(_)(/_|_ |_|_)(_)(_)| | |

http://www.droettboom.com