Introduction to rtables

Layout Instructions

In the code above we first described the table and assigned that description to a variable l. We then built the table using the actual data with build_table. The description of a table is called a table layout. basic_table is the start of every table layout and contains the information that we have one column representing all data. The analyze instruction adds to the layout that the age variable should be analyzed with the mean analysis function and the result should be rounded to 1 decimal place.

Hence, a layout is “pre-data”, that is, it’s a description of how to build a table once we get data. We can look at the layout isolated:

l

A Pre-data Table Layout

Column-Split Structure:
 () 

Row-Split Structure:
age (** analysis **) 

The general layouting instructions are summarized below:

• basic_table is a layout representing a table with zero rows and one column
• Nested splitting
  • in row space: split_rows_by, split_rows_by_multivar, split_rows_by_cuts, split_rows_by_cutfun, split_rows_by_quartiles
  • in column space: split_cols_by, split_cols_by_cuts, split_cols_by_cutfun, split_cols_by_quartiles
• Summarizing Groups: summarize_row_groups
• Analyzing Variables: analyze, analyze_against_baseline, analyze_colvars, analyze_row_groups

using those functions it is possible to create a wide variety of tables as we will show in this document.

Adding Column Structure

We will now add more structure to the columns by adding a column split based on the factor variable arm:

l <- basic_table() %>%
  split_cols_by("arm") %>%
  analyze("age", afun = mean, format = "xx.x")

build_table(l, df)

       Arm A   Arm B
————————————————————
mean   39.5    39.4 

The resulting table has one column per factor level of arm. So the data represented by the first column is df[df$arm == "ARM A", ]. Hence, the split_cols_by partitions the data among the columns by default.

Column splitting can be done in a recursive/nested manner by adding sequential split_cols_by layout instruction. It’s also possible to add a non-nested split. Here we splitting each arm further by the gender:

l <- basic_table() %>%
  split_cols_by("arm") %>%
  split_cols_by("gender") %>%
  analyze("age", afun = mean, format = "xx.x")

build_table(l, df)

           Arm A           Arm B    
       Female   Male   Female   Male
————————————————————————————————————
mean    38.8    40.1    39.6    39.2

The first column represents the data in df where df$arm == "A" & df$gender == "Female" and the second column the data in df where df$arm == "A" & df$gender == "Male", and so on.

Adding Row Structure

So far, we have created layouts with analysis and column splitting instructions, i.e. analyze and split_cols_by, respectively. This resulted with a table with multiple columns and one data row. We will add more row structure by stratifying the mean analysis by country (i.e. adding a split in the row space):

l <- basic_table() %>%
  split_cols_by("arm") %>%
  split_cols_by("gender") %>%
  split_rows_by("country") %>%
  analyze("age", afun = mean, format = "xx.x")

build_table(l, df)

             Arm A           Arm B    
         Female   Male   Female   Male
——————————————————————————————————————
CAN                                   
  mean    38.2    40.3    40.3    38.9
USA                                   
  mean    39.2    39.7    38.9    39.6

In this table the data used to derive the first data cell (average of age of female canadians in Arm A) is where df$country == "CAN" & df$arm == "Arm A" & df$gender == "Female". This cell value can also be calculated manually:

mean(df$age[df$country == "CAN" & df$arm == "Arm A" & df$gender == "Female"])

[1] 38.22447

Adding Group Information

When adding row splits we get by default label rows for each split level, for example CAN and USA in the table above. Besides the column space subsetting, we have now further subsetted the data for each cell. It is often useful when defining a row splitting to display information about each row group. In rtables this is referred to as content information, i.e. mean on row 2 is a descendant of CAN (visible via the indenting, though the table has an underlying tree structure that is not of importance for this vignette). In order to add content information and turn the CAN label row into a content row the summarize_row_groups function is required. By default, the count (nrows) and percentage of data relative to the column associated data is calculated:

l <- basic_table() %>%
  split_cols_by("arm") %>%
  split_cols_by("gender") %>%
  split_rows_by("country") %>%
  summarize_row_groups() %>%
  analyze("age", afun = mean, format = "xx.x")

build_table(l, df)

                  Arm A                     Arm B         
           Female        Male        Female        Male   
——————————————————————————————————————————————————————————
CAN      45 (46.9%)   64 (61.0%)   46 (50.0%)   62 (57.9%)
  mean      38.2         40.3         40.3         38.9   
USA      51 (53.1%)   41 (39.0%)   46 (50.0%)   45 (42.1%)
  mean      39.2         39.7         38.9         39.6   

The relative percentage for average age of female Canadians is calculated as follows:

df_cell <- subset(df, df$country == "CAN" & df$arm == "Arm A" & df$gender == "Female")
df_col_1 <- subset(df, df$arm == "Arm A" & df$gender == "Female")

c(count = nrow(df_cell), percentage = nrow(df_cell)/nrow(df_col_1))

     count percentage 
  45.00000    0.46875 

so the group percentages per row split sum up to 1 for each column.

We can further split the row space by dividing each country by handedness:

l <- basic_table() %>%
  split_cols_by("arm") %>%
  split_cols_by("gender") %>%
  split_rows_by("country") %>%
  summarize_row_groups() %>%
  split_rows_by("handed") %>%
  analyze("age", afun = mean, format = "xx.x")

build_table(l, df)

                    Arm A                     Arm B         
             Female        Male        Female        Male   
————————————————————————————————————————————————————————————
CAN        45 (46.9%)   64 (61.0%)   46 (50.0%)   62 (57.9%)
  Left                                                      
    mean      38.9         40.4         40.3         37.7   
  Right                                                     
    mean      36.6         40.2         40.2         40.6   
USA        51 (53.1%)   41 (39.0%)   46 (50.0%)   45 (42.1%)
  Left                                                      
    mean      40.4         39.7         39.2         40.1   
  Right                                                     
    mean      36.9         39.8         38.5         39.0   

Next, we further add a count and percentage summary for handedness within each country:

l <- basic_table() %>%
  split_cols_by("arm") %>%
  split_cols_by("gender") %>%
  split_rows_by("country") %>%
  summarize_row_groups() %>%
  split_rows_by("handed") %>%
  summarize_row_groups() %>%
  analyze("age", afun = mean, format = "xx.x")

build_table(l, df)

                    Arm A                     Arm B         
             Female        Male        Female        Male   
————————————————————————————————————————————————————————————
CAN        45 (46.9%)   64 (61.0%)   46 (50.0%)   62 (57.9%)
  Left     32 (33.3%)   42 (40.0%)   26 (28.3%)   37 (34.6%)
    mean      38.9         40.4         40.3         37.7   
  Right    13 (13.5%)   22 (21.0%)   20 (21.7%)   25 (23.4%)
    mean      36.6         40.2         40.2         40.6   
USA        51 (53.1%)   41 (39.0%)   46 (50.0%)   45 (42.1%)
  Left     34 (35.4%)   19 (18.1%)   25 (27.2%)   25 (23.4%)
    mean      40.4         39.7         39.2         40.1   
  Right    17 (17.7%)   22 (21.0%)   21 (22.8%)   20 (18.7%)
    mean      36.9         39.8         38.5         39.0