[Matplotlib-devel] Documentation

classic Classic list List threaded Threaded
19 messages Options
Reply | Threaded
Open this post in threaded view
|

[Matplotlib-devel] Documentation

Matt Arcidy
Hi All,

Please forgive the presumption of pulling this topic out of from the meeting thread especially as this is also in a self-introduction email.

I want to help with the documentation effort.  I read Tom's article in numfocus and the desired skillset rang true.  I have 10ish years experience writing tech docs, a few 100+ pages.   I write creatively, and I am still somewhat new to matplotlib.  I am happy to work in any capacity, though i am most interested in cranking out the first draft of the book.  

I have looked into the available documentation over the past month+ so I could come with understanding and ideas, some of which I hope are actually good.

Both the meeting thread and Tom requested ideas for reorganizing the tutorials and examples as a place to start, so I'll throw one out: explicit definition of an audience, something to which all the documentation can adhere.

Right now the tutorials are leveled as beginner, intermediate, and expert, which is great, but it's not clear what that means.  Explicitly defining the required skill sets, while not perfect, will allow sorting of concepts and people into each bin.  

As an example, (please excuse the contrivence):

Laura 
- Sophomore in college
- dead set on being a data scientist
- 2 programming classes in python
- never used any kind of CAD software ever (i.e. does not have any concept of a plot beyond a line on graph paper)

Xian 
- 1 week away from Zoology PhD dissertation, under a deadline
- Has used R and Matplotlib to create very basic plots for papers
- Wants to create a plot with species heart size over adult weight, with the marker being a jpg of the species' actual heart, beating at the actual species' heart rate on the plot.

Ayah 
- Post Doc or professional
- 10+ years of plotting experience using various packages but not matplotlib
- has funding to contribute significant functionality, but needs to get up to speed on everything now

Obviously this is just beginner, intermediate, expert, but they can be explicitly targeted/taught based on their skill level.  Laura needs hand-holding, Xian needs a great API reference, Ayah needs a mosaic of everything and a good architecture map.

In the same vein as above, learning paths through the tutorial documents.  There are some separable plotting skills, like visually designing the plot, animation, application development, matplotlib development...etc. Each skill could have beginner/intermediate/expert level tutorials which progress naturally, creating a learning tract for each skill.  Skills can be stacked to flow into specific roles.

Looking at this from outside, the best part about this project is all the information is already there. I have more ideas to dump on you, but I'll postpone until I have a better understanding of where I can fit.

Thanks!

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Hannah
Hi Matt,
I'm super psyched that you're onboard and totally agree with you on the importance of identifying audience. I think that's a lot of where the docs really struggle because the audience is very broad. 

For example, I introduce matplotlib a lot to the following audiences who I don't think you've mentioned yet:

high school students
-little to no programming classes 
-a summer REU 
-only know about the plots they've seen in their science class

humanaties masters and graduate students 
- little/no programming experience
- frame of reference for visualization is usually journalism viz like New York Times or art installations. 
- often don't have or forgot the vocabulary around  scientific and statistical plots (what is a measurment, scale, etc)

Computer Science students 
- undergrad through grad
- taking a visualization course
- have lots of programming experience, but not necessarily in Python
- want to make highly information dense plots or dashboards


And I really would love a survey of the community to get an even better sense of who is using matplotlib.

-Hannah

On Feb 8, 2018 3:30 AM, "Matt Arcidy" <[hidden email]> wrote:
Hi All,

Please forgive the presumption of pulling this topic out of from the meeting thread especially as this is also in a self-introduction email.

I want to help with the documentation effort.  I read Tom's article in numfocus and the desired skillset rang true.  I have 10ish years experience writing tech docs, a few 100+ pages.   I write creatively, and I am still somewhat new to matplotlib.  I am happy to work in any capacity, though i am most interested in cranking out the first draft of the book.  

I have looked into the available documentation over the past month+ so I could come with understanding and ideas, some of which I hope are actually good.

Both the meeting thread and Tom requested ideas for reorganizing the tutorials and examples as a place to start, so I'll throw one out: explicit definition of an audience, something to which all the documentation can adhere.

Right now the tutorials are leveled as beginner, intermediate, and expert, which is great, but it's not clear what that means.  Explicitly defining the required skill sets, while not perfect, will allow sorting of concepts and people into each bin.  

As an example, (please excuse the contrivence):

Laura 
- Sophomore in college
- dead set on being a data scientist
- 2 programming classes in python
- never used any kind of CAD software ever (i.e. does not have any concept of a plot beyond a line on graph paper)

