get_agent_x_list {pointblank}

Get the agent's x-list

Description

The agent's x-list is a record of information that the agent possesses at any given time. The x-list will contain the most complete information after an interrogation has taken place (before then, the data largely reflects the validation plan). The x-list can be constrained to a particular validation step (by supplying the step number to the i argument), or, we can get the information for all validation steps by leaving i unspecified. The x-list is indeed an R list object that contains a veritable cornucopia of information.

For an x-list obtained with i specified for a validation step, the following components are available:

• time_start: the time at which the interrogation began (⁠POSIXct [0 or 1]⁠)

• time_end: the time at which the interrogation ended (⁠POSIXct [0 or 1]⁠)

• label: the optional label given to the agent (chr [1])

• tbl_name: the name of the table object, if available (chr [1])

• tbl_src: the type of table used in the validation (chr [1])

• tbl_src_details: if the table is a database table, this provides further details for the DB table (chr [1])

• tbl: the table object itself

• col_names: the table's column names (chr [ncol(tbl)])

• col_types: the table's column types (chr [ncol(tbl)])

• i: the validation step index (int [1])

• type: the type of validation, value is validation function name (chr [1])

• columns: the columns specified for the validation function (⁠chr [variable length]⁠)

• values: the values specified for the validation function (⁠mixed types [variable length]⁠)

• briefs: the brief for the validation step in the specified lang (chr [1])

• eval_error, eval_warning: indicates whether the evaluation of the step function, during interrogation, resulted in an error or a warning (lgl [1])

• capture_stack: a list of captured errors or warnings during step-function evaluation at interrogation time (list [1])

• n: the number of test units for the validation step (num [1])

• n_passed, n_failed: the number of passing and failing test units for the validation step (num [1])

• f_passed: the fraction of passing test units for the validation step, n_passed / n (num [1])

• f_failed: the fraction of failing test units for the validation step, n_failed / n (num [1])

• warn, stop, notify: a logical value indicating whether the level of failing test units caused the corresponding conditions to be entered (lgl [1])

• lang: the two-letter language code that indicates which language should be used for all briefs, the agent report, and the reporting generated by the scan_data() function (chr [1])

If i is unspecified (i.e., not constrained to a specific validation step) then certain length-one components in the x-list will be expanded to the total number of validation steps (these are: i, type, columns, values, briefs, eval_error, eval_warning, capture_stack, n, n_passed, n_failed, f_passed, f_failed, warn, stop, and notify). The x-list will also have additional components when i is NULL, which are:

• report_object: a gt table object, which is also presented as the default print method for a ptblank_agent

• email_object: a blastula email_message object with a default set of components

• report_html: the HTML source for the report_object, provided as a length-one character vector

• report_html_small: the HTML source for a narrower, more condensed version of report_object, provided as a length-one character vector; The HTML has inlined styles, making it more suitable for email message bodies

Usage

get_agent_x_list(agent, i = NULL)

Arguments

agent

The pointblank agent object

⁠obj:<ptblank_agent>⁠ // required

A pointblank agent object that is commonly created through the use of the create_agent() function.

i

A validation step number

⁠scalar<integer>⁠ // default: NULL (optional)

The validation step number, which is assigned to each validation step in the order of invocation. If NULL (the default), the x-list will provide information for all validation steps. If a valid step number is provided then x-list will have information pertaining only to that step.

Value

An x_list object.

Examples

Create a simple data frame with a column of numerical values.

tbl <- dplyr::tibble(a = c(5, 7, 8, 5))

tbl
#> # A tibble: 4 x 1
#>       a
#>   <dbl>
#> 1     5
#> 2     7
#> 3     8
#> 4     5

Create an action_levels() list with fractional values for the warn, stop, and notify states.

al <-
  action_levels(
    warn_at = 0.2,
    stop_at = 0.8,
    notify_at = 0.345
  )

Create an agent (giving it the tbl and the al objects), supply two validation step functions, then interrogate.

agent <-
  create_agent(
    tbl = tbl,
    actions = al
  ) %>%
  col_vals_gt(columns = a, value = 7) %>%
  col_is_numeric(columns = a) %>%
  interrogate()

Get the f_passed component of the agent x-list.

x <- get_agent_x_list(agent)

x$f_passed

#> [1] 0.25 1.00

Function ID

8-1

See Also

Other Post-interrogation: all_passed(), get_data_extracts(), get_sundered_data(), write_testthat_file()