define: Defines a column

Description Usage Arguments Details Value See Also Examples

View source: R/table_spec.r

Description

A function to define the specification for a table column. The define function contains a variety of a parameters to control the appearance of the report. Using the define function, you can control simple options like column alignment and format, but also control more sophisticated options like page wrapping and page breaking.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
define(
  x,
  vars,
  label = NULL,
  format = NULL,
  align = NULL,
  label_align = NULL,
  width = NULL,
  visible = TRUE,
  n = NULL,
  blank_after = FALSE,
  dedupe = FALSE,
  id_var = FALSE,
  page_wrap = FALSE,
  page_break = FALSE,
  indent = NULL,
  label_row = FALSE
)

Arguments

x

The table spec.

vars

The variable name or names to define a column for. Names may be quoted or unquoted. If defining for multiple variables, pass them as a vector of names.

label

The label to use for the column header. If a label is assigned to the label column attribute, it will be used as a default. Otherwise, the column name will be used.

format

The format to use for the column data. The format can be a string format, a formatting function, a lookup list, or a format object. All formatting is performed by the fmtr package. For additional information, see the help for that package.

align

The column alignment. Valid values are "left", "right", "center", and "centre".

label_align

How to align the header labels for this column. Valid values are "left", "right", "center", and "centre".

width

The width of the column in the specified units of measure. The units of measure are specified on the units parameter of the create_report function. If no width is supplied, the write_report function will assign a default width based on the width of the column data and the label. write_report will not set a column width less than the width of the largest word in the data or label. In other words, write_report will not break words.

visible

Whether or not the column should be visible on the report. This parameter can be used as a simple way to drop columns from the report.

n

The n value to place in the "N=" header label. Formatting for the n value will be performed by the formatting function assigned to the n_format parameter on create_table.

blank_after

Whether to place a blank row after unique values of this variable. Valid values are TRUE or FALSE. Default is FALSE.

dedupe

Whether to dedupe the values for this variable. Variables that are deduped only show the value on the first row for each group. This option is commonly used for grouping variables.

id_var

Whether this variable should be considered an ID variable. ID variables are retained on each page when the page is wrapped. ID variables are also moved to the far left of the page.

page_wrap

Force a page wrap on this variable. A page wrap is a vertical page break necessary when the table is too wide to fit on a single page. The excess variables will be wrapped to the next page. Page wraps will continue until all columns are displayed. Use the id_vars parameter to identify rows across wrapped pages.

page_break

You may control when page breaks occur by defining a page break variable yourself, and setting this parameter to TRUE for that variable. Only one page break variable can be defined per table. If two or more variables are defined as a page break, an error will be generated.

indent

How much to indent the column values. Parameter takes a numeric value that will be interpreted according to the units (Unit Of Measure) setting on the report. This parameter can be used to help create a stub column. The default value is NULL, meaning the column should not be indented.

label_row

Whether the values of the variable should be used to create a label row. Valid values are TRUE or FALSE. Default is FALSE. If label_row is set to TRUE, the dedupe parameter will also be set to TRUE. This parameter is often used in conjunction with the stub function to create a stub column.

Details

Column definitions are optional. By default, all columns in the data are displayed in the order and with the formatting attributes assigned to the data frame. The report will use attributes assigned to the data frame such as 'width', 'justify', 'label', and 'format'. In other words, some control over the column formatting is available by manipulating the data frame attributes prior to assigning the data frame to create_table.

The define function is used to provide additional control over column appearance. For example, you may use the define function to assign an "N=" population count, eliminate duplicates from the column, or place a blank row after each unique value of the column. See the parameters below for additional options.

Some of the parameters on the define function are used in the creation of a table stub. See the stub function for additional details.

Value

The modified table spec.

See Also

Other table: column_defaults(), create_table(), 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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
library(rptr)
library(magrittr)
 
# Create temp file name
tmp <- file.path(tempdir(), "mtcars.txt")

# Prepare data
dat <- mtcars[1:10, ]
dat <- data.frame(vehicle = rownames(dat), dat)

# Define table
tbl <- create_table(dat, show_cols = 1:8) %>% 
  define(vehicle, label = "Vehicle", width = 3, id_var = TRUE, align = "left") %>% 
  define(mpg, label = "Miles per Gallon", width = 1) %>% 
  define(cyl, label = "Cylinders", format = "%.1f") %>% 
  define(disp, label = "Displacement") %>% 
  define(hp, label = "Horsepower", page_wrap = TRUE) %>% 
  define(drat, visible = FALSE) %>% 
  define(wt, label = "Weight") %>% 
  define(qsec, label = "Quarter Mile Time", width = 1.5) 


# Create the report
rpt <- create_report(tmp, orientation = "portrait") %>% 
  titles("Listing 2.0", "MTCARS Data Listing with Page Wrap") %>% 
  add_content(tbl, align = "left") %>% 
  page_footer(right = "Page [pg] of [tpg]")

# Write the report
write_report(rpt)

# Send report to console for viewing
writeLines(readLines(tmp))

#                                  Listing 2.0
#                       MTCARS Data Listing with Page Wrap
# 
#                                         Miles per
# Vehicle                                    Gallon Cylinders Displacement
# ------------------------------------------------------------------------
# Mazda RX4                                      21       6.0          160
# Mazda RX4 Wag                                  21       6.0          160
# Datsun 710                                   22.8       4.0          108
# Hornet 4 Drive                               21.4       6.0          258
# Hornet Sportabout                            18.7       8.0          360
# Valiant                                      18.1       6.0          225
# Duster 360                                   14.3       8.0          360
# Merc 240D                                    24.4       4.0        146.7
# Merc 230                                     22.8       4.0        140.8
# Merc 280                                     19.2       6.0        167.6
# 
# ...
# 
#                                                                    Page 1 of 2
#                                  Listing 2.0
#                       MTCARS Data Listing with Page Wrap
# 
# Vehicle                              Horsepower Weight  Quarter Mile Time
# -------------------------------------------------------------------------
# Mazda RX4                                   110   2.62              16.46
# Mazda RX4 Wag                               110  2.875              17.02
# Datsun 710                                   93   2.32              18.61
# Hornet 4 Drive                              110  3.215              19.44
# Hornet Sportabout                           175   3.44              17.02
# Valiant                                     105   3.46              20.22
# Duster 360                                  245   3.57              15.84
# Merc 240D                                    62   3.19                 20
# Merc 230                                     95   3.15               22.9
# Merc 280                                    123   3.44               18.3
# 
# ...
# 
#                                                                    Page 2 of 2

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