Thread: [Matplotlib-users] Looking for feedback on figures using matplotlib and jupyter notebook

Hi all.

This is about a joint jupyter-notebook / matplotlib problem I've been 
thinking about.
So I'm writing a book using jupyter-notebook, and all my figures are 
generated using matplotlib.

In books, there is usually a figure caption with a running number and 
some description.
 From what I read, the best way to add captions is just using plt.text. 
However, the caption should probably be in the markup,
not in a rendered PNG. I'm not sure if changing the backend might help, 
but that probably doesn't make the notebook happy?

The other problem is that I want to have running numbers that I can 
refer to by a tag (as you would in latex).
That is more of a notebook problem, though.

Any feedback would be very welcome.

Cheers,
Andy

On Thu, Jan 28, 2016 at 3:23 PM, Andreas Mueller <t3...@gm...> wrote:

> Hi all.
>
> This is about a joint jupyter-notebook / matplotlib problem I've been
> thinking about.
> So I'm writing a book using jupyter-notebook, and all my figures are
> generated using matplotlib.
>
> In books, there is usually a figure caption with a running number and
> some description.
>  From what I read, the best way to add captions is just using plt.text.
> However, the caption should probably be in the markup,
> not in a rendered PNG. I'm not sure if changing the backend might help,
> but that probably doesn't make the notebook happy?
>
> The other problem is that I want to have running numbers that I can
> refer to by a tag (as you would in latex).
> That is more of a notebook problem, though.
>
> Any feedback would be very welcome
>

I've been wanting to do something about this problem for a while, but
haven't had the cycles to work on it...  Here's my current idea, perhaps I
can goad you into implementing it :)

I think that IPython.display should provide a Figure object, capable of
wrapping any input image (with nice code to automatically swallow a
matplotlib figure without asking the user to convert it to an image first),
and taking an optional caption.

Figure() would then produce as output the displayed image but with a bit of
nice CSS to center it on the page, along with the caption.

The trick is to send the entire data bundle correctly structured so that,
at the other end, nbconvert could recognize these figures as such, and not
only produce nice HTML, but more importantly, push them into the LaTeX
output with the correct call to \figure, including \caption as well as size
and placement specifiers.

The signature of Figure() might be something like

def Figure(fig, caption=None, width=None, height=None,
           latex_placement=None):


I would try implementing this first as a standalone tool, and once it's
been tested enough in real-world usage with both HTML and LaTeX output from
nbconvert, it could be merged in.  I suspect it's going to take a few
iterations to get it right.

But it's not particularly hard, and someone working on a book would be the
perfect candidate to have enough test cases to be able to iterate until
happy ;)

If you think you want to take a stab at this, don't hesitate to ping us on
the jupyter list. We can help with some of the more obscure parts of
getting this to work on nbconvert (and there may be things I've overlooked
in the sketch above).

Cheers,

f

