updating documentation

Author: edwindj

R/categorical.R

@@ -88,9 +88,9 @@ cat_var_name <- function(x, infix=INFIX_CAT_NAME){
   gsub(suffix,"",names(x$a))
 }
 
-#' Check if rules are categorical
+#' Check whether rules are categorical
 #'
-#' Check if rules are categorical
+#' Check whether rules are categorical
 #' @export
 #' @param x validator object
 #' @param ... not used

R/conditional.R

@@ -23,9 +23,9 @@ is_condition_ <- function(expr, or=TRUE, top=TRUE, ...){
   )
 }
 
-#' Check if rules are conditional rules
+#' Check whether rules are conditional rules
 #'
-#' Check if rules are conditional rules
+#' Check whether rules are conditional rules
 #' @export
 #' @param rules validator object containing validation rules
 #' @param ... not used

R/detect_boundary.R

@@ -1,6 +1,7 @@
-#' Detect the range for numerical variables
+#' Detect the allowed range for numerical variables
 #' 
-#' Detect for each numerical variable in a validation rule set, what its maximum and minimum values are.
+#' Detect for each numerical variable in a validation rule set, what its maximum and minimum allowed values are.
+#' The rule set may constrain numerical variables to a subset of their values.
 #' This allows for manual rule set checking: does rule set `x` overly constrain numerical values?
 #' 
 #' This procedure only finds minimum and maximum values, but misses gaps.
