matplotlib-devel

[matplotlib-devel] Colored lines and examples / documentation

[David P. S. <dps...@gm...>]

Hi,

It was great to meet many of the Matplotlib developers at SciPy 2013. I had
a great time and I learnt a huge amount, which I am slowly starting to
digest.

In particular, without the Matplotlib sprint, I would never have got off
the ground -- many thanks to all those who took the time to be patient with
me!

I have been working, as a first step, on colored line support. This is not,
of course, new -- it's all in LineCollection. However, as a user,
LineCollection is intimidating and difficult to understand, and does not
lead to easy experimentation (I speak from experience).

At Tony's suggestion, the first step was to rewrite the
multicolored_line.py example.
You can find my first attempt as an IPython notebook at

https://github.com/dpsanders/matplotlib-examples/blob/master/linecolor.ipynb

or

http://nbviewer.ipython.org/urls/raw.github.com/dpsanders/matplotlib-examples/master/linecolor.ipynb

Please let me have any comments before I attempt the next step of making a
pull request.
It seems to me that IPython notebooks are quite a natural format for such
examples, especially with a view to having interactive examples in the
future.

I have tried, as discussed in the sprint, to separate the data processing
from the plotting.
The function "linecolor" (the only other reasonable name that I thought of
was "colorline") should be able to be extracted without too much effort
(hopefully?) into the axes module and into pyplot.

What is the situation with tagging the examples? If the examples are being
refactored, it would seem to at least be a natural moment to start adding
tags, even if nothing is actually done with them yet.


Along these lines, it seems to me that there is a lot of other
functionality which is difficult to get at for the average user who does
not understand collections or patches.

For example, there is an 'arrow' function in pyplot, which just exposes the
FancyArrow patch, but there is no corresponding 'circle', 'ellipse' etc.
function for those patches.
I think this would be a great addition -- what is the general consensus?

By the way, I only understood what an 'axes' object is yesterday, even
though I have been using Matplotlib for several years. The documentation
that I found seems to assume that the user is coming from Matlab and
already implicitly understands what 'axes' refers to.


Some more general comments which I have been led to in this process:

- Ben made the comment that it was very important to have figures in the
documentation for each function. I completely agree with this. It seems to
me that a simple way to achieve this would be to have one example for each
function, with the name of the example file being the same as the name of
the function (à la Matlab!) Thus I have (re-)named the script as
"linecolor.py".

- At the moment, there seem to be too many places with examples:
screenshots, examples, gallery, scipy cookbook, figures for each function,
etc.
I think that the (refactored) gallery is the solution, and is where people
should be pointed -- the screenshots page and the examples page do not seem
to me to be useful / necessary.

- Also during the BoF / sprint, style sheets were discussed several times.
Tony seems to have already solved this problem in his mpltools package -- I
would suggest that this could be brought straight into Matplotlib?

Thanks to everybody for a great package (and for reading all this, if you
get this far). Please let me know if this is (not) the right place to
discuss such things.

Best wishes,
David.



-- 
**************************************************************************
Dr. David P. Sanders

Profesor Titular A / Associate Professor
Departamento de Física, Facultad de Ciencias
Universidad Nacional Autónoma de México (UNAM)

dps...@gm...
http://sistemas.fciencias.unam.mx/~dsanders

Cubículo / office: #414
Tel.: +52 55 5622 4965

Re: [matplotlib-devel] Colored lines and examples / documentation

[Tony Yu <ts...@gm...>]

Hi David,

Sorry for the delay in replying. It was good meeting you last week.
Comments inline with a lot of parts cut out.


On Thu, Jul 4, 2013 at 10:13 PM, David P. Sanders <dps...@gm...>wrote:
>
> I have been working, as a first step, on colored line support. This is
> not, of course, new -- it's all in LineCollection. However, as a user,
> LineCollection is intimidating and difficult to understand, and does not
> lead to easy experimentation (I speak from experience).
>

I agree that LineCollection isn't the most user-friendly thing to use.
Personally, I'd be in favor of something like your `linecolor` suggestion,
but I'd understand if the core-devs have concerns about feature creep.


> At Tony's suggestion, the first step was to rewrite the
> multicolored_line.py example.
> You can find my first attempt as an IPython notebook at
>
>
> https://github.com/dpsanders/matplotlib-examples/blob/master/linecolor.ipynb
>
> or
>
>
> http://nbviewer.ipython.org/urls/raw.github.com/dpsanders/matplotlib-examples/master/linecolor.ipynb
>

This looked pretty interesting when I first looked at it, but it seems to
be down now.


> Please let me have any comments before I attempt the next step of making a
> pull request.
> It seems to me that IPython notebooks are quite a natural format for such
> examples, especially with a view to having interactive examples in the
> future.
>

Using IPython notebooks as examples would be really beneficial in the long
run, as discussed during the BoF. I struggled with implementing support for
interleaved text, code, and plots for the scikit-image gallery (so that
examples could have real explanations). IPython notebooks are a more
natural format for this, but they're not quite there yet---specifically
nbconvert is still evolving (though this should be integrated into the next
release). That said, someone will need to write the code that takes the
output from nbconvert and integrates it with the current Sphinx code that
generates the gallery. Most of this will be straightforward but tedious.


> What is the situation with tagging the examples? If the examples are being
> refactored, it would seem to at least be a natural moment to start adding
> tags, even if nothing is actually done with them yet.
>

This is a great idea. I wish I had suggested this in my original MEP. I'm
not sure if there's been progress on adding an interface for tags, but we
should be adding tags during any clean ups to the examples so they're ready
in the future.