Xian 
- 1 week away from Zoology PhD dissertation, under a deadline
- Has used R and Matplotlib to create very basic plots for papers
- Wants to create a plot with species heart size over adult weight, with the marker being a jpg of the species' actual heart, beating at the actual species' heart rate on the plot.

Ayah 
- Post Doc or professional
- 10+ years of plotting experience using various packages but not matplotlib
- has funding to contribute significant functionality, but needs to get up to speed on everything now

Obviously this is just beginner, intermediate, expert, but they can be explicitly targeted/taught based on their skill level.  Laura needs hand-holding, Xian needs a great API reference, Ayah needs a mosaic of everything and a good architecture map.

In the same vein as above, learning paths through the tutorial documents.  There are some separable plotting skills, like visually designing the plot, animation, application development, matplotlib development...etc. Each skill could have beginner/intermediate/expert level tutorials which progress naturally, creating a learning tract for each skill.  Skills can be stacked to flow into specific roles.

Looking at this from outside, the best part about this project is all the information is already there. I have more ideas to dump on you, but I'll postpone until I have a better understanding of where I can fit.

Thanks!

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel




_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Matt Arcidy
Good points.  I wonder if tagging is better with a search/filter than
only categorization.  Someone could filter/search for tutorials which
only use arithmetic and basic python, or grab all tutorials/examples
that use Axes.xlim, etc.  I guess that's for later though.

I don't know a good way to classify python as
beginner/intermediate/expert. Having taught all those levels, maybe
you have clear insight into that?

Do you have ideas for the survey, how, what etc?  That's a great idea.
I'd love to get as many profiles as possible up front.

I'm attempting to get a handle on all the functions used in the
examples/tutorials (note below). I'd like to categorize the
functions/concepts used for them as well.  Will need categories first
of course.

Those are 3 pretty good tasks I think:
1) classify python by skill level
2) survey ideas
3) gather data on current tutorials/examples and rough categorization

This is just a list, I'm not one to assign anything.  I'll work on
whatever needs to get done.

All:
I would like to be able to go through all the example/tutorial scripts
and pull out which matplotlib modules/functions/objects are used in
each script, just top level.  Since they are scripts and not modules,
I cannot seem to get reflection to work like a for a module (so far
anyways).  If anyone has a good tool I would greatly appreciate it.


Thanks,
-Matt


On Thu, Feb 8, 2018 at 8:15 AM, Hannah <[hidden email]> wrote:

> Hi Matt,
> I'm super psyched that you're onboard and totally agree with you on the
> importance of identifying audience. I think that's a lot of where the docs
> really struggle because the audience is very broad.
>
> For example, I introduce matplotlib a lot to the following audiences who I
> don't think you've mentioned yet:
>
> high school students
> -little to no programming classes
> -a summer REU
> -only know about the plots they've seen in their science class
>
> humanaties masters and graduate students
> - little/no programming experience
> - frame of reference for visualization is usually journalism viz like New
> York Times or art installations.
> - often don't have or forgot the vocabulary around  scientific and
> statistical plots (what is a measurment, scale, etc)
>
> Computer Science students
> - undergrad through grad
> - taking a visualization course
> - have lots of programming experience, but not necessarily in Python
> - want to make highly information dense plots or dashboards
>
>
> And I really would love a survey of the community to get an even better
> sense of who is using matplotlib.
>
> -Hannah
>
> On Feb 8, 2018 3:30 AM, "Matt Arcidy" <[hidden email]> wrote:
>
> Hi All,
>
> Please forgive the presumption of pulling this topic out of from the meeting
> thread especially as this is also in a self-introduction email.
>
> I want to help with the documentation effort.  I read Tom's article in
> numfocus and the desired skillset rang true.  I have 10ish years experience
> writing tech docs, a few 100+ pages.   I write creatively, and I am still
> somewhat new to matplotlib.  I am happy to work in any capacity, though i am
> most interested in cranking out the first draft of the book.
>
> I have looked into the available documentation over the past month+ so I
> could come with understanding and ideas, some of which I hope are actually
> good.
>
> Both the meeting thread and Tom requested ideas for reorganizing the
> tutorials and examples as a place to start, so I'll throw one out: explicit
> definition of an audience, something to which all the documentation can
> adhere.
>
> Right now the tutorials are leveled as beginner, intermediate, and expert,
> which is great, but it's not clear what that means.  Explicitly defining the
> required skill sets, while not perfect, will allow sorting of concepts and
> people into each bin.
>
> As an example, (please excuse the contrivence):
>
> Laura
> - Sophomore in college
> - dead set on being a data scientist
> - 2 programming classes in python
> - never used any kind of CAD software ever (i.e. does not have any concept
> of a plot beyond a line on graph paper)
>
> Xian
> - 1 week away from Zoology PhD dissertation, under a deadline
> - Has used R and Matplotlib to create very basic plots for papers
> - Wants to create a plot with species heart size over adult weight, with the
> marker being a jpg of the species' actual heart, beating at the actual
> species' heart rate on the plot.
>
> Ayah
> - Post Doc or professional
> - 10+ years of plotting experience using various packages but not matplotlib
> - has funding to contribute significant functionality, but needs to get up
> to speed on everything now
>
> Obviously this is just beginner, intermediate, expert, but they can be
> explicitly targeted/taught based on their skill level.  Laura needs
> hand-holding, Xian needs a great API reference, Ayah needs a mosaic of
> everything and a good architecture map.
>
> In the same vein as above, learning paths through the tutorial documents.
> There are some separable plotting skills, like visually designing the plot,
> animation, application development, matplotlib development...etc. Each skill
> could have beginner/intermediate/expert level tutorials which progress
> naturally, creating a learning tract for each skill.  Skills can be stacked
> to flow into specific roles.
>
> Looking at this from outside, the best part about this project is all the
> information is already there. I have more ideas to dump on you, but I'll
> postpone until I have a better understanding of where I can fit.
>
> Thanks!
>
> _______________________________________________
> Matplotlib-devel mailing list
> [hidden email]
> https://mail.python.org/mailman/listinfo/matplotlib-devel
>
>
>
_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Paul Hobson-2

