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'.
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
)The data frame or tibble from which to create the table object.
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.
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.
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.
Whether to place a blank row under the table header. Valid values are TRUE or FALSE. Default is FALSE.
The formatting function to apply to the header "N=" label.
The default formatting function is upcase_parens.
Whether to create a headerless table. A headerless table displays the table data only. Default is FALSE, meaning the table will have a header.
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.
Whether or not the column headers on the tables should be bolded. Valid values are TRUE and FALSE. The default is FALSE.
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.
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.
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.
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.
create_report to create a report,
create_plot to create a plot,
create_text to create text content, and
add_content to append content to a report. Also see
the titles, footnotes, and page_by
functions to add those items to the table if desired.
Other table:
column_defaults(),
define(),
print.table_spec(),
spanning_header(),
stub()
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
#