- Also during the BoF / sprint, style sheets were discussed several times.
> Tony seems to have already solved this problem in his mpltools package --
> I would suggest that this could be brought straight into Matplotlib?
>

This was my original plan. At the time I wrote the original, the rc parser
wasn't exposed to the user. That's been fixed now, but I haven't found the
time to integrate changes into Matplotlib proper. If anyone else would like
to have a go at it, they are more than welcome. Otherwise, I'll get to it
at some point ... hopefully.

Cheers!
-Tony

Re: [matplotlib-devel] Colored lines and examples / documentation

[David P. S. <dps...@gm...>]

On Sun, Jul 7, 2013 at 10:14 PM, Tony Yu <ts...@gm...> wrote:

> Hi David,
>
> Sorry for the delay in replying. It was good meeting you last week.
> Comments inline with a lot of parts cut out.
>

Hi Tony,

It was great to meet you too!


>
>
> On Thu, Jul 4, 2013 at 10:13 PM, David P. Sanders <dps...@gm...>wrote:
>>
>> I have been working, as a first step, on colored line support. This is
>> not, of course, new -- it's all in LineCollection. However, as a user,
>> LineCollection is intimidating and difficult to understand, and does not
>> lead to easy experimentation (I speak from experience).
>>
>
> I agree that LineCollection isn't the most user-friendly thing to use.
> Personally, I'd be in favor of something like your `linecolor` suggestion,
> but I'd understand if the core-devs have concerns about feature creep.
>

Yes, I do understand your point, but I feel strongly that providing simple
interfaces for otherwise complicated concepts / syntax is important, and
very much in the spirit of matplotlib as I understand it.



>
>
>> At Tony's suggestion, the first step was to rewrite the
>> multicolored_line.py example.
>> You can find my first attempt as an IPython notebook at
>>
>>
>> https://github.com/dpsanders/matplotlib-examples/blob/master/linecolor.ipynb
>>
>> or
>>
>>
>> http://nbviewer.ipython.org/urls/raw.github.com/dpsanders/matplotlib-examples/master/linecolor.ipynb
>>
>
> This looked pretty interesting when I first looked at it, but it seems to
> be down now.
>

Apologies, I decided that 'colorline' was a better name than 'linecolor'
(since 'colorline' suggests that we are going to color a line, i.e. it puts
the verb and the noun in the correct order!), so I changed the notebook to

https://github.com/dpsanders/matplotlib-examples/blob/master/colorline.ipynb


http://nbviewer.ipython.org/urls/raw.github.com/dpsanders/matplotlib-examples/master/colorline.ipynb




>
>
>> Please let me have any comments before I attempt the next step of making
>> a pull request.
>>
>

I am trying to get to making a pull request, but am having trouble
incorporating the plot correctly into the gallery:
I have been trying to include colorline.py in the correct place in the
examples tree to have it added automatically to the gallery.
Somebody (don't remember who exactly -- Mike?) showed me how to do this
during the sprint, but I have been unable to reproduce the steps
successfully.

Could you please remind me exactly where I should put the file, and what
the correct sequence of commands to execute is? Is there a special format
that the file should have? For example, it seems that it should only have
one  plt.show()  following the other examples with multiple plots -- is
that right?
(I once managed to get a single one of the plots to show in the gallery,
and have not been able to reproduce that feat since!)



>  It seems to me that IPython notebooks are quite a natural format for
>> such examples, especially with a view to having interactive examples in the
>> future.
>>
>
> Using IPython notebooks as examples would be really beneficial in the long
> run, as discussed during the BoF. I struggled with implementing support for
> interleaved text, code, and plots for the scikit-image gallery (so that
> examples could have real explanations). IPython notebooks are a more
> natural format for this, but they're not quite there yet---specifically
> nbconvert is still evolving (though this should be integrated into the next
> release). That said, someone will need to write the code that takes the
> output from nbconvert and integrates it with the current Sphinx code that
> generates the gallery. Most of this will be straightforward but tedious.
>

The current git master of ipython indeed has nbconvert integrated. The
Python script output is also in my git repository -- these kind of outputs
should be easy to parse.
(Though I personally have no idea where to even start with something like
that. Any suggestions? Is there some kind of standard package for this kind
of thing?)



>
>
>> What is the situation with tagging the examples? If the examples are
>> being refactored, it would seem to at least be a natural moment to start
>> adding tags, even if nothing is actually done with them yet.
>>
>
> This is a great idea. I wish I had suggested this in my original MEP. I'm
> not sure if there's been progress on adding an interface for tags, but we
> should be adding tags during any clean ups to the examples so they're ready
> in the
>

I agree that it should be added to the MEP. From my point of view, the
exact tags that should be used may well be something that evolves over time.



>
> - Also during the BoF / sprint, style sheets were discussed several times.
>> Tony seems to have already solved this problem in his mpltools package --
>> I would suggest that this could be brought straight into Matplotlib?
>>
>
> This was my original plan. At the time I wrote the original, the rc parser
> wasn't exposed to the user. That's been fixed now, but I haven't found the
> time to integrate changes into Matplotlib proper. If anyone else would like
> to have a go at it, they are more than welcome. Otherwise, I'll get to it
> at some point ... hopefully.
>

OK, great.

Best,
David.


>
> Cheers!
> -Tony
>



-- 
**************************************************************************
Dr. David P. Sanders

Profesor Titular A / Associate Professor
Departamento de Física, Facultad de Ciencias
Universidad Nacional Autónoma de México (UNAM)

dps...@gm...
http://sistemas.fciencias.unam.mx/~dsanders

Cubículo / office: #414
Tel.: +52 55 5622 4965