Documentation

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!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180208/c7c835b6/attachment.html>

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" <marcidy at gmail.com> 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
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180208/186fcf85/attachment.html>

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 <story645 at gmail.com> 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" <marcidy at gmail.com> 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
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180209/a95c3b13/attachment.html>

···

On Fri, Feb 9, 2018 at 2:36 AM, Matt Arcidy <marcidy at gmail.com> 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.

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180212/5136287b/attachment.html>

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180212/7fb12549/attachment.html>

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180212/183f6428/attachment-0001.html>

···

On Mon, Feb 12, 2018 at 5:56 PM, Chris Barker - NOAA Federal < chris.barker at noaa.gov> 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

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180212/3279a0ff/attachment.html>

···

On Mon, Feb 12, 2018 at 8:56 PM, Chris Barker - NOAA Federal < chris.barker at noaa.gov> wrote:

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.

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.

···

On Mon, Feb 12, 2018 at 6:26 PM, Hannah <story645 at gmail.com> wrote:

On Mon, Feb 12, 2018 at 8:56 PM, Chris Barker - NOAA Federal > <chris.barker at noaa.gov> wrote:

_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

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
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180213/305ad8ac/attachment.html>

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 < chris.barker at noaa.gov> 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
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180213/1cbbe135/attachment.html>

Sorry -- way too easy to hit send on my phone....

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

···

On Tue, Feb 13, 2018 at 8:12 AM, Chris Barker - NOAA Federal < chris.barker at noaa.gov> wrote:

--

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

Chris.Barker at noaa.gov
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180213/72597211/attachment.html>

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

···

On Tue, Feb 13, 2018 at 9:23 AM, Matt Arcidy <marcidy at gmail.com> 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.

--

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

Chris.Barker at noaa.gov
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180213/9432d38f/attachment-0001.html>

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?

[1] http://shop.oreilly.com/product/0636920033424.do
[2] http://shop.oreilly.com/product/0636920034919.do

···

On Tue, Feb 13, 2018 at 11:12 AM Chris Barker - NOAA Federal < chris.barker at noaa.gov> 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
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180213/3763fcef/attachment.html>

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.

https://www.youtube.com/results?search_query=anatomy+of+matplotlib+

···

On Tue, Feb 13, 2018 at 6:57 PM Thomas Caswell <tcaswell at gmail.com> 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?

[1] http://shop.oreilly.com/product/0636920033424.do
[2] http://shop.oreilly.com/product/0636920034919.do

On Tue, Feb 13, 2018 at 11:12 AM Chris Barker - NOAA Federal < > chris.barker at noaa.gov> 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
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180213/41bd87fc/attachment-0001.html>

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

[1] http://shop.oreilly.com/product/0636920033424.do
[2] http://shop.oreilly.com/product/0636920034919.do

···

On Feb 13, 2018, at 9:57 AM, Thomas Caswell <tcaswell at gmail.com> wrote:

On Tue, Feb 13, 2018 at 11:12 AM Chris Barker - NOAA Federal < chris.barker at noaa.gov> 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
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180213/8f263682/attachment.html>

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180213/a879c612/attachment.html>

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 <story645 at gmail.com> 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.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180214/8d565afa/attachment.html>

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.

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.

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.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: ranking.py
Type: text/x-python
Size: 4277 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180316/2b4df5a7/attachment-0001.py>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: rankings-test.csv
Type: text/csv
Size: 17333 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180316/2b4df5a7/attachment-0001.csv>

···

On Tue, Feb 13, 2018 at 4:20 PM, Matt Arcidy <marcidy at gmail.com> wrote:

On Tue, Feb 13, 2018, 15:24 Hannah <story645 at gmail.com> wrote: