The conjointly()
validation function, the expect_conjointly()
expectation
function, and the test_conjointly()
test function all check whether test
units at each index (typically each row) all pass multiple validations. We
can use validation functions that validate row units (the col_vals_*()
series), check for column existence (col_exists()
), or validate column type
(the col_is_*()
series). Because of the imposed constraint on the allowed
validation functions, the ensemble of test units are either comprised rows of
the table (after any common preconditions
have been applied) or are single
test units (for those functions that validate columns).
Each of the functions used in a conjointly()
validation step (composed
using multiple validation function calls) ultimately perform a rowwise test
of whether all sub-validations reported a pass for the same test units. In
practice, an example of a joint validation is testing whether values for
column a
are greater than a specific value while adjacent values in column
b
lie within a specified range. The validation functions to be part of the
conjoint validation are to be supplied as one-sided R formulas (using a
leading ~
, and having a .
stand in as the data object). The validation
function can be used directly on a data table or with an agent object
(technically, a ptblank_agent
object) whereas the expectation and test
functions can only be used with a data table.
conjointly( x, ..., .list = list2(...), preconditions = NULL, actions = NULL, step_id = NULL, label = NULL, brief = NULL, active = TRUE ) expect_conjointly( object, ..., .list = list2(...), preconditions = NULL, threshold = 1 ) test_conjointly( object, ..., .list = list2(...), preconditions = NULL, threshold = 1 )
x | A data frame, tibble ( |
---|---|
... | a collection one-sided formulas that consist of validation
functions that validate row units (the |
.list | Allows for the use of a list as an input alternative to |
preconditions | An optional expression for mutating the input table
before proceeding with the validation. This is ideally as a one-sided R
formula using a leading |
actions | A list containing threshold levels so that the validation step
can react accordingly when exceeding the set levels. This is to be created
with the |
step_id | One or more optional identifiers for the single or multiple
validation steps generated from calling a validation function. The use of
step IDs serves to distinguish validation steps from each other and provide
an opportunity for supplying a more meaningful label compared to the step
index. By default this is |
label | An optional label for the validation step. This label appears in the agent report and for the best appearance it should be kept short. |
brief | An optional, text-based description for the validation step. If
nothing is provided here then an autobrief is generated by the agent,
using the language provided in |
active | A logical value indicating whether the validation step should
be active. If the validation function is working with an agent, |
object | A data frame, tibble ( |
threshold | A simple failure threshold value for use with the
expectation ( |
For the validation function, the return value is either a
ptblank_agent
object or a table object (depending on whether an agent
object or a table was passed to x
). The expectation function invisibly
returns its input but, in the context of testing data, the function is
called primarily for its potential side-effects (e.g., signaling failure).
The test function returns a logical value.
If providing multiple column names in any of the supplied validation step
functions, the result will be an expansion of sub-validation steps to that
number of column names. Aside from column names in quotes and in vars()
,
tidyselect helper functions are available for specifying columns. They
are: starts_with()
, ends_with()
, contains()
, matches()
, and
everything()
.
Having table preconditions
means pointblank will mutate the table just
before interrogation. Such a table mutation is isolated in scope to the
validation step(s) produced by the validation function call. Using
dplyr code is suggested here since the statements can be translated to
SQL if necessary. The code is most easily supplied as a one-sided R
formula (using a leading ~
). In the formula representation, the .
serves
as the input data table to be transformed (e.g.,
~ . %>% dplyr::mutate(col_a = col_b + 10)
). Alternatively, a function could
instead be supplied (e.g.,
function(x) dplyr::mutate(x, col_a = col_b + 10)
).
Often, we will want to specify actions
for the validation. This argument,
present in every validation function, takes a specially-crafted list
object that is best produced by the action_levels()
function. Read that
function's documentation for the lowdown on how to create reactions to
above-threshold failure levels in validation. The basic gist is that you'll
want at least a single threshold level (specified as either the fraction of
test units failed, or, an absolute value), often using the warn_at
argument. This is especially true when x
is a table object because,
otherwise, nothing happens. For the col_vals_*()
-type functions, using
action_levels(warn_at = 0.25)
or action_levels(stop_at = 0.25)
are good
choices depending on the situation (the first produces a warning when a
quarter of the total test units fails, the other stop()
s at the same
threshold level).
Want to describe this validation step in some detail? Keep in mind that this
is only useful if x
is an agent. If that's the case, brief
the agent
with some text that fits. Don't worry if you don't want to do it. The
autobrief protocol is kicked in when brief = NULL
and a simple brief will
then be automatically generated.
A pointblank agent can be written to YAML with yaml_write()
and the
resulting YAML can be used to regenerate an agent (with yaml_read_agent()
)
or interrogate the target table (via yaml_agent_interrogate()
). When
conjointly()
is represented in YAML (under the top-level steps
key as a
list member), the syntax closely follows the signature of the validation
function. Here is an example of how a complex call of conjointly()
as a
validation step is expressed in R code and in the corresponding YAML
representation.
# R statement agent %>% conjointly( ~ col_vals_lt(., vars(a), 8), ~ col_vals_gt(., vars(c), vars(a)), ~ col_vals_not_null(., vars(b)), preconditions = ~ . %>% dplyr::filter(a < 10), actions = action_levels(warn_at = 0.1, stop_at = 0.2), label = "The `conjointly()` step.", active = FALSE ) # YAML representation steps: - conjointly: fns: - ~col_vals_lt(., vars(a), 8) - ~col_vals_gt(., vars(c), vars(a)) - ~col_vals_not_null(., vars(b)) preconditions: ~. %>% dplyr::filter(a < 10) actions: warn_fraction: 0.1 stop_fraction: 0.2 label: The `conjointly()` step. active: false
In practice, both of these will often be shorter as only the expressions for
validation steps are necessary. Arguments with default values won't be
written to YAML when using yaml_write()
(though it is acceptable to include
them with their default when generating the YAML by other means). It is also
possible to preview the transformation of an agent to YAML without any
writing to disk by using the yaml_agent_string()
function.
2-19
Other validation functions:
col_exists()
,
col_is_character()
,
col_is_date()
,
col_is_factor()
,
col_is_integer()
,
col_is_logical()
,
col_is_numeric()
,
col_is_posix()
,
col_schema_match()
,
col_vals_between()
,
col_vals_decreasing()
,
col_vals_equal()
,
col_vals_expr()
,
col_vals_gte()
,
col_vals_gt()
,
col_vals_in_set()
,
col_vals_increasing()
,
col_vals_lte()
,
col_vals_lt()
,
col_vals_make_set()
,
col_vals_make_subset()
,
col_vals_not_between()
,
col_vals_not_equal()
,
col_vals_not_in_set()
,
col_vals_not_null()
,
col_vals_null()
,
col_vals_regex()
,
rows_distinct()
# For all examples here, we'll use # a simple table with three numeric # columns (`a`, `b`, and `c`); this is # a very basic table but it'll be more # useful when explaining things later tbl <- dplyr::tibble( a = c(5, 2, 6), b = c(3, 4, 6), c = c(9, 8, 7) ) tbl#> # A tibble: 3 x 3 #> a b c #> <dbl> <dbl> <dbl> #> 1 5 3 9 #> 2 2 4 8 #> 3 6 6 7# A: Using an `agent` with validation # functions and then `interrogate()` # Validate a number of things on a # row-by-row basis using validation # functions of the `col_vals*` type # (all have the same number of test # units): (1) values in `a` are less # than `8`, (2) values in `c` are # greater than the adjacent values in # `a`, and (3) there aren't any NA # values in `b` agent <- create_agent(tbl = tbl) %>% conjointly( ~ col_vals_lt(., vars(a), value = 8), ~ col_vals_gt(., vars(c), value = vars(a)), ~ col_vals_not_null(., vars(b)) ) %>% interrogate() # Determine if this validation # had no failing test units (there # are 3 test units, one for each row) all_passed(agent)#> [1] TRUE# Calling `agent` in the console # prints the agent's report; but we # can get a `gt_tbl` object directly # with `get_agent_report(agent)` # What's going on? Think of there being # three parallel validations, each # producing a column of `TRUE` or `FALSE` # values (`pass` or `fail`) and line them # up side-by-side, any rows with any # `FALSE` values results in a conjoint # `fail` test unit # B: Using the validation function # directly on the data (no `agent`) # This way of using validation functions # acts as a data filter: data is passed # through but should `stop()` if there # is a single test unit failing; the # behavior of side effects can be # customized with the `actions` option tbl %>% conjointly( ~ col_vals_lt(., vars(a), value = 8), ~ col_vals_gt(., vars(c), value = vars(a)), ~ col_vals_not_null(., vars(b)) )#> # A tibble: 3 x 3 #> a b c #> <dbl> <dbl> <dbl> #> 1 5 3 9 #> 2 2 4 8 #> 3 6 6 7# C: Using the expectation function # With the `expect_*()` form, we would # typically perform one validation at a # time; this is primarily used in # testthat tests expect_conjointly( tbl, ~ col_vals_lt(., vars(a), value = 8), ~ col_vals_gt(., vars(c), value = vars(a)), ~ col_vals_not_null(., vars(b)) ) # D: Using the test function # With the `test_*()` form, we should # get a single logical value returned # to us tbl %>% test_conjointly( ~ col_vals_lt(., vars(a), value = 8), ~ col_vals_gt(., vars(c), value = vars(a)), ~ col_vals_not_null(., vars(b)) )#> [1] TRUE