[ENH]: Subtitle and caption

[JanPalasek]

Problem

I would like to add subtitle and caption to my axis. Currently, afaik the recommended approach is for subtitle to:

1. Use suptitle of figure together with title of the axis.
2. Manually position your own text to define the subtitle.

However, often I have multiple axes for one figure, where I would like to add subtitle to all of them. In this situation, suptitle is not feasible. Also, positioning it using text API can be a bit tedious, especially when having a lot of axes.

With caption, the recommended approach (afaik) is to position it with text. When I do this in practice, I have to manually tune the position for every graph, depending on the value of xlabel.

Proposed solution

It would be great if we had a bit higher-level API for subtitle and caption. They are very comonly needed when plotting the data.

Two new functions on Axis object like set_subtitle and set_caption would be great!

[oscargus]

I am not sure I follow. There is also set_title if you want to set the title of each subplot/axes https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_title.html

Can you provide an example plot which shows where you want to add text?

[JanPalasek]

I am not sure I follow. There is also set_title if you want to set the title of each subplot/axes https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_title.html

Can you provide an example plot which shows where you want to add text?

Thanks for the quick response. I'll explain with the image below which I took from a ggplot document.

The upper red arrow points to a "subtitle". The lower red arrow points to a "caption".

Example plot

Often you want to have a plot title accompanied with an additional text that provides further information to the title - a subtitle. This lower importance is usually denoted by the subtitle having e.g. a lower font-size.

[oscargus]

Thanks! Now I understand. So the idea is basically, in some sense, that one should be able to have two titles above and one below on each axes?

Currently we support three different titles, all above and located to the left, centered or to the right. I guess that it may be relatively easy to just mimic that with another, optinal. line above and one below, but then I am not really aware of how the title's vertical positioning really work. I believe that optionally reposition the title when a subtitle is added/removed probably is the trickiest part. The way it works now is that the titles are already positioned in the Axes and then they are possibly filled with text.

[JanPalasek]

Thanks! Now I understand. So the idea is basically, in some sense, that one should be able to have two titles above and one below on each axes?

Yes, I believe it can be formulated like that.

I believe that optionally reposition the title when a subtitle is added/removed probably is the trickiest part.

I believe adding caption would need to also solve this because of the xlabel. However, it would greatly benefit the users because it would solve this problem for a lot of plots, where they need to manually tune the coordinates themselves.

[timhoffm]

I see the motivation for this, and I agree we should have better ways to support this. However, I'm a bit wary adding this as Extensions to the Axes. It's relatively special and OTOH one can think of various other similar extensions. So I'm afraid we'd be opening a can of worms by adding a secondary title and similar things below. Maybe we should think more in the direction of a generalized layout, which can contain Axes but also other elements like text or images.

[mwaskom]

I've been asked about this for seaborn plots and would especially +1 the request for a "caption" concept. Given that matplotlib already has title/suptitle I can definitely see how adding "subtitle" would introduce a lot of complexity / ambiguity.

But I think that the "caption" (a label that lives below a plot to the right or left) is a distinct and a very common concept that shouldn't incur a lot of API complexity to support. I think the main thing would be deciding whether a caption is a property of an axes or of a figure?

[story645]

is a distinct and a very common concept

Is in ggplot so I see asks for it all the time https://ggplot2.tidyverse.org/news/index.html?q=Caption#subtitle-and-caption-2-2-0 and came in w/ subtitle, so now I'm getting why those are paired so frequently. Matlab also has a subtitle, but their captioning is same as Matplotlib.

Ideally though I agree w/ Tim that a more generalized layout would probably be more optimal, w/ these as maybe helpers on top.

[jklymak]

First, I don't think adding either of these is particularly hard. They would happen inside of colorbars. caption would be vertically stacked outside of xlabel, and subtitle would be stacked above whatever is on the top xaxis and below title. I think adding both of these is pretty unambiguous and not technically challenging on the face of it.

So to me the questions are a) should we do this at all? b) should we do something more general?

I guess I'm +0.5 for subtitle and something like "caption", though I would not call it caption. These sorts of extra info is pretty common on plots: e.g.:

https://medium.economist.com/charting-new-territory-7f5afb293270

However... I'm not sure subtitle is really that common - it seems the economist tends to have "suptitle" for multiple subplots, and titles on the individual subplots. Does it really make sense to have each subplot to have both a title and a subtitle? That seems potentially cluttered to me, and perhaps folks should be using subfigures instead if they are showing unrelated information in each subplot. Happy to see counter examples where a multi-subplot figure each axes has both a title and a subtitle.

What ggplot is calling a "caption" is really a data annotation. I think this one makes more sense, though I balk at the name "caption" as its really not what LaTeX or a word processing language would call a caption. However, it is often outside the xlabel, and likely makes sense for it to be one per axes.

For the second question, as to whether we should have a more general layout mechanism - we could add one, where we stack things around the axes; OTOH, I'm not sure that making it infinitely flexible is going to lead to a lot of payoff. Attaching different objects to axes have different needs, and my imagination is limited as to what else we would want to stack like that, that in particular we would not have an enforced hierarchy for.

[JanPalasek]

I’m just adding that in a popular book Storytelling with data that I happen to read the subtitle and the caption are used in literally every second plot. And this book is more or less a guide how to make clear easily explainable charts.

[timhoffm]

First, I don't think adding either of these is particularly hard.

That's good to hear from someone with more layout experience. My concerns on creating a mess with this are somewhat alleviated.

For the second question, as to whether we should have a more general layout mechanism - we could add one, where we stack things around the axes; OTOH, I'm not sure that making it infinitely flexible is going to lead to a lot of payoff. Attaching different objects to axes have different needs, and my imagination is limited as to what else we would want to stack like that, that in particular we would not have an enforced hierarchy for.

This was just a quick thought, and I'm not clear myself whether this is useful / worth the effort. Even if it is, a smaller solution could be implemented faster. So, it should not necessary hold up somebody from implementing a caption ad-hoc.
Anyway, let me explain the main idea: Currently, the Axes is the cental layout element. It's placed somewhere, we then attach various things outside, and finally hope that the layout will squeeze everything back in. We could think of this differently: An Axes layout could be interpreted as some kind of grid. Somewhat simplified like this:

It might be easier to define this grid and specify which components go into which fields. The layout mechanism only needs to determine the size of all cells based on their contents.

This would open up new possibilites for the future

• you could introduce placeholders in cells so that they occupy space even though they have no content.
• you could span cells: Should the title be centered over the Axes or over Axes and all decorations?
• you could even put two axes plus decorations in a common grid, which e.g. would guarantee that the xlabels are aligned independed on the amount of space the respective ticklabels need.

Note: I'm not actively planning on following up on this idea, just want to have it floating around in case someone sees benefit.

[aeturrell]

Just want to come in and support addition of subtitle/caption options. This would be massively useful for data visualisation and is often recommended in data viz courses. Currently, one has to either add an annotation or use title and suptitle and then awkwardly move them around. This is possible (all things are possible with matplotlib!) but it's clunky, needs to be adjusted for each plot, and it's not very easy for people new to coding.

I raised this in an issue for seaborn too but it needs to really be solved upstream in Matplotlib.

You can see some of the shenanigans you need to get around it when creating newspaper-grade (well, Financial Times-grade) visualisations using the current options in the examples I've created for people new to data viz here.

Grateful for all the hard work that goes into considering these requests, thanks!