Guiding principles

Please do not set the figure size and style unless there is a good reason to do so.

Use code generated figures whenever possible rather than include static files.

See also

Configuration A QuantEcon lecture series will set the figure size and padding style by default in the _config.yml. This configuration can be found in the QuantEcon lecture repo setup guide

Plots and figures can be either generated from code or included through the use of static image files (i.e. png or pdf) using the figure directive.

See also

The jupyter-book documentation for figures and code generated images are useful resources.

The following rules apply when including both figure types:

  1. elminating all titles embedded in matplotlib (i.e. no ax.set_title)

  2. add title metadata to the figure directive or code-cell metadata as documented in the jupyter-book docs

  3. use lower case for captions, except for the first letter (and proper nouns)

  4. keep the caption title down to about 5~6 words max

  5. set a descriptive name for use as a reference with numref

  6. axis labels should be lower case (“time” not “Time”, etc.)

  7. keep the box around matplotlib figures for consistency across the lectures (i.e. do not use ax.splines[['top']].set_visible(False))

  8. use a lw=2 for all matplotlib figures that have line charts

  9. Figures should be approximately 80% to 100% of the width of text to ensure they are easy to read


See the documentation to see how to use the numref role.

Code generated figures

Make sure your code returns a single figure object from the code cell.

To caption these figures you need to use mystnb metadata on the {code-cell} directive such as

For additional information see the myst-nb docs

Plotly Generated Figures#

Plotly images are a good way to add interactivity to a lecture and make the data easier to explore thanks to hover tip tools etc.


Date: 22 Feb 2024 The usual way of adding Figure captions using mystnb cell level configuration will not work at this time as plotly returns advanced mime type objects that causes mystnb to produce two captions for each plotly object. This in turn causes sphinx to complain about duplicate figure labels.

To include plotly figures we need to use the following pattern to ensure both html and pdf are supported.

Please include a {only} latex directive after the figure that includes a link back to the website for any plotly plots

This link will always follow the pattern https://<lecture-series>{filename}.html#{labelref}.


```{code-cell} python
import as px
fig = px.scatter(x=[0, 1, 2, 3, 4], y=[0, 1, 4, 9, 16])

```{only} latex
This figure is interactive you may [click here to see this figure on the website](

This snippet would look like the following:

import as px
fig = px.scatter(x=[0, 1, 2, 3, 4], y=[0, 1, 4, 9, 16])
ModuleNotFoundError                       Traceback (most recent call last)
Cell In[1], line 1
----> 1 import as px
      2 fig = px.scatter(x=[0, 1, 2, 3, 4], y=[0, 1, 4, 9, 16])

ModuleNotFoundError: No module named 'plotly'

You will notice that the {only} latex information is not seen here as that will only be processed by the latex builder.


You may use the {ref} role to reference the figure in the document

{ref}`Plotly scatter plot <fig-scatter-example>`. 

such as Plotly scatter plot but you need to supply the title text in the link.

You cannot use {numref} at this time.