adding some documentation

Author: edwindj

R/detect_boundary.R

@@ -58,9 +58,11 @@ detect_boundary_num <- function(x, eps = 1e-8, ...){
 }
 
 
-#' Detect viable domains for categorical variables
+#' Detect domains for categorical variables
 #' 
-#' Detect viable 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_boundary_cat()` finds the categories that are allowed by the rule set.
 #' @example ./examples/detect_boundary.R
 #' @param x [validate::validator()] object with rules
 #' @param as_df return result as data.frame (before 0.4.5)

R/detect_contradicting_if_rules.R

@@ -1,6 +1,10 @@
-#' Detect infeasible if clauses
+#' Detect infeasible if rules
 #' 
-#' Detect if clauses that contradict each other. This is useful to detect if clauses that are not satistifable.
+#' Detect whether conditions in if-rules may generate contradictions. Strictly
+#' speaking these rules do not make the rule set infeasible but rather make
+#' the if-condition unsatisfiable. So semantically speaking these rules are 
+#' contradicting, because the writer of the rule set did not have the intention 
+#' to make the condition forbidden. See examples for more details.
 #' 
 #' @param x A validator object.
 #' @param ... Additional arguments passed to `detect_if_clauses`.

R/detect_fixed_variables.R

@@ -1,6 +1,6 @@
 #' Detect fixed variables
 #' 
-#' Detects variables that have a fixed value in the rule set. 
+#' 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.
 #' @example ./examples/detect_fixed_variables.R
 #' @seealso [simplify_fixed_variables()]

R/feasible.R

@@ -3,6 +3,7 @@
 #' An infeasible rule set cannot be satisfied by any data because of internal 
 #' contradictions. 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()`.
 #'  
 #' @example ./examples/feasible.R
 #' @param x `validator` object with validation rules.
@@ -29,6 +30,11 @@ is_feasible <- function(x, ...){
 #' Make an infeasible system feasible, by removing the minimum (weighted) number of rules, such that the remaining
 #' rules are not conflicting.
 #' This function uses [detect_infeasible_rules()] for determining the rules to be removed.
+#' Note that this may not result in your desired system, because some rules may be more important. 
+#' This can be mediated by supplying weights for the rules. Default weight is 1.
+#' 
+#' Also `make_feasible()` does not check for contradictions in `if` rules, so it is wise to also check
+#' `detect_contradicting_if_rules()` after making the system feasible.
 #' @export
 #' @param x [validate::validator()] object with the validation rules.
 #' @param ... passed to [detect_infeasible_rules()]
@@ -71,7 +77,8 @@ detect_infeasible_rules <- function(x, weight = numeric(), ...){
   mr <- fix_cat_domain(mr)
 
   nms <- mr |> sapply(\(x) x$rule)
-  w_inf <- nms[grepl("^\\.domain.", nms)] |> sapply(\(x) Inf)
+  # meaning: all rules that start with a dot are "hard rules"
+  w_inf <- nms[grepl("^\\.", nms)] |> sapply(\(x) Inf)
   weight <- c(weight, w_inf)
 
   is_equality <- sapply(mr, function(m){

R/mip_lpsolve.R

@@ -6,6 +6,7 @@
 #' @param  rules mip rules
 #' @param objective function
 #' @param eps accuracy for equality/inequality
+#' @keywords internal
 translate_mip_lp <- function( rules
                             , objective=NULL
                             , eps = 1e-3

R/redundancy.R

@@ -1,6 +1,8 @@
-#' Detect redundant rules without removing.
+#' Detect redundant rules
 #' 
-#' Detect redundancies in a rule set. 
+#' 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
@@ -28,7 +30,7 @@ detect_redundancy <- function(x, ...){
 
 #' Remove redundant rules
 #' 
-#' Simplify a rule set by removing redundant rules
+#' Simplify a rule set by removing redundant rules, i.e. rules that are implied by other rules.
 #' @export
 #' @example ./examples/redundancy.R
 #' @param x [validate::validator()] object with validation rules.

R/simplify_rules.R

@@ -9,6 +9,9 @@
 #'  \item [remove_redundancy()]: remove redundant rules.
 #' }
 #' For more control, these methods can be called separately.
+#' 
+#' Note that it is wise to call [detect_contradicting_if_rules()]
+#' before calling this function.
 #' @example ./examples/simplify_rules.R
 #' @export
 #' @param .x [validate::validator()] object with the rules to be simplified.

R/soft-rule.R

@@ -41,6 +41,7 @@ eps_min <- suffix("_eps_min")
 #' @param values named list of values.
 #' @param weights named numeric of equal length as values.
 #' @param ... not used
+#' @keywords internal
 expect_values <- function(values, weights, ...){
   if (missing(weights)){
     weights <- rep(1, length(values))

R/substitute_values.R

@@ -4,7 +4,8 @@ NULL
 
 #' substitute a value in a rule set
 #' 
-#' Substitute values into expression, thereby simplifying the rule set.
+#' Substitute values / fill in a value for one ore more variables, thereby 
+#' simplifying the rule set.
 #' Rules that evaluate to TRUE because of the substitution are removed.
 #' @example ./examples/substitute_values.R
 #' @param .x `validator` object with rules

R/validatetools-package.R

@@ -13,6 +13,8 @@
 #' 
 #' \itemize{
 #'   \item [is_infeasible()] checks a rule set for feasibility. An infeasible system must be corrected to be useful.
+#'   \item [detect_infeasible_rules()] detects which rules cause infeasibility.
+#'   \item [detect_contradicting_if_rules()] detects which `if` rules are conflicting.
 #'   \item [detect_boundary_num()] shows for each numerical variable the allowed range of values.
 #'   \item [detect_boundary_cat()] shows for each categorical variable the allowed range of values.
 #'   \item [detect_fixed_variables()] shows variables whose value is fixated by the rule set.