Extending documentation for -1null and 1null

[AmelZulji]

Thank you for continuously improving the package, @thomasp85! Version 1.3, with the extended free() functionality and the new wrap_table() addition, is just awesome!

Regarding the documentation for 1null and -1null, I think users will benefit greatly from expanding it. In particular, clarifying how factors in front of null affect plot behavior (especially for fixed-aspect plots) would be highly valuable.

library(ggplot2)
library(patchwork)

p1 <- ggplot(mtcars) +
  geom_point(aes(mpg, disp))

p_fixed <- ggplot(mtcars) +
  geom_point(aes(hp, disp)) +
  ggtitle('Fixed aspect') +
  coord_fixed(1)

patch <- 
  p_fixed + p1 +
  plot_layout(
    widths = unit(c(-1,1), c("null", "null")),
    heights = unit(-1, "null")
    )

The layout below allows p_fixed to expand as the space increases, while p1 fills the remaining space, respecting the aspect ratio of p_fixed.

tmp_file <- tempfile(fileext = ".png")
ggsave(
  filename = tmp_file,
  plot = patch,
  width = 20,
  height = 7,
  units = "cm"
)
print(magick::image_read(tmp_file))
#> # A tibble: 1 × 7
#>   format width height colorspace matte filesize density
#>   <chr>  <int>  <int> <chr>      <lgl>    <int> <chr>  
#> 1 PNG     2362    826 sRGB       FALSE    62996 118x118

Let’s explore how the layout behaves when the width parameter is changed

ggsave(
  filename = tmp_file,
  plot = patch,
  width = 14,
  height = 7,
  units = "cm"
)
print(magick::image_read(tmp_file))
#> # A tibble: 1 × 7
#>   format width height colorspace matte filesize density
#>   <chr>  <int>  <int> <chr>      <lgl>    <int> <chr>  
#> 1 PNG     1653    826 sRGB       FALSE    59163 118x118

The plots scale very nicely, maximizing the available space. However, if we continue decreasing the width, p_fixed will eventually start to shrink.

ggsave(
  filename = tmp_file,
  plot = patch,
  width = 8,
  height = 7,
  units = "cm"
)
print(magick::image_read(tmp_file))
#> # A tibble: 1 × 7
#>   format width height colorspace matte filesize density
#>   <chr>  <int>  <int> <chr>      <lgl>    <int> <chr>  
#> 1 PNG      944    826 sRGB       FALSE    49880 118x118

Note

There are blank white spaces on top and bottom

This behavior occurs because widths = unit(c(-1,1), c("null", "null")) specifies that the width ratio of p_fixed to p1 can only be 1 or lower. In other words, the widths of the plots can be equal, or p1 can be wider than p_fixed, but p_fixed can never be wider than p1.

As a result, in the final figure, as the widths approach equality, the width of p_fixed decreases to maintain the ratio of 1. Consequently, the height of p_fixed also shrinks to preserve the aspect ratio, resulting in blank spaces at the top and bottom.

To prevent this, you can set the layout to allow a higher ratio between the plot widths. For example, by setting the ratio to 5, p_fixed can extend its width until it is five times the width of p1. This adjustment gives the p_fixed plot more breathing room.

patch1 <- 
  p_fixed + p1 +
  plot_layout(
    widths = unit(c(-1,0.2), c("null", "null")),
    heights = unit(-1, "null")
  )

ggsave(
  filename = tmp_file,
  plot = patch1,
  width = 8,
  height = 7,
  units = "cm"
)
print(magick::image_read(tmp_file))
#> # A tibble: 1 × 7
#>   format width height colorspace matte filesize density
#>   <chr>  <int>  <int> <chr>      <lgl>    <int> <chr>  
#> 1 PNG      944    826 sRGB       FALSE    51401 118x118

^{Created on 2024-12-25 with reprex v2.1.0}