create_table: Create a table

Description Usage Arguments Details See Also Examples

View source: R/table_spec.r

Description

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

Usage

1
2
3
4
5
6
7
8
9
create_table(
  x,
  show_cols = "all",
  use_attributes = "all",
  width = NULL,
  first_row_blank = FALSE,
  n_format = upcase_parens,
  headerless = FALSE
)

Arguments

x

The data frame or tibble from which to create the table object.

show_cols

Whether to show all columns by default. Valid values are 'all', 'none', or a vector of column names. "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 is supplied, those columns will be shown in the report in the order specified, whether or not a definition is supplied.

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 the 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. Default is FALSE.

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 quoted column names. When supplied, create_table will display only those columns on the report.

Column parameters can be specified in three ways. By default, formatting attributes assigned to the data frame will be passed through to the reporting functions. This default behavior can be modifed with the use_attributes parameter on create_table.

Secondly, parameters 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 parameter of this function, the defaults will apply to all columns. Any default parameters can be overridden by the define function.

Lastly, the define function provides the most control over columns parameters. This function provides a significant amount of functionality that cannot be specified elsewhere. See the define function for additional information.

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 rptr 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 function indicated in the n_format function. The 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.

See Also

create_report to create report, create_text to create text content, and add_content to append content to a report.

Other table: column_defaults(), define(), print.table_spec(), spanning_header(), stub()

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
library(rptr)
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)))

# Get vehicle names into first column
dat_mod <- data.frame(vehicle = rownames(dat), dat)
                      
# Create table for averages
tbl1 <- create_table(dat_sum) %>% 
        titles("Table 1.0", "MTCARS Sample Data") %>% 
        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) %>% 
        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))

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

dbosak01/reporter documentation built on Sept. 22, 2020, 3:34 p.m.