Define a research rule

Validates one rule and returns it as a plain list. A rule names the research actions it governs, optional when conditions that decide whether it applies, and one requirement. Conditions and requirements have the form list(type = <predicate id>, ...arguments).

Usage

bg_rule(
  id,
  on,
  require,
  message,
  when = NULL,
  severity = NULL,
  explanation = NULL,
  suggestion = NULL,
  interpretation = NULL,
  references = NULL
)

Arguments

id

Rule id, unique within its ruleset. Lowercase letters, digits, _, and -. vocabulary is reserved.

on

Research actions the rule governs: create, revise, evidence, compare, review, accept, reject, note, close, or reopen.

require

One requirement, as a condition list.

message

One sentence stating the unmet requirement.

when

Optional list of conditions. The rule applies only if all of them are true.

severity

blocking (the default when NULL) or advisory. Enforce holds an action only for blocking findings.

explanation, suggestion, interpretation

Optional guidance strings.

references

Optional source strings. They are never fetched.

Value

A validated rule (named list).

Details

Built-in predicates are goal_kind (values), actor_type (values), candidate_values and require_values (path, values), forbid_values (path, values), require_evidence (check, optional provenance), require_utility_evidence (utility, optional provenance), and require_review (check). Paths are relative to the candidate's components, for example c("P", "covariates"). Custom predicates use a dotted id; see bg_register_rule_predicate().

A predicate that is missing, has a different version than the pinned one, raises an error, or returns anything other than TRUE or FALSE produces a finding, whether in when or in require. A failure never switches a rule off.

Examples

bg_rule(
  id = "review-ppc",
  on = "accept",
  when = list(list(type = "goal_kind", values = "observable_prediction")),
  require = list(type = "require_review", check = "ppc"),
  message = "Review the predictive check before accepting."
)
#> $id
#> [1] "review-ppc"
#> 
#> $message
#> [1] "Review the predictive check before accepting."
#> 
#> $on
#> $on[[1]]
#> [1] "accept"
#> 
#> 
#> $require
#> $require$check
#> [1] "ppc"
#> 
#> $require$type
#> [1] "require_review"
#> 
#> 
#> $when
#> $when[[1]]
#> $when[[1]]$type
#> [1] "goal_kind"
#> 
#> $when[[1]]$values
#> $when[[1]]$values[[1]]
#> [1] "observable_prediction"
#> 
#> 
#> 
#>