Allow interactive visualizations to be "figures" (and referencable)

[NatalieZelenka]

I have a mixture of interactive and non-interactive figures in my jupyter book. I'd like to be able to reference the interactive ones in the same way as the others.

I've tried using glue (to glue the interactive figure and then use that in a glue:figure directive), and I've tried using a normal figure directive and putting the path as a link to standalone html to embed.

I'd be happy if either of those ways worked so that I could use {ref} and {numref} directives as normal.

Edit: As a stop gap, I've been editing the built html to replace the tag with an

[choldgraf]

Hmmmm, one thing you could try doing as another stop-gap is to include a title with some of the figures, so that you could reference the title via a title anchor like so:

(my-anchor-name)=
## My title

I think something like that might also work for admonitions, but not sure. I don't think you can directly reference interactive figures. I'll mark this as an enhancement!

[NatalieZelenka]

Thanks for considering this :)

In terms of referencing, I'm sure that the anchor trick would work, but reading this back, I realise that I didn't describe what I wanted super well, which is for interactive figures to be included as figures, so that they are numbered + captioned (in keeping with the rest of the figures), i.e. it would be nice for consistency. I reference all of my other figures using {numref} (e.g. "Figure 3.2") which I think is where the my lack of clarity was coming from.

I am using Jupyter Book for my thesis, just to give you some context.

[choldgraf]

Amazing - totally agree that this would be useful.

[chrisjsewell]

Hey @NatalieThurlby

which is for interactive figures to be included as figures, so that they are numbered + captioned (in keeping with the rest of the figures)

Have you looked at https://jupyterbook.org/content/code-outputs.html#images? This seems to be exactly what you are asking for?

[choldgraf]

@chrisjsewell would that work for, say, an Altair plot or something? I think the assumption @NatalieThurlby made was that it would only work for static images.

If I recall, glue is not going to work for things that aren't static, so maybe the issue is that @NatalieThurlby was using this pattern instead of the "embed metadata in your code-cell to format the output". @chrisjsewell is it correct that the metadata approach you describe is a way to reference interactive figures in a way that glue cannot? If so, then we should document that because it's a nice workaround!

[chrisjsewell]

I think the assumption @NatalieThurlby made was that it would only work for static images.

ah yes good point, that is currently correct (it only applies to image type outputs), although it certainly should be feasible to extend this to other types of output (but not necessarily as easy to achieve "out-of-the-box" with Sphinx)

[stoffprof]

I'm not sure what is meant by static or interactive in the discussion above. I came here because I am looking for a way to reference a "figure" created by a code cell using matplotlib. It's not an interactive plot, but it is generated by code. Not sure I'm following the discussion above, but it seems to me that this also isn't currently possible without a workaround. Is this correct?

[joelostblom]

We are also encountering this issue when trying to create and introductory Python book for datascience. A current workaround for this is to insert and empty figure reference just under the visualization and use that to reference the Chart outputeed from the code just above. Since figure references do not work with empty figures, we included an image of just a single white pixel as a base64 encoded string:

```{figure} data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7
:figclass: caption-hack
:name: your-fig-name

Your caption goes here
```

This ensures that figures are numbered automatically and avoids current issues with numbering these as in https://github.com/executablebooks/jupyter-book/issues/1401. Anothe advantage of including the custom figclass is that you can change the text positioning in your CSS file. For example, it looks a bit better to center plot output just like regular figures, and to position the figure text higher up closer to the plot, so you can include the following:

img {
    display: block;
    margin-left: auto;
    margin-right: auto;
}

.caption-hack img {
    margin-bottom: -30px;
}

---

One of my students also discovered the glueing does seem to work for interactive outputs such as altair plots, so hopefully Jupyter Book can automate a solution with gluing that does not involve the author to have to manually assign plots to variable names and glue them into the cell just underneath. Alternatively automating the insertion of the empty figure ref, but that seems more hacky.

The following worked for an html altair plot for my student: