R/action_levels.R
action_levels.RdThe action_levels() function works with the actions argument that is
present in the create_agent() function and in every validation step
function. With it, we can provide threshold fail levels for any combination
of warn, stop, or notify states.
We can react to any entrance of a state by supplying corresponding functions
to the fns argument. They will undergo evaluation at the time when the
matching state is entered. If provided to create_agent() then the policies
will be applied to every validation step, acting as a default for the
validation as a whole.
Calls of action_levels() could also be applied directly to any validation
step and this will act as an override if set also in create_agent(). Usage
of action_levels() is required to have any useful side effects (i.e.,
warnings, throwing errors) in the case of validation functions operating
directly on data (e.g., mtcars %>% col_vals_lt("mpg", 35)). There are two
helper functions that are convenient when using validation functions directly
on data (the agent-less workflow): warn_on_fail() and stop_on_fail().
These helpers either warn or stop (default failure threshold for each is set
to 1), and, they do so with informative warning or error messages. The
stop_on_fail() helper is applied by default when using validation functions
directly on data (more information on this is provided in Details).
action_levels(warn_at = NULL, stop_at = NULL, notify_at = NULL, fns = NULL) warn_on_fail(warn_at = 1) stop_on_fail(stop_at = 1)
| warn_at, stop_at, notify_at | The threshold number or fraction of
test units that can provide a fail result before entering the
|
|---|---|
| fns | A named list of functions that is to be paired with the
appropriate failure states. The syntax for this list involves using failure
state names from the set of |
The output of the action_levels() call in actions will be interpreted
slightly differently if using an agent or using validation functions
directly on a data table. For convenience, when working directly on data, any
values supplied to warn_at or stop_at will be automatically given a stock
warning() or stop() function. For example using
small_table %>% col_is_integer("date") will provide a detailed stop message
by default, indicating the reason for the failure. If you were to supply the
fns for stop or warn manually then the stock functions would be
overridden. Furthermore, if actions is NULL in this workflow (the default),
pointblank will use a stop_at value of 1 (providing a detailed,
context-specific error message if there are any fail units). We can
absolutely suppress this automatic stopping behavior by at each validation
step by setting active = FALSE. In this interactive data case, there is no
stock function given for notify_at. The notify failure state is less
commonly used in this workflow as it is in the agent-based one.
When using an agent, we often opt to not use any functions in fns as the
warn, stop, and notify failure states will be reported on when using
create_agent_report() (and, usually that's sufficient). Instead, using the
end_fns argument is a better choice since that scheme provides useful data
on the entire interrogation, allowing for finer control on side effects and
reducing potential for duplicating any side effects.
1-5
Other Planning and Prep:
create_agent(),
create_informant(),
db_tbl(),
file_tbl(),
scan_data(),
validate_rmd()
# 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.5 ) # Use the included `small_table` dataset # for the validation example small_table#> # A tibble: 13 x 8 #> date_time date a b c d e f #> <dttm> <date> <int> <chr> <dbl> <dbl> <lgl> <chr> #> 1 2016-01-04 11:00:00 2016-01-04 2 1-bcd-345 3 3423. TRUE high #> 2 2016-01-04 00:32:00 2016-01-04 3 5-egh-163 8 10000. TRUE low #> 3 2016-01-05 13:32:00 2016-01-05 6 8-kdg-938 3 2343. TRUE high #> 4 2016-01-06 17:23:00 2016-01-06 2 5-jdo-903 NA 3892. FALSE mid #> 5 2016-01-09 12:36:00 2016-01-09 8 3-ldm-038 7 284. TRUE low #> 6 2016-01-11 06:15:00 2016-01-11 4 2-dhe-923 4 3291. TRUE mid #> 7 2016-01-15 18:46:00 2016-01-15 7 1-knw-093 3 843. TRUE high #> 8 2016-01-17 11:27:00 2016-01-17 4 5-boe-639 2 1036. FALSE low #> 9 2016-01-20 04:30:00 2016-01-20 3 5-bce-642 9 838. FALSE high #> 10 2016-01-20 04:30:00 2016-01-20 3 5-bce-642 9 838. FALSE high #> 11 2016-01-26 20:07:00 2016-01-26 4 2-dmx-010 7 834. TRUE low #> 12 2016-01-28 02:51:00 2016-01-28 2 7-dmx-010 8 108. FALSE low #> 13 2016-01-30 11:23:00 2016-01-30 1 3-dka-303 NA 2230. TRUE high# Validate that values in column # `a` are always greater than `2` and # apply the list of action levels (`al`) agent <- create_agent(tbl = small_table) %>% col_vals_gt(vars(a), 2, actions = al) %>% interrogate() # The report from the agent will show # that the `warn` state has been entered # for the first and only validation step; # Let's look at the *tibble* version of the # agent report (accessible through the use # of the `get_agent_report()` function) agent %>% get_agent_report(display_table = FALSE)#> # A tibble: 1 x 14 #> i type columns values precon active eval units n_pass f_pass W S #> <int> <chr> <chr> <chr> <chr> <lgl> <chr> <dbl> <dbl> <dbl> <lgl> <lgl> #> 1 1 col_… a 2 NA TRUE OK 13 9 0.692 TRUE FALSE #> # … with 2 more variables: N <lgl>, extract <int># In the context of using validation # functions directly on data, their # use is commonly to trigger warnings # and raise errors. The following *will* # provide a warning (but that's # suppressed here) and the `small_table` # data will be returned suppressWarnings( small_table %>% col_vals_gt(vars(a), 2, actions = al) )#> # A tibble: 13 x 8 #> date_time date a b c d e f #> <dttm> <date> <int> <chr> <dbl> <dbl> <lgl> <chr> #> 1 2016-01-04 11:00:00 2016-01-04 2 1-bcd-345 3 3423. TRUE high #> 2 2016-01-04 00:32:00 2016-01-04 3 5-egh-163 8 10000. TRUE low #> 3 2016-01-05 13:32:00 2016-01-05 6 8-kdg-938 3 2343. TRUE high #> 4 2016-01-06 17:23:00 2016-01-06 2 5-jdo-903 NA 3892. FALSE mid #> 5 2016-01-09 12:36:00 2016-01-09 8 3-ldm-038 7 284. TRUE low #> 6 2016-01-11 06:15:00 2016-01-11 4 2-dhe-923 4 3291. TRUE mid #> 7 2016-01-15 18:46:00 2016-01-15 7 1-knw-093 3 843. TRUE high #> 8 2016-01-17 11:27:00 2016-01-17 4 5-boe-639 2 1036. FALSE low #> 9 2016-01-20 04:30:00 2016-01-20 3 5-bce-642 9 838. FALSE high #> 10 2016-01-20 04:30:00 2016-01-20 3 5-bce-642 9 838. FALSE high #> 11 2016-01-26 20:07:00 2016-01-26 4 2-dmx-010 7 834. TRUE low #> 12 2016-01-28 02:51:00 2016-01-28 2 7-dmx-010 8 108. FALSE low #> 13 2016-01-30 11:23:00 2016-01-30 1 3-dka-303 NA 2230. TRUE high