---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

# Figures

```{admonition} 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.
```

```{seealso} 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](config:repo:lecture:figure-size)
```

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.

```{seealso}
The jupyter-book documentation for [figures](https://jupyterbook.org/en/stable/content/figures.html?highlight=image#figures) and [code generated images](https://jupyterbook.org/en/stable/content/code-outputs.html#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](https://jupyterbook.org/en/stable/reference/cheatsheet.html?highlight=numref#figures-and-images)
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

```{tip}
See the [documentation](https://jupyterbook.org/en/stable/reference/cheatsheet.html?highlight=numref#referencing-figures) to see how to use the `numref` role.
```

````{admonition} Code generated figures
:class: tip

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

```{code-cell} ipython3
---
mystnb:
  figure:
    caption: GDP per capita vs. life expectancy
    name: fig-gdppc-le
---
<code>
```

```{warning}
Captioning a `{code-cell}` this way wraps its output in a LaTeX `figure` **float**.

A float nested inside an `exercise`, `solution`, or any `prf:` directive breaks the PDF build with `! LaTeX Error: Not in outer par mode.`

So do **not** add `mystnb: figure:` caption metadata to a `{code-cell}` that lives inside one of those directives --- leave the cell uncaptioned (it still renders as an image).
```

For additional information [see the myst-nb docs](https://myst-nb.readthedocs.io/en/latest/render/format_code_cells.html#images-and-figures)
````

## 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.

```{warning}
**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>.quantecon.org/{filename}.html#{labelref}`. 

Example:

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

```{only} latex
This figure is interactive you may [click here to see this figure on the website](https://intro.quantecon.org/plotly.html#plotlyfig)
```
````

This snippet would look like the following:

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

```{only} latex
This figure is interactive you may [click here to see this figure on the website](https://manual.quantecon.org/styleguide/figures.html#fig-scatter-example)
```

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

````{warning}
You may use the `{ref}` role to reference the figure in the document
```md
{ref}`Plotly scatter plot <fig-scatter-example>`. 
```
such as {ref}`Plotly scatter plot <fig-scatter-example>` but **you need to supply the title text in the link**.

You **cannot** use `{numref}` at this time. 
````