On Fri, Feb 9, 2018 at 2:36 AM, Matt Arcidy <[hidden email]> wrote:
Good points.  I wonder if tagging is better with a search/filter than
only categorization.  Someone could filter/search for tutorials which
only use arithmetic and basic python, or grab all tutorials/examples
that use Axes.xlim, etc. 


To some extent, this already happens with the sphinx-gallery examples. See, for example:
https://matplotlib.org/devdocs/api/_as_gen/matplotlib.pyplot.contourf.html#examples-using-matplotlib-pyplot-contourf

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Hannah
In reply to this post by Matt Arcidy

Sorry for the late reply.

Good points.  I wonder if tagging is better with a search/filter than
only categorization.  Someone could filter/search for tutorials which
only use arithmetic and basic python, or grab all tutorials/examples
that use Axes.xlim, etc.  I guess that's for later though.

Totally agree with you on this, and also wondering if there are ways to tag the documentation with the type of graph the function is creating when the name of the function is domain specific but the graph is used a bit more widely. Specifically thinking about how stackplot is the technical term, but a lot of people know them as stream graphs. Or imshow and matshow are used to create heatmaps.

 
I don't know a good way to classify python as
beginner/intermediate/expert. Having taught all those levels, maybe
you have clear insight into that?
 
I struggle with it too because it's so relative. What for me is intermediate Python is beginner to some and expert to others. Object Oriented seems to be a good demarcation,
but since the suggested way of interacting with mpl is through the OO I dunno how to reconcile that. I wonder if mpl needs a little "intro to using objects" type mini/breakaway section. I've been going through the data camp tutorials and been frustrated that they're all pyplot, but that seems to be the preferred intro-and I wonder if it'd be good for matplotlib to have more bridge documentation that doesn't just show how to do things both ways but explains why the OO way is better. Also a proper simple but object oriented tutorial might help here.  Ben Root and Nicolas Rougier's  tutorials are in this direction.


Do you have ideas for the survey, how, what etc?  That's a great idea.
I'd love to get as many profiles as possible up front.
 
I think something as simple as a google or survey monkey poll, advertised really heavily on twitter/a pop up banner when people come to the docs/the user mailing list/etc. might work. Pretty basic self assessment questions: What's your fluency with Python? How long have you been using Python? How long have you been using Matplolib? Which interface do you use more often? pyplot/OO (with links/hover example of each), and sort of whatever else you feel you'd need for docs.




_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Chris Barker - NOAA Federal



Object Oriented seems to be a good demarcation, 

I don’t think so— writing OO code, that is defining your own classes, subclassing, etc. is non-beginner, but calling methods on existing objects is not: you can’t get very far in python without using the methods of the buil-ins: lists, dicts, strings....

but since the suggested way of interacting with mpl is through the OO

Which does mean calling methods on objects, but that’s about it.

 they're all pyplot, but that seems to be the preferred intro-and I wonder if it'd be good for matplotlib to have more bridge documentation that doesn't just show how to do things both ways but explains why the OO way is better.

Yup. And I don’t think pyplot is any easier for newbies—other than existing Matlab users — admittedly a big group.

Also a proper simple but object oriented tutorial might help here.  Ben Root and Nicolas Rougier's  tutorials are in this direction.

