3  Panel

Group table rows in panels.

3.1 Syntax

To panel a table by STUDY

stable(stdata(), panel = "STUDY")

To set a prefix for the panel header:

stable(
  stdata(), 
  panel = as.panel("STUDY", prefix = "Study: ")
)

3.2 Basics

Paneling your table is a way to group sets of rows together into a “panel” with a panel header rendered in bold font. For example, we can panel a table of mtcars by carb. We will be working with an abbreviated version of mtcars

smcars
.                          name  mpg cyl  disp  hp drat    wt  qsec vs am gear
. Datsun 710         Datsun 710 22.8   4 108.0  93 3.85 2.320 18.61  1  1    4
. Hornet 4 Drive Hornet 4 Drive 21.4   6 258.0 110 3.08 3.215 19.44  1  0    3
. Valiant               Valiant 18.1   6 225.0 105 2.76 3.460 20.22  1  0    3
. Fiat 128             Fiat 128 32.4   4  78.7  66 4.08 2.200 19.47  1  1    4
. Toyota Corolla Toyota Corolla 33.9   4  71.1  65 4.22 1.835 19.90  1  1    4
. Toyota Corona   Toyota Corona 21.5   4 120.1  97 3.70 2.465 20.01  1  0    3
. Fiat X1-9           Fiat X1-9 27.3   4  79.0  66 4.08 1.935 18.90  1  1    4
. Merc 240D           Merc 240D 24.4   4 146.7  62 3.69 3.190 20.00  1  0    4
. Merc 230             Merc 230 22.8   4 140.8  95 3.92 3.150 22.90  1  0    4
. Honda Civic       Honda Civic 30.4   4  75.7  52 4.93 1.615 18.52  1  1    4
.                carb
. Datsun 710        1
. Hornet 4 Drive    1
. Valiant           1
. Fiat 128          1
. Toyota Corolla    1
. Toyota Corona     1
. Fiat X1-9         1
. Merc 240D         2
. Merc 230          2
. Honda Civic       2

Then we pass into stable() and name the paneling column

stable(smcars, panel = "carb") %>% st_as_image()

Now, all of the carb==1 rows are grouped with the heading 1 and similarly the carb==2 rows are grouped with the heading 2 in bold.

This is ok, but a more informative heading would be helpful. To do this, we’ll call as.panel() to both name the panel column and set some options

stable(
  smcars, 
  panel = as.panel("carb", prefix = "carb: ")
) %>% st_as_image()

Note that the prefix is completely specified by the user (including any spaces or a colon.

3.3 panel: additional customization

See the ?rowpanel help topic for arguments to rowpanel() that can be passed to customize the panel. Some of the customizations include

  1. add a prefix to the panel title
  2. skip making panels for certain data in the panel column
  3. make the panel title bold
  4. make the panel title italics
  5. opt out from drawing hline above panels
  6. jut the panel titles so that the rows under the panel header are indented (available starting with version 0.4.1)

3.3.1 jut

We recommend an value more than 1, otherwise the table looks mis-aligned rather than creating offset between panel row and underlying data.

stable(
  stdata(), 
  panel = as.panel("STUDY", jut = 1)
) %>% st_as_image()

This feature requires pmtables 0.4.1 or greater.

3.4 panel: important points

  1. Most of the time, the data frame should be sorted by the panel column
  2. pmtables creates panels by non-repeating values in the panel column; there will be an error if duplicate panel names are found and this can be overridden by passing duplicates_ok to as.panel().