We can get an informative summary table from an agent by using the
get_agent_report() function. The table can be provided in two substantially
different forms: as a gt based display table (the default), or, as a
tibble. The amount of fields with intel is different depending on whether or
not the agent performed an interrogation (with the interrogate() function).
Basically, before interrogate() is called, the agent will contain just the
validation plan (however many rows it has depends on how many validation
functions were supplied a part of that plan). Post-interrogation, information
on the passing and failing test units is provided, along with indicators on
whether certain failure states were entered (provided they were set through
actions). The display table variant of the agent report, the default form,
will have the following columns:
i (unlabeled): the validation step number
STEP: the name of the validation function used for the validation step
COLUMNS: the names of the target columns used in the validation step (if applicable)
VALUES: the values used in the validation step, where applicable; this
could be as literal values, as column names, an expression, a set of
sub-validations (for a conjointly() validation step), etc.
TBL: indicates whether any there were any preconditions to apply before interrogation; if not, a script 'I' stands for 'identity' but, if so, a right-facing arrow appears
EVAL: a character value that denotes the result of each validation step functions' evaluation during interrogation
N: the total number of test units for the validation step
PASS: the number of test units that received a pass
FAIL: the fraction of test units that received a pass
W, S, N: indicators that show whether the warn, stop, or notify
states were entered; unset states appear as dashes, states that are set with
thresholds appear as unfilled circles when not entered and filled when
thresholds are exceeded (colors for W, S, and N are amber, red, and blue)
EXT: a column that provides buttons with data extracts for each validation step where failed rows are available (as CSV files)
The small version of the display table (obtained using size = "small")
omits the COLUMNS, TBL, and EXT columns. The width of the small table
is 575px; the standard table is 875px wide.
If choosing to get a tibble (with display_table = FALSE), it will have the
following columns:
i: the validation step number
type: the name of the validation function used for the validation step
columns: the names of the target columns used in the validation step (if applicable)
values: the values used in the validation step, where applicable; for
a conjointly() validation step, this is a listing of all sub-validations
precon: indicates whether any there are any preconditions to apply before interrogation and, if so, the number of statements used
active: a logical value that indicates whether a validation step is
set to "active" during an interrogation
eval: a character value that denotes the result of each validation step functions' evaluation during interrogation
units: the total number of test units for the validation step
n_pass: the number of test units that received a pass
f_pass: the fraction of test units that received a pass
W, S, N: logical value stating whether the warn, stop, or notify
states were entered
extract: a logical value that indicates whether a data extract is available for the validation step
get_agent_report(
agent,
arrange_by = c("i", "severity"),
keep = c("all", "fail_states"),
display_table = TRUE,
size = "standard",
title = ":default:",
lang = NULL,
locale = NULL
)An agent object of class ptblank_agent.
A choice to arrange the report table rows by the validation
step number ("i", the default), or, to arrange in descending order by
severity of the failure state (with "severity").
An option to keep "all" of the report's table rows (the
default), or, keep only those rows that reflect one or more
"fail_states".
Should a display table be generated? If TRUE (the
default), and if the gt package is installed, a display table for the
report will be shown in the Viewer. If FALSE, or if gt is not
available, then a tibble will be returned.
The size of the display table, which can be either "standard"
(the default) or "small". This only applies to a display table (where
display_table = TRUE).
Options for customizing the title of the report. The default is
the keyword ":default:" which produces generic title text that refers to
the pointblank package in the language governed by the lang option.
Another keyword option is ":tbl_name:", and that presents the name of the
table as the title for the report. If no title is wanted, then the
":none:" keyword option can be used. Aside from keyword options, text can
be provided for the title and glue::glue() calls can be used to construct
the text string. If providing text, it will be interpreted as Markdown text
and transformed internally to HTML. To circumvent such a transformation,
use text in I() to explicitly state that the supplied text should not be
transformed.
The language to use for automatic creation of briefs (short
descriptions for each validation step) and for the agent report (a
summary table that provides the validation plan and the results from the
interrogation. By default, NULL will create English ("en") text. Other
options include French ("fr"), German ("de"), Italian ("it"), Spanish
("es"), Portuguese, ("pt"), Chinese ("zh"), and Russian ("ru").
This lang option will override any previously set lang value (e.g., by
the create_agent() call).
An optional locale ID to use for formatting values in the
agent report summary table according the locale's rules. Examples include
"en_US" for English (United States) and "fr_FR" for French (France);
more simply, this can be a language identifier without a country
designation, like "es" for Spanish (Spain, same as "es_ES"). This
locale option will override any previously set locale value (e.g., by the
create_agent() call).
A gt table object if display_table = TRUE or a tibble if
display_table = FALSE.
6-2
Other Interrogate and Report:
interrogate()
# NOT RUN {
# Create a simple table with a
# column of numerical values
tbl <-
dplyr::tibble(a = c(5, 7, 8, 5))
# Validate that values in column
# `a` are always greater than 4
agent <-
create_agent(tbl = tbl) %>%
col_vals_gt(vars(a), value = 4) %>%
interrogate()
# Get a tibble-based report from the
# agent by using `get_agent_report()`
# with `display_table = FALSE`
agent %>%
get_agent_report(display_table = FALSE)
# View a the report by printing the
# `agent` object anytime, but, return a
# gt table object by using this with
# `display_table = TRUE` (the default)
report <- get_agent_report(agent)
class(report)
# What can you do with the report?
# Print it from an R Markdown code,
# use it in an email, put it in a
# webpage, or further modify it with
# the **gt** package
# The agent report as a **gt** display
# table comes in two sizes: "standard"
# (the default) and "small"
small_report <-
get_agent_report(
agent = agent,
size = "small"
)
class(small_report)
# The standard report is 875px wide
# the small one is 575px wide
# }
Run the code above in your browser using DataLab