-- 
Fernando Perez (@fperez_org; http://fperez.org)
fperez.net-at-gmail: mailing lists only (I ignore this when swamped!)
fernando.perez-at-berkeley: contact me here for any direct mail

In mpl, our figure objects get numbers assigned to them by default, but
they can also be strings. These labels are used in the figure window title
bar. Perhaps that existing data could be hijacked? Admittedly, most people
use the string name to give nice short names to their figures, so maybe
those names could be the "tag" name in latex? So, all we would need is some
way to supply the actual caption string.

Ben Root


On Thu, Jan 28, 2016 at 10:17 PM, Fernando Perez <fpe...@gm...>
wrote:

> On Thu, Jan 28, 2016 at 3:23 PM, Andreas Mueller <t3...@gm...> wrote:
>
>> Hi all.
>>
>> This is about a joint jupyter-notebook / matplotlib problem I've been
>> thinking about.
>> So I'm writing a book using jupyter-notebook, and all my figures are
>> generated using matplotlib.
>>
>> In books, there is usually a figure caption with a running number and
>> some description.
>>  From what I read, the best way to add captions is just using plt.text.
>> However, the caption should probably be in the markup,
>> not in a rendered PNG. I'm not sure if changing the backend might help,
>> but that probably doesn't make the notebook happy?
>>
>> The other problem is that I want to have running numbers that I can
>> refer to by a tag (as you would in latex).
>> That is more of a notebook problem, though.
>>
>> Any feedback would be very welcome
>>
>
> I've been wanting to do something about this problem for a while, but
> haven't had the cycles to work on it...  Here's my current idea, perhaps I
> can goad you into implementing it :)
>
> I think that IPython.display should provide a Figure object, capable of
> wrapping any input image (with nice code to automatically swallow a
> matplotlib figure without asking the user to convert it to an image first),
> and taking an optional caption.
>
> Figure() would then produce as output the displayed image but with a bit
> of nice CSS to center it on the page, along with the caption.
>
> The trick is to send the entire data bundle correctly structured so that,
> at the other end, nbconvert could recognize these figures as such, and not
> only produce nice HTML, but more importantly, push them into the LaTeX
> output with the correct call to \figure, including \caption as well as size
> and placement specifiers.
>
> The signature of Figure() might be something like
>
> def Figure(fig, caption=None, width=None, height=None,
>            latex_placement=None):
>
>
> I would try implementing this first as a standalone tool, and once it's
> been tested enough in real-world usage with both HTML and LaTeX output from
> nbconvert, it could be merged in.  I suspect it's going to take a few
> iterations to get it right.
>
> But it's not particularly hard, and someone working on a book would be the
> perfect candidate to have enough test cases to be able to iterate until
> happy ;)
>
> If you think you want to take a stab at this, don't hesitate to ping us on
> the jupyter list. We can help with some of the more obscure parts of
> getting this to work on nbconvert (and there may be things I've overlooked
> in the sketch above).
>
> Cheers,
>
> f
>
> --
> Fernando Perez (@fperez_org; http://fperez.org)
> fperez.net-at-gmail: mailing lists only (I ignore this when swamped!)
> fernando.perez-at-berkeley: contact me here for any direct mail
>
>
> ------------------------------------------------------------------------------
> Site24x7 APM Insight: Get Deep Visibility into Application Performance
> APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
> Monitor end-to-end web transactions and take corrective actions now
> Troubleshoot faster and improve end-user experience. Signup Now!
> http://pubads.g.doubleclick.net/gampad/clk?id=267308311&iu=/4140
> _______________________________________________
> Matplotlib-users mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-users
>
>

Thanks for your input Fernando.
I thought about cross-posting to Jupyter, but I'm glad you also saw it 
here :)
That would help, but not solve all problems.
I guess the Figure could hold a tag for referencing, too. It would be 
nice to get a tag and caption from matplotlib.
Maybe Benjamin's reply would help with that. But it sounds like the 
figure has a single string attached (which is more the tag).
I guess I can do
IPython.display.Figure(matplotlib_figure, caption="stuff", tag="tag")
That would be acceptable, I think.
But how do I reference that in a markup cell? [maybe I should move that 
question to the jupyter list, though]

