define | R Documentation |
A function to define 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 width, but also control more
sophisticated options like page wrapping and page breaking.
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,
standard_eval = FALSE,
style = NULL
)
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. If you want to pass an R variable of names,
set the |
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, a user-defined
format, or a formatting list.
All formatting is performed by the |
align |
The column alignment. Valid values are "left", "right", "center", and "centre". By default, text columns will be left aligned and numeric columns will be right aligned. |
label_align |
How to align the header labels for this column.
Valid values are "left", "right", "center", and "centre". By default,
the label alignment will follow any alignment set on the column |
width |
The width of the column in the specified units of measure.
The units of measure are specified on the |
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
|
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 of 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 |
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. The parameter takes a
numeric value that will be interpreted according to the |
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 |
standard_eval |
A TRUE or FALSE value indicating whether to
use standard evaluation on the |
style |
A |
Column definitions are optional. By default, all columns in the data are displayed in the order 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
. See
create_table
for more details.
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 variable.
See the parameter documentation for additional options.
Some of the parameters on the define
function are used in the
creation of a table stub. Specifically, the label_row
and
indent
parameters participate in the creation of the stub column.
See the stub
function for further
information.
A single column definition may be defined for multiple variables.
To create a definition for multiple variables, pass the variables as
a quoted or unquoted vector. When creating a single definition for
multiple variables, the parameters will be unified across those variables.
Note that some parameters (such as page_break
) may only be set
once per report, and cannot be shared across multiple variables.
The modified table spec.
Other table:
column_defaults()
,
create_table()
,
print.table_spec()
,
spanning_header()
,
stub()
library(reporter)
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, stringsAsFactors = FALSE)
# 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, encoding = "UTF-8"))
# 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
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.