@@ -60,8 +61,8 @@ detect_boundary_num <- function(x, eps = 1e-8, ...){
 
 #' Detect domains for categorical variables
 #' 
-#' Detect viable domains for categorical variables.
-#' A rule set may constrain a categorical variable to a subset of its values.
+#' Detect the allowed values for categorical variables: the rule set may constrain
+#' the categorical variables to a subset of their values.
 #' `detect_boundary_cat()` finds the categories that are allowed by the rule set.
 #' @example ./examples/detect_boundary.R
 #' @param x [validate::validator()] object with rules

R/detect_contradicting_if_rules.R

@@ -1,16 +1,16 @@
 #' Detect contradictory if-rules
 #' 
-#' Detect whether conditions in if-rules may generate contradictions. Strictly
+#' Detect whether conditions in conditional if-rules may generate contradictions. Strictly
 #' speaking these rules do not make the rule set infeasible but rather make
 #' the if-condition unsatisfiable. 
 #' Semantically speaking these rules are 
 #' contradicting, because the writer of the rule set did not have the intention 
 #' to make the condition forbidden.
 #' 
-#' In general it detects cases where:
+#' In general it detects (variations on) cases where:
 #' 
-#' - `if (A) B` and `if (A) !B`, which probably is not intended, but strictly speaking equals `!A`.
-#' - `if (A) B` and `if (B) !A`, which probably is not intended but strictly speaking equals `!A`. 
+#' - `if (A) B` and `if (A) !B`, which probably is not intended, but logically equals `!A`.
+#' - `if (A) B` and `if (B) !A`, which probably is not intended but logically equals `!A`. 
 #' 
 #' See examples for more details.
 #' 
@@ -83,7 +83,7 @@ check_condition <- function(cond_expr, x){
   for (i in seq_along(cond)){
     cd <- cond[-i]
     v <- x + do.call(validate::validator, cd)
-    if (is_feasible(v)){
+    if (is_feasible(v, verbose=FALSE)){
       next
     }
     v1 <- is_contradicted_by(v, names(cd), verbose = FALSE)

R/detect_fixed_variables.R

@@ -2,6 +2,7 @@
 #' 
 #' Detects variables that are constrained by the rule set to have one fixed value.
 #' To simplify a rule set, these variables can be substituted with their value.
+#' See examples.
 #' @example ./examples/detect_fixed_variables.R
 #' @seealso [simplify_fixed_variables()]
 #' @param x [validate::validator()] object with the validation rules.

R/feasible.R

@@ -1,23 +1,47 @@
 #' Check the feasibility of a rule set
 #' 
 #' An infeasible rule set cannot be satisfied by any data because of internal 
-#' contradictions. This function checks whether the record-wise linear,
+#' contradictions: the combination of the rules make it inconsistent.
+#' This function checks whether the record-wise linear,
 #' categorical and conditional rules in a rule set are consistent.
-#' Note that is it always wise to also check `detect_contradicting_if_rules()`.
+#' Note that is it wise to also check `detect_contradicting_if_rules()`: 
+#' conditional If-rules
+#' may not be strictly inconsistent, but can be semantically inconsistent.
 #'  
 #' @example ./examples/feasible.R
 #' @param x `validator` object with validation rules.
 #' @param ... not used
+#' @param verbose if `TRUE` print information to the console
 #' @family feasibility
 #' @return TRUE or FALSE
 #' @export
-is_infeasible <- function(x, ...){
+is_infeasible <- function(x, ..., verbose = interactive()){
   lp <- to_lp(x) # TODO find out how to treat eps for linear inequalities...
   lpSolveAPI::lp.control(lp, presolve="rows", break.at.first = TRUE)
   res <- solve(lp)
   # any of the following means that there is a solution found by lpSolveAPI:
   # TODO generate errors if the lpSolveAPI gives other return values...
-  !(res %in% c(0,1,4,12))
+  i <- !(res %in% c(0,1,4,12))
+  
+  if (isTRUE(verbose)){
+    if (i){
+      message(
+        "The rule set is infeasible:\n",
+        "  use `detect_infeasible_rules()` and `is_contradicted_by` to find out\n",
+        "  which rules are causing infeasibility.",
+        "  or `make_feasible()` to make the rule set feasible."
+      )
+    } else {
+      message(
+        "The rule set is feasible,\n",
+        "  but may contain contradictions in conditional if-rules.\n",
+        "  use `detect_contradicting_if_rules()` to find out whether there are \n",
+        "  contradictions in the if-clauses."
+      )
+    }
+  }
+  
+  i
 }
 
 is_feasible <- function(x, ...){
@@ -70,7 +94,7 @@ make_feasible <- function(x, ..., verbose = interactive()){
 #' @return `character` with the names of the rules that are causing infeasibility.
 detect_infeasible_rules <- function(x, weight = numeric(), ..., verbose = interactive()){
   # browser()
-  if (!is_infeasible(x)){
+  if (!is_infeasible(x, verbose=FALSE)){
     return(character())
   }
   # browser()

R/implied_by.R

@@ -1,6 +1,8 @@
-#' Find which rule(s) make rule_name redundant
+#' Find which rule(s) imply a rule
 #' 
 #' Find out which rules are causing rule_name(s) to be redundant.
+#' A rule set can contain rules that are implied by the other rules, so it is
+#' superfluous, see examples.
 #' @example ./examples/redundancy.R
 #' @export
 #' @param x [validate::validator()] object with rule

R/redundancy.R

@@ -3,7 +3,6 @@
 #' Detect redundancies in a rule set, but do not remove the rules.
 #' A rule in a ruleset can be redundant if it is implied by another rule
 #' or by a combination of rules. See the examples for more information.
-#' 
 #' @note For removal of duplicate rules, simplify
 #' @example ./examples/redundancy.R
 #' @param x [validate::validator()] object with the validation rules.
@@ -91,7 +90,7 @@ is_redundant <- function(dnf_set, i, ...){
   #     print(get(n))
   #   }
   # }
-  is_infeasible(test_rules)
+  is_infeasible(test_rules, verbose = FALSE)
 }
 
 # x <- validator( rule1 = x > 1

R/simplify_conditional.R

@@ -1,9 +1,7 @@
 #' Simplify conditional statements
 #' 
-#' Conditional rules may be constrained by the others rules in a validation rule set.
+#' Conditional rules (if-rules) may be constrained by the others rules in a validation rule set.
 #' This procedure tries to simplify conditional statements.
-#' 
-#' 
 #' @references TODO non-constraining, non-relaxing
 #' @example ./examples/simplify_conditional.R
 #' @export
@@ -31,7 +29,7 @@ simplify_non_relaxing <- function(cond_expr, vals){
   clauses <- as_dnf(cond_expr)
   clauses[] <- lapply(clauses, function(clause){
     test_rules <- do.call(validate::validator, c(vals, clause))
-    if (is_infeasible(test_rules)){
+    if (is_infeasible(test_rules, verbose=FALSE)){
       return(NULL)
     }
     clause
@@ -45,7 +43,7 @@ simplify_non_constraining <- function(cond_expr, vals){
   for (clause in clauses){
     clause_neg <- invert_or_negate(clause)
     test_rules <- do.call(validate::validator, c(vals, clause_neg))
-    if (is_infeasible(test_rules)){
+    if (is_infeasible(test_rules, verbose=FALSE)){
       return(clause)
     }
   }

R/utils.R

@@ -3,7 +3,7 @@ check_validator <- function(x, copy = TRUE, check_infeasible = TRUE){
   if (!inherits(x, "validator")){
     stop("This method needs a 'validator' object, but was given a '", class(x), "'.",call. = FALSE)
   }
-  if (isTRUE(check_infeasible) && is_infeasible(x)){
+  if (isTRUE(check_infeasible) && is_infeasible(x, verbose=FALSE)){
     stop("This rule set is infeasible. Please fix and repair the rule set with `make_feasible` before continuing.", call. = FALSE)
   }
   invisible(x)