How to handle figure panels in a PDF book output?

[karaesmen]

Description

I'm using Quarto v1.3.433 on macOS 14.7.1 with the following specification in the _quarto.yml

format:
  pdf:
    documentclass: scrreprt

I am having difficulty understanding how figure panels are handled by LaTeX in the book context.
It seems that if multiple figures are in a panel, they don't automatically get sub-figure titles, and if a caption is added to the sub-figures each gets a different figure title including the caption, rather than a subtitle.

Here are two examples showing 4 sub-figures in a panel in Chapter 3 of a quarto book.

Example 1: no caption added at the sub-figure level, and sub-figures don't get any numbering (e.g. Figure 3.1.a would be preferred)

::: {#fig-pca-plots layout-ncol=2 fig-cap="Representative PCA plots showing the first two principal components, which capture the majority of the variance in the data. PCA plots are colored by (a) histology, (b) RNA assay, (c) sample tumor percentage, and (d) tissue site."}

![](PCA_fig1.png){width="50%"}
![](PCA_fig2.png){width="50%"}
![](PCA_fig3.png){width="50%"}
![](PCA_fig4.png){width="50%"}
:::

Example 2: Same setup but with captions for each sub-figure

::: {#fig-pca-plots layout-ncol=2 fig-cap="Representative PCA plots showing the first two principal components, which capture the majority of the variance in the data. PCA plots are colored by (a) histology, (b) RNA assay, (c) sample tumor percentage, and (d) tissue site."}

![a](PCA_fig1.png){width="50%"}
![b](PCA_fig2.png){width="50%"}
![c](PCA_fig3.png){width="50%"}
![d](PCA_fig4.png){width="50%"}
:::

Finally, if a panel figure is too long (or big), is there a way to push it to the next page rather than having it cut off at the end of a single page?

Using the same example from above, but with layout-ncol=1 we see that the figures are cutoff.

::: {#fig-pca-plots layout-ncol=1 fig-cap="Representative PCA plots showing the first two principal components, which capture the majority of the variance in the data. PCA plots are colored by (a) histology, (b) RNA assay, (c) sample tumor percentage, and (d) tissue site."}

![a](PCA_fig1.png){width="50%"}
![b](PCA_fig2.png){width="50%"}
![c](PCA_fig3.png){width="50%"}
![d](PCA_fig4.png){width="50%"}
:::

[mcanouil]

1.3.433 is 1.5 years old. Quarto CLI is currently at 1.6.39.
Unfortunately, I'm not sure we can offer help for a version that old especially because this version is older than a huge refactoring of the cross-reference system which involves this particular matter.

I highly suggest you upgrade your Quarto CLI version to the latest stable version if you can.

Additionally, please provide fully reproducible example we can use to help you.
Make sure to read the documentation on figures: https://quarto.org/docs/authoring/figures.html (Unfortunately, the documentation might contains elements not there in 1.3 thus why you should upgrade).

Finally, figures and other elements like that need to be surrounded by empty line or then will be considered as part of the same line/paragraph. Test the following:

---
title: "Reproducible Quarto Document"
format: pdf
engine: markdown
---

## No empty lines

![An image]({{< placeholder 60 40 >}}){#fig-placeholder1}
![An image]({{< placeholder 60 40 >}}){#fig-placeholder2}
![An image]({{< placeholder 60 40 >}}){#fig-placeholder3}
![An image]({{< placeholder 60 40 >}}){#fig-placeholder4}

## Empty lines

![An image]({{< placeholder 60 40 >}}){#fig-placeholder5}

![An image]({{< placeholder 60 40 >}}){#fig-placeholder6}

![An image]({{< placeholder 60 40 >}}){#fig-placeholder7}

![An image]({{< placeholder 60 40 >}}){#fig-placeholder8}

---

You can share a self-contained "working" (reproducible) Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````).
See https://quarto.org/bug-reports.html#small-is-beautiful-aim-for-a-single-document-with-10-lines.

If you have multiple files (and if it is absolutely required to have multiple files), please share as a Git repository.

R	Python
````qmd --- title: "Reproducible Quarto Document" format: html engine: knitr --- This is a reproducible Quarto document. {{< lipsum 1 >}} ```{r} x <- c(1, 2, 3, 4, 5) y <- c(1, 4, 9, 16, 25) plot(x, y) ``` {#fig-placeholder} {{< lipsum 1 >}} The end after @fig-placeholder. ````	````qmd --- title: "Reproducible Quarto Document" format: html engine: jupyter --- This is a reproducible Quarto document. {{< lipsum 1 >}} ```{python} import matplotlib.pyplot as plt x = [1, 2, 3, 4, 5] y = [1, 4, 9, 16, 25] plt.plot(x, y) plt.show() ``` {#fig-placeholder} {{< lipsum 1 >}} The end after @fig-placeholder. ````

Additionally and if not already given, please share the output of quarto check within a code blocks (i.e., using three backticks ```txt), see https://quarto.org/bug-reports.html#check.

[mcanouil]

Here is an example using 1.6.39

Input

Output

--- title: "Reproducible Quarto Document" format: pdf engine: markdown --- ::: {#fig-placeholder layout-ncol="2"} {#fig-a} {#fig-b} {#fig-c} {#fig-d} Representative PCA plots showing the first two principal components, which capture the majority of the variance in the data. PCA plots are colored by (a) histology, (b) RNA assay, (c) sample tumor percentage, and (d) tissue site. ::: You can cross-reference @fig-a and @fig-b in the text, or the whole figure @fig-placeholder.

[karaesmen]

Thank you very much for the reply.
As recommended, I updated my quarto version to 1.6.39.

As recommended, adding labels to subfigures helped with the subfigure titles.
Unfortunately, even after the update, if a figure panel has too many figures to fit on a single page, some of the figures do not flow onto the next page but instead cut off at the end of the page, as shown in the example above.

We are in a crunch as a team, and I am hesitant to put time into creating a reproducible example. However, I will follow up in issues once I get a chance to work on one.

[mcanouil]

The overflowing issue is a LaTeX everyday issue.
You can try keep-tex: true to have the intermediate LaTeX file in order to see if you can manually fix the issue.

You could also manually insert a pagebreak before the figure, see https://quarto.org/docs/authoring/markdown-basics.html#page-breaks.

And set fig-pos from the figure documentation I mentioned before, see https://quarto.org/docs/authoring/figures.html#figure-position.