Display Sizing

Dynamic scaling

For {tfrmt} and {gt} tables, {docorator} will make its best attempt to fit the display to the allotted area. Specifically, using the default setting of tbl_scale = TRUE will adjust all of the columns to fit the allotted display. This option will first size the stub column(s) (i.e. those columns on the left-hand side containing row group/label information) according to tbl_stub_pct option, then make the remaining columns equal width.

{docorator} uses the function scale_gt() to apply table sizing under the hood. There is no need to call this function directly for the pdf creation but it is used to illustrate the examples below.

Let’s say we have a table with 1 stub column and 4 other columns, like so:

library(gt)
mytbl <- gtcars |>
   dplyr::slice_head(n = 10) |>
   dplyr::select(mfr, model, year, msrp, ctry_origin) |>
   gt(rowname_col = "mfr") |>
   tab_style(
     style = cell_borders(c("left","right")),
     locations = list(cells_body(), cells_stub(), cells_column_labels())
   )

mytbl

If we set tbl_stub_pct=0.4, the stub column will occupy 40% of the full width, and the 4 data columns will each occupy 15% of the full width, totaling 100% width.

mytbl |>
  scale_gt(tbl_stub_pct = 0.4)

For a table with 2 stub columns, like the one below, settings tbl_stub_pct=0.4 will result 20% width for each stub column, resulting in 40% total for both stubs.

mytbl <- gtcars |>
   dplyr::slice_head(n = 10) |>
   dplyr::select(mfr, model, year, msrp, ctry_origin) |>
   gt(
      groupname_col = "ctry_origin", 
      rowname_col = "mfr",
      row_group_as_column = TRUE) |>
   tab_style(
     style = cell_borders(c("left","right")),
     locations = list(cells_body(), cells_stub(), cells_column_labels())
   )

mytbl

mytbl |>
  scale_gt(tbl_stub_pct = 0.4)

Manual scaling

For full control over column widths, it is recommended to use gt::cols_width() on the table prior to {docorator}. By default, {docorator}’s dynamic scaling will override these widths, so it is important to set tbl_scale = FALSE. Note: only widths specified in % (i.e using either “5%” or pct(5)) are accepted. If widths are specified in px then a warning will be issued and dynamic scaling will apply. Widths should also total no more than 100%.

If only a subset of the columns are covered in the cols_width(), {docorator} will expand the remaining columns to fit the allotted width of the display area.

mytbl |> 
  gt::cols_width(
    msrp ~ pct(50)
  ) |> 
  as_docorator(tbl_scale = FALSE)

Alternatively, if all columns are covered in the cols_width(), {docorator} will not apply any resizing to fit the allotted area.

mytbl |> 
  gt::cols_width(
    ctry_origin ~ pct(15),
    mfr ~ pct(10),
    model ~ pct(7),
    year ~ pct(9),
    msrp ~ pct(15)
  ) |> 
  as_docorator(tbl_scale = FALSE)