create_table: Create a table

Description

The create_table function creates a table object to which further specifications can be added. The object can be added to a report using the add_content function. The object is implemented as an S3 object of class 'table_spec'.

Usage

create_table(
  x,
  show_cols = "all",
  use_attributes = "all",
  width = NULL,
  first_row_blank = FALSE,
  n_format = upcase_parens,
  headerless = FALSE,
  borders = "none",
  header_bold = FALSE,
  continuous = FALSE
)

Arguments

x: The data frame or tibble from which to create the table object.
show_cols: This parameter gives control over which columns in the input data to display on the report by default. Valid values are 'all', 'none', a vector of quoted column names, or a vector of column positions. 'all' means show all columns, unless overridden by the column definitions. 'none' means don't show any columns unless specified in the column definitions. If a vector of column names or positions is supplied, those columns will be shown in the report in the order specified, whether or not a definition is supplied. See the define function for additional information on how to show/hide report columns.
use_attributes: Whether or not to use any formatting attributes assigned to the columns on the input data frame. Valid values are 'all', 'none', or a vector of attribute names to use. Possible attributes that may be used are 'label', 'format', 'width', and 'justify'. By default, any of these attribute values will be applied to the table. For example, if you assign a label to the 'label' attribute of a data frame column, pass that data frame into create_table, and don't override the label value on a define function, the label will appear as a column header on the table. The use_attributes parameter allows you to control this default behavior, and use or ignore data frame attributes as desired.
width: The expected width of the table in the report units of measure. By default, the width setting is NULL, and columns will be sized according to the width of the data and labels. If the width parameter is set, the function will attempt to size the table to the specified width. If the sum of the column widths is less than the specified width, the function will adjust the columns widths proportionally to fit the specified width. If the sum of the column widths is wider than the table width parameter value, the table width parameter will be ignored.
first_row_blank: Whether to place a blank row under the table header. Valid values are TRUE or FALSE. Default is FALSE.
n_format: The formatting function to apply to the header "N=" label. The default formatting function is upcase_parens.
headerless: Whether to create a headerless table. A headerless table displays the table data only. Default is FALSE, meaning the table will have a header.
borders: Whether and where to place a border. Valid values are 'top', 'bottom', 'left', 'right', 'all', 'none', 'outside', 'inside', and 'body'. Default is 'none'. The 'left', 'right', 'outside', 'inside', and 'body' border specifications only apply to RTF, HTML, PDF, and DOCX reports. The 'body' border specification means put borders around only the body of the table.
header_bold: Whether or not the column headers on the tables should be bolded. Valid values are TRUE and FALSE. The default is FALSE.
continuous: If a table crosses multiple pages, it is normally broken into a separate table for each page, and the titles and footnotes are repeated on each page. When the "continuous" parameter is TRUE, the table will instead be a single table, and the titles and footnotes will not be repeated on each page. This parameter currently only works for RTF outputs. Also, this parameter only works for titles and footnotes that are attached to the table body. Titles and footnotes attached to the report will still be shown on every page.

Setting Formatting Attributes

Formatting attributes can be controlled in three ways. By default, formatting attributes assigned to the data frame will be passed through to the reporting functions. The reporting functions will recognize the 'label', 'format', 'width', and 'justify' attributes. In other words, you can control the column label, width, format, and alignment of your report columns simply by assigning those attributes to your data frame. The advantage of using attributes assigned to data frame columns is that you can store those attributes permanently with the data frame, and those attributes will not have to be re-specified for each report. To ignore attributes assigned to the data frame, set the use_attributes parameter to 'none'.

Secondly, attributes can be specified using the column_defaults function. This function allows the user to apply a default set of parameters to one or more columns. If no columns are specified in the var or from and to parameter of this function, the defaults will apply to all columns. Any default parameter value can be overridden by the define function.

Lastly, the define function provides the most control over column parameters. This function provides a significant amount of functionality that cannot be specified elsewhere. See the define function for additional information. The define function will also override any formatting attributes assigned to the data frame, or anything set by the column_defaults function.

Additional Functionality

The create_table function also provides the capabilities to create a "headerless" table. A headerless table is useful when combining two tables into one report. The example below illustrates use of a headerless table.

Since the purpose of the reporter package is to create statistical reports, the create_table function makes it easy to add population counts to the table header. These population counts are added to column labels and spanning header labels using the n parameter on the define or spanning_header functions. The population count is formatted according to the n_format parameter on create_table. The reporter package provides four population count formatting functions. You may create your own formatting function if one of these functions does not meet your needs. See upcase_parens for further details.

Details

A table object is a container to hold information about a table. The only required information for a table is the table data. All other parameters and functions are optional.

By default, the table will display all columns in the data frame. To change this default, use the show_cols parameter. Setting this parameter to 'none' will display none of the columns in the data, unless they are explicitly defined with a define function.

The show_cols parameter also accepts a vector of column positions or column names. When a vector is supplied, create_table will display only those columns on the report, in the order encountered in the vector. The show_cols parameter is the only mechanism in create_table to modify the column order. Otherwise, modify the order prior to sending the data to create_table using the many options available in Base R or supplemental packages.

Examples

Run this code

library(reporter)
library(magrittr)

# Create temp file path
tmp <- file.path(tempdir(), "mtcars.txt")

#Subset cars data
dat <- mtcars[1:10, 1:7]

# Calculate means for all columns
dat_sum <- data.frame(all_cars = "All cars average", as.list(sapply(dat, mean)), 
                      stringsAsFactors = FALSE)

# Get vehicle names into first column
dat_mod <- data.frame(vehicle = rownames(dat), dat, stringsAsFactors = FALSE)
                      
# Create table for averages
tbl1 <- create_table(dat_sum) %>% 
        titles("Table 1.0", "MTCARS Sample Data") %>% 
        column_defaults(width = .5) %>% 
        define(all_cars, label = "", width = 2) %>% 
        define(mpg, format = "%.1f") %>% 
        define(disp, format = "%.1f") %>% 
        define(hp, format = "%.0f") %>% 
        define(qsec, format = "%.2f")

# Create table for modified data
tbl2 <- create_table(dat_mod, headerless = TRUE) %>% 
        column_defaults(width = .5) %>% 
        define(vehicle, width = 2) 

# Create the report object
rpt <- create_report(tmp) %>% 
  add_content(tbl1, align = "left", page_break = FALSE) %>% 
  add_content(tbl2, align = "left") 

# Write the report to the file system
write_report(rpt)

# Write report to console
writeLines(readLines(tmp, encoding = "UTF-8"))

#                                 Table 1.0
#                             MTCARS Sample Data
# 
#                             mpg    cyl   disp     hp   drat     wt   qsec
# -------------------------------------------------------------------------
# All cars average           20.4    5.8  208.6    123  3.538  3.128  18.58
# 
# Mazda RX4                    21      6    160    110    3.9   2.62  16.46
# Mazda RX4 Wag                21      6    160    110    3.9  2.875  17.02
# Datsun 710                 22.8      4    108     93   3.85   2.32  18.61
# Hornet 4 Drive             21.4      6    258    110   3.08  3.215  19.44
# Hornet Sportabout          18.7      8    360    175   3.15   3.44  17.02
# Valiant                    18.1      6    225    105   2.76   3.46  20.22
# Duster 360                 14.3      8    360    245   3.21   3.57  15.84
# Merc 240D                  24.4      4  146.7     62   3.69   3.19     20
# Merc 230                   22.8      4  140.8     95   3.92   3.15   22.9
# Merc 280                   19.2      6  167.6    123   3.92   3.44   18.3
#

Run the code above in your browser using DataLab