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 <tcasw...@uchicago.edu>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 <dani...@grinta.net>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
>> Matplotlib-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>>
>
>
>
> --
> Thomas A Caswell
> PhD Candidate University of Chicago
> Nagel and Gardel labs
> tcasw...@uchicago.edu
> 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
> Matplotlib-devel@lists.sourceforge.net
> 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
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
