get_agent_report: Get a summary report from an agent

Description

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

Usage

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
)

Arguments

agent

An agent object of class ptblank_agent.

arrange_by

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").

keep

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".

display_table

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.

size

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).

title

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.

lang

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).

locale

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).

Value

A gt table object if display_table = TRUE or a tibble if display_table = FALSE.

Function ID

6-2

Examples

Run this code

# 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

# }