Colored lines and examples / documentation

_David_P_Sanders1 · July 5, 2013, 3:13am

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)

dpsanders@…272…149…

http://sistemas.fciencias.unam.mx/~dsanders

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

Tony_S_Yu2 · July 8, 2013, 3:14am

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 <dpsanders@…149…> 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

_David_P_Sanders1 · July 8, 2013, 4:08am

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!

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

github.com

dpsanders/matplotlib-examples/blob/master/colorline.ipynb

{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Examples of plotting (multi-)colored lines"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},

This file has been truncated. show original

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.

···

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

On Thu, Jul 4, 2013 at 10:13 PM, David P. Sanders <dpsanders@...149...>wrote:

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)

dpsanders@...149...
http://sistemas.fciencias.unam.mx/~dsanders

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