# Display Sizing

    library(docorator)

## Table sizing

Users can take advantage of {docorator}’s built-in scaling or opt to instead specify column widths via {gt}. Both techniques are described below.

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

| model | year | msrp | ctry_origin
--- | --- | --- | --- | ---
Ford | GT | 2017 | 447000 | United States
Ferrari | 458 Speciale | 2015 | 291744 | Italy
Ferrari | 458 Spider | 2015 | 263553 | Italy
Ferrari | 458 Italia | 2014 | 233509 | Italy
Ferrari | 488 GTB | 2016 | 245400 | Italy
Ferrari | California | 2015 | 198973 | Italy
Ferrari | GTC4Lusso | 2017 | 298000 | Italy
Ferrari | FF | 2015 | 295000 | Italy
Ferrari | F12Berlinetta | 2015 | 319995 | Italy
Ferrari | LaFerrari | 2015 | 1416362 | Italy

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)

| model | year | msrp | ctry_origin
--- | --- | --- | --- | ---
Ford | GT | 2017 | 447000 | United States
Ferrari | 458 Speciale | 2015 | 291744 | Italy
Ferrari | 458 Spider | 2015 | 263553 | Italy
Ferrari | 458 Italia | 2014 | 233509 | Italy
Ferrari | 488 GTB | 2016 | 245400 | Italy
Ferrari | California | 2015 | 198973 | Italy
Ferrari | GTC4Lusso | 2017 | 298000 | Italy
Ferrari | FF | 2015 | 295000 | Italy
Ferrari | F12Berlinetta | 2015 | 319995 | Italy
Ferrari | LaFerrari | 2015 | 1416362 | Italy

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

| model | year | msrp
--- | --- | --- | ---
United States | Ford | GT | 2017 | 447000
Italy | Ferrari | 458 Speciale | 2015 | 291744
Ferrari | 458 Spider | 2015 | 263553
Ferrari | 458 Italia | 2014 | 233509
Ferrari | 488 GTB | 2016 | 245400
Ferrari | California | 2015 | 198973
Ferrari | GTC4Lusso | 2017 | 298000
Ferrari | FF | 2015 | 295000
Ferrari | F12Berlinetta | 2015 | 319995
Ferrari | LaFerrari | 2015 | 1416362

    mytbl |>
      scale_gt(tbl_stub_pct = 0.4)

| model | year | msrp
--- | --- | --- | ---
United States | Ford | GT | 2017 | 447000
Italy | Ferrari | 458 Speciale | 2015 | 291744
Ferrari | 458 Spider | 2015 | 263553
Ferrari | 458 Italia | 2014 | 233509
Ferrari | 488 GTB | 2016 | 245400
Ferrari | California | 2015 | 198973
Ferrari | GTC4Lusso | 2017 | 298000
Ferrari | FF | 2015 | 295000
Ferrari | F12Berlinetta | 2015 | 319995
Ferrari | LaFerrari | 2015 | 1416362

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

## Figure sizing

Figure sizes can be adjusted via the `fig_dim` argument of `as_docorator()`. This argument expects a numeric vector of length 2, where the first and second elements are the height and width in inches, respectively. For example, the default `c(5,8)` translates to a height of 5 inches and width of 8 inches. Note: for `ggplot2` objects, the height and width are applied in the `ggplot2::ggsave()` function when the plot is converted to PNG prior to render. For further control over figure sizing, such as changing the DPI, users can use `ggplot2::ggsave()` directly on the plot object prior to passing it to `as_docorator()` via `png_path`. For example:

    myplot <- ggplot2::ggplot(mtcars, ggplot2::aes(x = wt, y = mpg)) +
      ggplot2::geom_point()

    ggplot2::ggsave(myplot, filename = "myplot.png", width = 6, height = 4, dpi = 300)

    as_docorator(png_path("myplot.png"), display_name = "my_plot") |>
      render_pdf()

## Future developments

More customization options will be offered in future releases. If you have a need to customize something that is not currently offered, please file an issue.