Yes!!

I say introduce the OO interface, then have a “matplotlib for Matlab users” section to translate for them.
.
I'd love to get as many profiles as possible up front.

Just now thought that “Matlab user” is a profile to keep
In mind.

Pretty basic self assessment questions: What's your fluency with Python? How long have you been using Python? How long have you been using Matplolib?

What other languages/plotting libraries are you comfortable with?

-CHB

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Paul Hobson-2

On Mon, Feb 12, 2018 at 5:56 PM, Chris Barker - NOAA Federal <[hidden email]> wrote:
Object Oriented seems to be a good demarcation, 

I don’t think so— writing OO code, that is defining your own classes, subclassing, etc. is non-beginner, but calling methods on existing objects is not: you can’t get very far in python without using the methods of the buil-ins: lists, dicts, strings....

but since the suggested way of interacting with mpl is through the OO

Which does mean calling methods on objects, but that’s about it.

 they're all pyplot, but that seems to be the preferred intro-and I wonder if it'd be good for matplotlib to have more bridge documentation that doesn't just show how to do things both ways but explains why the OO way is better.

Yup. And I don’t think pyplot is any easier for newbies—other than existing Matlab users — admittedly a big group.

Also a proper simple but object oriented tutorial might help here.  Ben Root and Nicolas Rougier's  tutorials are in this direction.

Yes!!

I say introduce the OO interface, then have a “matplotlib for Matlab users” section to translate for them.
.
I'd love to get as many profiles as possible up front.

Just now thought that “Matlab user” is a profile to keep
In mind.

Pretty basic self assessment questions: What's your fluency with Python? How long have you been using Python? How long have you been using Matplolib?

What other languages/plotting libraries are you comfortable with?

-CHB

I like where this discussion is going. If I could wave a magic wand, I set up two parallel introductory tutorials:
1) for all new comers: show basic plotting and customization with the OO interface
2) for new comers with MATLAB backgrounds:  show basic plotting and customization with pyplot on the left and the OO interface on the right

-Paul

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Hannah
In reply to this post by Chris Barker - NOAA Federal


On Mon, Feb 12, 2018 at 8:56 PM, Chris Barker - NOAA Federal <[hidden email]> wrote:

but calling methods on existing objects is not: you can’t get very far in python without using the methods of the buil-ins: lists, dicts, strings....
 
I agree that you can't get very far in Python without it, but it still majorly confuses the audiences I work with. Quite literally, the demarcation my fellowship makes between the Python 101 and 201 we teach is how explicitly we go into using objects. So I think an intro should provide at least a soft explanation of methods/objects/etc.
 
 they're all pyplot, but that seems to be the preferred intro-and I wonder if it'd be good for matplotlib to have more bridge documentation that doesn't just show how to do things both ways but explains why the OO way is better.

Yup. And I don’t think pyplot is any easier for newbies—other than existing Matlab users — admittedly a big group.

It is and it isn't. While it's technically still OO, I think it ends up feeling weirdly declarative just keep layering these things (kinda like ggplot), rather than the explicit here's an axis and attach information to it. It seems like a super trivial distinction but I think it may be a barrier for some people (also why I think a survey could be good here.)


I say introduce the OO interface, then have a “matplotlib for Matlab users” section to translate for them.
I like this approach too. 


