Restrictions renamed to exclusions and function updated to exclude. T…

…his is more intuitive and in line with what the argument does.

R/design.R

@@ -16,8 +16,8 @@
 #' default is set and argument must be specified. Optimizing for multiple
 #' criteria is not yet implemented and will result in an error.
 #' @param algorithm A character string giving the optimization algorithm to use.
-#' No default is set and the argument must be specified to be one of 'federov'
-#' or 'random'. The 'rsc' algorithm is not implemented yet.
+#' No default is set and the argument must be specified to be one of 'rsc',
+#' 'federov' or 'random'.
 #' @param draws The type of draws to use with Bayesian priors. No default is set
 #'  and must be specified even if you are not creating a Bayesian design. Can be
 #' one of "pseudo-random", "mlhs", "standard-halton", "scrambled-halton",
@@ -28,12 +28,12 @@
 #' @param candidate_set A matrix or data frame in the "wide" format containing
 #' all permitted combinations of attributes. The default is NULL. If no
 #' candidate set is provided, then the full factorial subject to specified
-#' restrictions will be used.
-#' @param restrictions A list of restrictions. Often this list will be pulled
-#' directly from the list of options or it is a modified list of restrictions
-#' following calls to _dummy or _effects coding.
-#' @param level_balance A placeholder boolean for whether to impose level
-#' balance in the design
+#' exclusions will be used.
+#' @param exclusions A list of exclusions Often this list will be pulled
+#' directly from the list of options or it is a modified list of exclusions
+#' @param level_balance A boolean equal to `TRUE` if attribute level balance
+#' should be imposed. This only matters if the estimation algorithm is specified
+#' as `federov` or `random`.
 #' @param control A list of control options
 #'
 #' @return An object of class 'spdesign'
@@ -51,7 +51,7 @@ generate_design <- function(utility,
                             R = 100,
                             dudx = NULL,
                             candidate_set = NULL,
-                            restrictions = NULL,
+                            exclusions = NULL,
                             level_balance = FALSE,
                             control = list(
                               cores = 1,
@@ -114,7 +114,7 @@ generate_design <- function(utility,
   }
 
   ## Candidate set ----
-  cli_h2("Checking the candidate set and applying restrictions")
+  cli_h2("Checking the candidate set and applying exclusions")
 
   # If no candidate set is supplied generate full factorial if not run simple
   # checks
@@ -147,11 +147,11 @@ generate_design <- function(utility,
     }
   }
 
-  # Apply the restrictions to the candidate set
-  candidate_set <- apply_restrictions(candidate_set, restrictions)
+  # Apply the exclusions to the candidate set
+  candidate_set <- exclude(candidate_set, exclusions)
   candidate_set <- as.matrix(candidate_set)
 
-  cli_alert_success("All restrictions successfully applied")
+  cli_alert_success("All exclusions successfully applied")
 
   # Prepare the list of priors ----
   cli_h2("Preparing the list of priors")

R/restrictions.R → R/exclusions-and-conditions.R

@@ -1,18 +1,18 @@
-#' Apply restrictions to the candidate set
+#' Exclude rows from the candidate set
 #'
-#' The function takes the list of restrictions and transforms them into an
-#' expression that is then parsed and evaluated to apply the restrictions
+#' The function takes the list of exclusions and transforms them into an
+#' expression that is then parsed and evaluated to apply the exclusions
 #' to the supplied candidate set using standard subsetting routines.
 #'
 #' @inheritParams generate_design
 #'
 #' @return A restricted candidate set
-apply_restrictions <- function(candidate_set, restrictions) {
+exclude <- function(candidate_set, exclusions) {
   attribute_names <- names(candidate_set)
 
-  # Reformat the restrictions
-  restrictions <- lapply(seq_along(restrictions), function(i) {
-    restriction <- restrictions[[i]]
+  # Reformat the exclusions
+  exclusions <- lapply(seq_along(exclusions), function(i) {
+    restriction <- exclusions[[i]]
 
     for (j in seq_along(attribute_names)) {
       restriction <- str_replace_all(
@@ -26,9 +26,9 @@ apply_restrictions <- function(candidate_set, restrictions) {
     paste0("candidate_set[!(",  restriction, "), , drop = FALSE]")
   })
 
-  # Apply the restrictions
-  for (i in seq_along(restrictions)) {
-    candidate_set <- eval(parse(text = restrictions[[i]]))
+  # Apply the exclusions
+  for (i in seq_along(exclusions)) {
+    candidate_set <- eval(parse(text = exclusions[[i]]))
   }
 
   # Return

examples/mnl-design-with-restrictions.R

@@ -14,7 +14,7 @@ utility <- list(
 design <- generate_design(utility, rows = 20,
                           model = "mnl", efficiency_criteria = "d-error",
                           algorithm = "federov", draws = "scrambled-sobol",
-                          restrictions = list(
+                          exclusions = list(
                             "alt1_x1 == 2 & alt1_x2 == 0 & alt1_x3 == 0",
                             "alt2_x2 == 1 & alt2_x3 == 1"
                           ))

tests/testthat/test-apply-restrictions.R

@@ -1,14 +1,14 @@
-context("That restrictions are correctly applied to the candidate set")
+context("That exclusions are correctly applied to the candidate set")
 
 candidate_set <- full_factorial(list(x1 = c(0, 1), x2 = c(0, 1)))
 
 test_that("Restriction pattern one", {
-  restrictions <- list(
+  exclusions <- list(
     "x1 == 1 & x2 == 1"
   )
 
   expect_equal(
-    apply_restrictions(candidate_set, restrictions),
+    exclude(candidate_set, exclusions),
     structure(
       list(
         x1 = c(0, 1, 0),
@@ -27,13 +27,13 @@ test_that("Restriction pattern one", {
 
 
 test_that("Restriction pattern two", {
-  restrictions <- list(
+  exclusions <- list(
     "x1 == 1 & x2 == 1",
     "x1 == 0"
   )
 
   expect_equal(
-    apply_restrictions(candidate_set, restrictions),
+    exclude(candidate_set, exclusions),
     structure(
       list(
         x1 = 1,