On 01/28/2016 10:17 PM, Fernando Perez wrote:
> On Thu, Jan 28, 2016 at 3:23 PM, Andreas Mueller <t3...@gm... 
> <mailto:t3...@gm...>> wrote:
>
>     Hi all.
>
>     This is about a joint jupyter-notebook / matplotlib problem I've been
>     thinking about.
>     So I'm writing a book using jupyter-notebook, and all my figures are
>     generated using matplotlib.
>
>     In books, there is usually a figure caption with a running number and
>     some description.
>      From what I read, the best way to add captions is just using
>     plt.text.
>     However, the caption should probably be in the markup,
>     not in a rendered PNG. I'm not sure if changing the backend might
>     help,
>     but that probably doesn't make the notebook happy?
>
>     The other problem is that I want to have running numbers that I can
>     refer to by a tag (as you would in latex).
>     That is more of a notebook problem, though.
>
>     Any feedback would be very welcome
>
>
> I've been wanting to do something about this problem for a while, but 
> haven't had the cycles to work on it... Here's my current idea, 
> perhaps I can goad you into implementing it :)
>
> I think that IPython.display should provide a Figure object, capable 
> of wrapping any input image (with nice code to automatically swallow a 
> matplotlib figure without asking the user to convert it to an image 
> first), and taking an optional caption.
>
> Figure() would then produce as output the displayed image but with a 
> bit of nice CSS to center it on the page, along with the caption.
>
> The trick is to send the entire data bundle correctly structured so 
> that, at the other end, nbconvert could recognize these figures as 
> such, and not only produce nice HTML, but more importantly, push them 
> into the LaTeX output with the correct call to \figure, including 
> \caption as well as size and placement specifiers.
>
> The signature of Figure() might be something like
>
> def Figure(fig, caption=None, width=None, height=None,
>            latex_placement=None):
>
>
> I would try implementing this first as a standalone tool, and once 
> it's been tested enough in real-world usage with both HTML and LaTeX 
> output from nbconvert, it could be merged in.  I suspect it's going to 
> take a few iterations to get it right.
>
> But it's not particularly hard, and someone working on a book would be 
> the perfect candidate to have enough test cases to be able to iterate 
> until happy ;)
>
> If you think you want to take a stab at this, don't hesitate to ping 
> us on the jupyter list. We can help with some of the more obscure 
> parts of getting this to work on nbconvert (and there may be things 
> I've overlooked in the sketch above).
>
> Cheers,
>
> f
>
> -- 
> Fernando Perez (@fperez_org; http://fperez.org)
> fperez.net-at-gmail: mailing lists only (I ignore this when swamped!)
> fernando.perez-at-berkeley: contact me here for any direct mail

On Fri, Jan 29, 2016 at 8:25 AM, Andreas Mueller <t3...@gm...> wrote:

> Thanks for your input Fernando.
> I thought about cross-posting to Jupyter, but I'm glad you also saw it
> here :)
> That would help, but not solve all problems.
> I guess the Figure could hold a tag for referencing, too. It would be nice
> to get a tag and caption from matplotlib.
> Maybe Benjamin's reply would help with that. But it sounds like the figure
> has a single string attached (which is more the tag).
> I guess I can do
> IPython.display.Figure(matplotlib_figure, caption="stuff", tag="tag")
> That would be acceptable, I think.
>

Yes, I'd forgotten about the label ("label" is the LaTeX name for what
you're calling "tag" here).


> But how do I reference that in a markup cell? [maybe I should move that
> question to the jupyter list, though]
>

Yup, this is the slightly trickier part.  A sketch of the solution, we need
to:

- generate a local anchor element for the labeled output.  That's the
easier part, it would be the job of the displayed output from this
hypothetical Figure() object.

It needs to wrap the output in `<a name=label>... </a>`.

- For markdown referencing, you simply do [link text](#label).

- The problem would be latex conversion: by default, the above is converted
to

\protect\hyperlink{label}{link text}

where as you want a \ref{label} call instead.

- You also want this to generate the

Internal cross-referencing is one of Markdown's main weaknesses for complex
more document-oriented workflows that aren't purely HTML oriented.
Markdown is really a thin wrapper around HTML, so it doesn't expose the
rich labeling/referencing semantics of rST or LaTeX.

I didn't say this was a done deal, and there might be some tricky edges to
it :)

Cheers

f

-- 
Fernando Perez (@fperez_org; http://fperez.org)
fperez.net-at-gmail: mailing lists only (I ignore this when swamped!)
fernando.perez-at-berkeley: contact me here for any direct mail