_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Matt Arcidy
Just for fun, I made graphs (too big to send, hosted here:
http://arcidy.com) from the backref information.  Functions used in
examples/tutorials are blue,  examples/tutorials are green.  Red edges
are from functions used in more than 10 tutorials to any tutorial that
uses the function.
- "full.png" has everything
- "filtered.png" as the top 10 most used functions removed.  e.g.
usual suspects like pyplot.plot()
They are big and I have residential internet, so might need a small
bit of patience.

Curious if it inspires ideas for analysis.  Longest path?  shortest
path?  what would these even mean?  I'm working on clustering
functions by module, or other groupings.
If you have ideas to analyze it, or you want any code or other format
(e.g. dot) please let me know.  This is all built off the backrefs
from the gallery, so thank you very much for that.  There's structure
so i just need to keep digging.

As an example, I noted there are separate "pyplot.subplot" (<- no 's')
and "pyplot.subplots" tutorials.  Maybe they could be in the same
examples, as one is a wrapper for the other.  Just an example, not
necessarily a good one.

Some specific comments below, but I'm on board with OO.



On Mon, Feb 12, 2018 at 6:26 PM, Hannah <[hidden email]> wrote:

>
>
> On Mon, Feb 12, 2018 at 8:56 PM, Chris Barker - NOAA Federal
> <[hidden email]> wrote:
>>
>>
>> but calling methods on existing objects is not: you can’t get very far in
>> python without using the methods of the buil-ins: lists, dicts, strings....
>
>
> I agree that you can't get very far in Python without it, but it still
> majorly confuses the audiences I work with. Quite literally, the demarcation
> my fellowship makes between the Python 101 and 201 we teach is how
> explicitly we go into using objects. So I think an intro should provide at
> least a soft explanation of methods/objects/etc.
>
>>
>>  they're all pyplot, but that seems to be the preferred intro-and I wonder
>> if it'd be good for matplotlib to have more bridge documentation that
>> doesn't just show how to do things both ways but explains why the OO way is
>> better.
>>
>>
>> Yup. And I don’t think pyplot is any easier for newbies—other than
>> existing Matlab users — admittedly a big group.
The biggest issue I had with pyplot was finding it's limitations.  I
saw that coloring every marker a different color on a line is
possible, which leads me to the documentation for various objects, but
I eventually find that I can't do that with pyplot, I can only provide
one color per line.  There's a mix of undocumented features and
undocumented limitations (or maybe I couldn't find them, but even
then).   stackexchange has an API to search questions, at some point
will be fun/impossible to mine it.

>
>
> It is and it isn't. While it's technically still OO, I think it ends up
> feeling weirdly declarative just keep layering these things (kinda like
> ggplot), rather than the explicit here's an axis and attach information to
> it. It seems like a super trivial distinction but I think it may be a
> barrier for some people (also why I think a survey could be good here.)
>
>>
>> I say introduce the OO interface, then have a “matplotlib for Matlab
>> users” section to translate for them.
>
> I like this approach too.
Agree, users don't need to know they are Object Oriented programming.
I believe Ben created a single image with everything labeled (tick,
marker, etc).  Learning the words/labels might be a sufficient
understanding of Plot Objects without requiring OO programming.  Just
programming with Plot Objects.  Which object to start with?  I was
thinking Figure because if the first thing you "see" and then drilling
down, but not at all married to it.  That could be considered
backwards but at the end of the day Figure is what get's modified so a
narrative arc about what's happening to the figure might work.

>
>
> _______________________________________________
> Matplotlib-devel mailing list
> [hidden email]
> https://mail.python.org/mailman/listinfo/matplotlib-devel
>
_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Chris Barker - NOAA Federal
In reply to this post by Hannah

I agree that you can't get very far in Python without it, but it still majorly confuses the audiences I work with. Quite literally, the demarcation my fellowship makes between the Python 101 and 201 we teach is how explicitly we go into using objects. So I think an intro should provide at least a soft explanation of methods/objects/etc.

THIS is maybe the core issue— are we introducing people to matplotlib, or to the python language via matplotlib. Indeed, to programming itself?

Each of these requires a different type of introduction.

Maybe multiple entry points:

- Know Basic Python?
- Know another programming language?
- New to programming?

Personally, I think it’s “better” to learn the basics of Python first, and then introduce the scipy stack, but the reality is that people have work to accomplish, and it’s often best to learn by solving a problem that interests you — so we should support that.

 they're all pyplot,

The challenge with pyplot is the learning curve — it’s great to able to simply start with:

plot(x, y)



but that seems to be the preferred intro-and I wonder if it'd be good for matplotlib to have more bridge documentation that doesn't just show how to do things both ways but explains why the OO way is better.

Yup. And I don’t think pyplot is any easier for newbies—other than existing Matlab users — admittedly a big group.

It is and it isn't. While it's technically still OO, I think it ends up feeling weirdly declarative just keep layering these things (kinda like ggplot), rather than the explicit here's an axis and attach information to it. It seems like a super trivial distinction but I think it may be a barrier for some people (also why I think a survey could be good here.)


I say introduce the OO interface, then have a “matplotlib for Matlab users” section to translate for them.
I like this approach too. 

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Matt Arcidy
I agree, though I'm curious if we still can't get one entry point which then fans out.  very basic, pyplot.plot() even.  more about plotting than python, matplotlib, math, geometry, etc.

I bet I can hack the Sphinx script to pull all imported/used modules and functions except built -ins.  The examples/tutorials can be tagged with "requires/suggests knowing..." any non-matplotlib function.

People then filter based on matplotlib tags of what they need to learn and select the examples that fit based on the python they are familiar with.  
 
theoretically I can mock this up.

Before doing too much more, I would love to hear any dissenting opinions or even explicit support.  I have been involved in too many projects that ended in a bridge to nowhere.  I'll ask on gitter too.

I definitely want to talk about surveying, I think no matter what that is required.

On Tue, Feb 13, 2018, 08:12 Chris Barker - NOAA Federal <[hidden email]> wrote:

I agree that you can't get very far in Python without it, but it still majorly confuses the audiences I work with. Quite literally, the demarcation my fellowship makes between the Python 101 and 201 we teach is how explicitly we go into using objects. So I think an intro should provide at least a soft explanation of methods/objects/etc.

THIS is maybe the core issue— are we introducing people to matplotlib, or to the python language via matplotlib. Indeed, to programming itself?

Each of these requires a different type of introduction.

Maybe multiple entry points:

- Know Basic Python?
- Know another programming language?
- New to programming?

Personally, I think it’s “better” to learn the basics of Python first, and then introduce the scipy stack, but the reality is that people have work to accomplish, and it’s often best to learn by solving a problem that interests you — so we should support that.

 they're all pyplot,

The challenge with pyplot is the learning curve — it’s great to able to simply start with:

plot(x, y)



but that seems to be the preferred intro-and I wonder if it'd be good for matplotlib to have more bridge documentation that doesn't just show how to do things both ways but explains why the OO way is better.

Yup. And I don’t think pyplot is any easier for newbies—other than existing Matlab users — admittedly a big group.

It is and it isn't. While it's technically still OO, I think it ends up feeling weirdly declarative just keep layering these things (kinda like ggplot), rather than the explicit here's an axis and attach information to it. It seems like a super trivial distinction but I think it may be a barrier for some people (also why I think a survey could be good here.)


I say introduce the OO interface, then have a “matplotlib for Matlab users” section to translate for them.
I like this approach too. 

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Chris Barker - NOAA Federal
In reply to this post by Chris Barker - NOAA Federal
Sorry -- way too easy to hit send on my phone....

On Tue, Feb 13, 2018 at 8:12 AM, Chris Barker - NOAA Federal <[hidden email]> wrote:
The challenge with pyplot is the learning curve — it’s great to able to simply start with:

plot(x, y)

and get the first plot -- like the classic:

print("hello world")

But you'll eventually run into limitations of the pyplot interface, and by then you will have learned a lot of bad habits.

I think the challenge with the OO interface is not so much that you need to use, say:

ax.set_title()

rather than simply

title()

But that you need to do SOMETHING to get that axis object in the first place. And given that to make an axis object you need a figure object first, it's just not as clean as it might be.

But I think that's a significant but small bump in the road on day one....

NOTE: is there any talk of updating the main axis interface to get away from all the "set_*" methods? they are kind of ugly.

-CHB

--

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

[hidden email]

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Chris Barker - NOAA Federal
In reply to this post by Matt Arcidy
On Tue, Feb 13, 2018 at 9:23 AM, Matt Arcidy <[hidden email]> wrote:
I agree, though I'm curious if we still can't get one entry point which then fans out.  very basic, pyplot.plot() even.  more about plotting than python, matplotlib, math, geometry, etc.

sure -- but you can't use matplotlib if you don't know how to call a method (or a function), and maybe a bit about keyword arguments, etc. Granted, many (most?) folks learn well by simply following examples -- show them what to type, and they'll adapt it to their needs, but I think newbies would really benefit from a bit more of the "why you type it this way", and more experienced folks will find that annoying.

Maybe optional "sidebars" in the initial tutorial? -- links to "how this works" kinds of things.

For instance, the first time a keyword argument is used, a link to a brief tutorial on keyword arguments. If people want to know more, they follow that link -- if they already understand kw args, then then skip on by...

-CHB


-- 

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

[hidden email]

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

tcaswell
In reply to this post by Chris Barker - NOAA Federal
For the 'brand new to python' users, can we handle that by linking out to the Scoptaz&Huff[1], VanderPlas [2], or SW carpentry material?  


On Tue, Feb 13, 2018 at 11:12 AM Chris Barker - NOAA Federal <[hidden email]> wrote:

I agree that you can't get very far in Python without it, but it still majorly confuses the audiences I work with. Quite literally, the demarcation my fellowship makes between the Python 101 and 201 we teach is how explicitly we go into using objects. So I think an intro should provide at least a soft explanation of methods/objects/etc.

THIS is maybe the core issue— are we introducing people to matplotlib, or to the python language via matplotlib. Indeed, to programming itself?

Each of these requires a different type of introduction.

Maybe multiple entry points:

- Know Basic Python?
- Know another programming language?
- New to programming?

Personally, I think it’s “better” to learn the basics of Python first, and then introduce the scipy stack, but the reality is that people have work to accomplish, and it’s often best to learn by solving a problem that interests you — so we should support that.

 they're all pyplot,

The challenge with pyplot is the learning curve — it’s great to able to simply start with:

plot(x, y)



but that seems to be the preferred intro-and I wonder if it'd be good for matplotlib to have more bridge documentation that doesn't just show how to do things both ways but explains why the OO way is better.

Yup. And I don’t think pyplot is any easier for newbies—other than existing Matlab users — admittedly a big group.

It is and it isn't. While it's technically still OO, I think it ends up feeling weirdly declarative just keep layering these things (kinda like ggplot), rather than the explicit here's an axis and attach information to it. It seems like a super trivial distinction but I think it may be a barrier for some people (also why I think a survey could be good here.)


I say introduce the OO interface, then have a “matplotlib for Matlab users” section to translate for them.
I like this approach too. 

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Max Linke

For starting with matplotlib and the OO interface I found the `anatomy of matplotlib` talks a good introduction.
I recommend it to new students in my group to learn matplotlib.

On Tue, Feb 13, 2018 at 6:57 PM Thomas Caswell <[hidden email]> wrote:
For the 'brand new to python' users, can we handle that by linking out to the Scoptaz&Huff[1], VanderPlas [2], or SW carpentry material?  


On Tue, Feb 13, 2018 at 11:12 AM Chris Barker - NOAA Federal <[hidden email]> wrote:

I agree that you can't get very far in Python without it, but it still majorly confuses the audiences I work with. Quite literally, the demarcation my fellowship makes between the Python 101 and 201 we teach is how explicitly we go into using objects. So I think an intro should provide at least a soft explanation of methods/objects/etc.

THIS is maybe the core issue— are we introducing people to matplotlib, or to the python language via matplotlib. Indeed, to programming itself?

Each of these requires a different type of introduction.

Maybe multiple entry points:

- Know Basic Python?
- Know another programming language?
- New to programming?

Personally, I think it’s “better” to learn the basics of Python first, and then introduce the scipy stack, but the reality is that people have work to accomplish, and it’s often best to learn by solving a problem that interests you — so we should support that.

 they're all pyplot,

The challenge with pyplot is the learning curve — it’s great to able to simply start with:

plot(x, y)



but that seems to be the preferred intro-and I wonder if it'd be good for matplotlib to have more bridge documentation that doesn't just show how to do things both ways but explains why the OO way is better.

Yup. And I don’t think pyplot is any easier for newbies—other than existing Matlab users — admittedly a big group.

It is and it isn't. While it's technically still OO, I think it ends up feeling weirdly declarative just keep layering these things (kinda like ggplot), rather than the explicit here's an axis and attach information to it. It seems like a super trivial distinction but I think it may be a barrier for some people (also why I think a survey could be good here.)


I say introduce the OO interface, then have a “matplotlib for Matlab users” section to translate for them.
I like this approach too. 

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Chris Barker - NOAA Federal
In reply to this post by tcaswell

On Feb 13, 2018, at 9:57 AM, Thomas Caswell <[hidden email]> wrote:

For the 'brand new to python' users, can we handle that by linking out to the Scoptaz&Huff[1], VanderPlas [2], or SW carpentry material?  

Well, yes — maybe best to not take on too much!

-CHB


On Tue, Feb 13, 2018 at 11:12 AM Chris Barker - NOAA Federal <[hidden email]> wrote:

I agree that you can't get very far in Python without it, but it still majorly confuses the audiences I work with. Quite literally, the demarcation my fellowship makes between the Python 101 and 201 we teach is how explicitly we go into using objects. So I think an intro should provide at least a soft explanation of methods/objects/etc.

THIS is maybe the core issue— are we introducing people to matplotlib, or to the python language via matplotlib. Indeed, to programming itself?

Each of these requires a different type of introduction.

Maybe multiple entry points:

- Know Basic Python?
- Know another programming language?
- New to programming?

Personally, I think it’s “better” to learn the basics of Python first, and then introduce the scipy stack, but the reality is that people have work to accomplish, and it’s often best to learn by solving a problem that interests you — so we should support that.

 they're all pyplot,

The challenge with pyplot is the learning curve — it’s great to able to simply start with:

plot(x, y)



but that seems to be the preferred intro-and I wonder if it'd be good for matplotlib to have more bridge documentation that doesn't just show how to do things both ways but explains why the OO way is better.

Yup. And I don’t think pyplot is any easier for newbies—other than existing Matlab users — admittedly a big group.

It is and it isn't. While it's technically still OO, I think it ends up feeling weirdly declarative just keep layering these things (kinda like ggplot), rather than the explicit here's an axis and attach information to it. It seems like a super trivial distinction but I think it may be a barrier for some people (also why I think a survey could be good here.)


I say introduce the OO interface, then have a “matplotlib for Matlab users” section to translate for them.
I like this approach too. 

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Hannah
In reply to this post by Chris Barker - NOAA Federal

For instance, the first time a keyword argument is used, a link to a brief tutorial on keyword arguments. If people want to know more, they follow that link -- if they already understand kw args, then then skip on by...

I think this approach has a good balance of not reinventing the wheel while also sign posting,

And Matt, I think  creating a narrative of this is a figure, on a figure we put axes, could probably go a ways towards helping with the "why?" of it all.

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Matt Arcidy
I will add args inspection to my Sphinx hacking.  That will also let me discriminate functions calls by tutorial/example as well, plus add that info to search parameters.  plt.plot() usage in examples will greatly benefit from this.

On Tue, Feb 13, 2018, 15:24 Hannah <[hidden email]> wrote:

For instance, the first time a keyword argument is used, a link to a brief tutorial on keyword arguments. If people want to know more, they follow that link -- if they already understand kw args, then then skip on by...

I think this approach has a good balance of not reinventing the wheel while also sign posting,

And Matt, I think  creating a narrative of this is a figure, on a figure we put axes, could probably go a ways towards helping with the "why?" of it all.

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation

Matt Arcidy
Hi all,

Sorry for the long wait, but I have some results to show.

Attached is programmatically generated ranking of  the examples based
on python complexity.

It was done by using the ast module to get every  statement, then each
file was ranked by a method I completely made up, but that can fit
whatever need we have.

It's very basic analysis compared to what is possible, so the ranking
here aren't perfect by any means.  I have not included ranking
matplotlib difficulty as that will require expert input.  As a funny
example,  contour3d.py comes up as one of the easiest tutorials.
That's because the code is easy., the concepts are much harder.
Ranking the mpl objects will provide a much richer and more useful
output.  And of course any dimension we think of can be ranked.

I'm not sure if this _output_ is useful as much as it's a proof of
concept.  But the examples do rank by python complexity now, so that's
good.  I included the ranking algorithm (ranking.py) to show how it
works and what is possible.  I'm doing really naive things like
existence and counts, but even that works to a degree.

There is plenty more information to use that is not in this run: class
inheritance, statement complexity (e.g. # of nested statements in one
expression), number lines of code, number of imports, etc.  many
things are available to use as factors.

Once the ranking is good, creating learning paths can be done,
allowing people to learn python in tandem to mpl, by creating paths
that introduce only 1 or 2 new items, be it a new arg to pyplot or an
object relatively close to another one in an inheritance tree.
Anything that can be programmatically found.  Or perhaps gaps will be
found as well.

And likewise, I can pull out any symbol to use as a search term or a
tag.  I can detect if they are from matplotlib package, or an external
package, and a list probably needs to be maintained to keep track of
what is considered complex and why, but that's a small price I think.

Feedfback?

More than happy to talk anyone's head off about it but I would like to
know if this is useful, and if so, what direction to take first, and
get it focused on specific tasks, etc..


as a note:
This can be used for much more, as I built it to do deep inspection
for other tasks mentioned.  For example, it can be used to look into
doc strings and check that all arguments of the function are in the
doc string.  It can go even further to look at the function body and
see if any arguments are consumed as literals, and then check if those
literals are mentioned in the docs.  And that can all be traced
through any call or attribute assignment (even dict keys, slicing,
etc) and trace things back to an entry point.  Entry point being a
script or scanning the whole package.  At this stage i have the core
functionality to do that, but those functions need to be built.

I also need to write tests and documentation (ha).  And I called it
doctor_doctor which is highly subject to change.


On Tue, Feb 13, 2018 at 4:20 PM, Matt Arcidy <[hidden email]> wrote:

> I will add args inspection to my Sphinx hacking.  That will also let me
> discriminate functions calls by tutorial/example as well, plus add that info
> to search parameters.  plt.plot() usage in examples will greatly benefit
> from this.
>
> On Tue, Feb 13, 2018, 15:24 Hannah <[hidden email]> wrote:
>>
>>
>>> For instance, the first time a keyword argument is used, a link to a
>>> brief tutorial on keyword arguments. If people want to know more, they
>>> follow that link -- if they already understand kw args, then then skip on
>>> by...
>>
>>
>> I think this approach has a good balance of not reinventing the wheel
>> while also sign posting,
>>
>> And Matt, I think  creating a narrative of this is a figure, on a figure
>> we put axes, could probably go a ways towards helping with the "why?" of it
>> all.

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel

ranking.py (5K) Download Attachment
rankings-test.csv (23K) Download Attachment