Rename some functions to avoid period in names.

MLopez-Ibanez · Mar 7, 2024 · a4ecc08 · a4ecc08
1 parent c158eb1
commit a4ecc08
Show file tree

Hide file tree

Showing 31 changed files with 272 additions and 334 deletions.
diff --git a/NAMESPACE b/NAMESPACE
@@ -1,17 +1,27 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(param_quantile,ParamCat)
+S3method(param_quantile,ParamInt)
+S3method(param_quantile,ParamOrd)
+S3method(param_quantile,ParamReal)
 S3method(print,ParameterSpace)
-export(CommandArgsParser)
+S3method(sample_model,ParamCat)
+S3method(sample_model,ParamInt)
+S3method(sample_model,ParamOrd)
+S3method(sample_model,ParamReal)
+S3method(sample_unif,ParamCat)
+S3method(sample_unif,ParamInt)
+S3method(sample_unif,ParamOrd)
+S3method(sample_unif,ParamReal)
 export(ablation)
 export(ablation_cmdline)
 export(buildCommandLine)
 export(checkIraceScenario)
 export(checkParameters)
 export(checkScenario)
 export(check_output_target_runner)
-export(cmdline_usage)
-export(configurations.print)
-export(configurations.print.command)
+export(configurations_print)
+export(configurations_print_command)
 export(defaultScenario)
 export(getConfigurationById)
 export(getConfigurationByIteration)
@@ -21,10 +31,11 @@ export(get_random_seed)
 export(has_testing_data)
 export(irace)
 export(irace.cmdline)
-export(irace.license)
-export(irace.main)
-export(irace.version)
+export(irace_cmdline)
+export(irace_license)
+export(irace_main)
 export(irace_summarise)
+export(irace_version)
 export(multi_irace)
 export(param_cat)
 export(param_int)
@@ -44,11 +55,10 @@ export(read_logfile)
 export(read_pcs_file)
 export(removeConfigurationsMetaData)
 export(restore_random_seed)
-export(scenario.update.paths)
 export(scenario_update_paths)
 export(set_random_seed)
-export(target.evaluator.default)
-export(target.runner.default)
+export(target_evaluator_default)
+export(target_runner_default)
 export(testConfigurations)
 export(testing_fromfile)
 export(testing_fromlog)

diff --git a/NEWS.md b/NEWS.md
@@ -57,6 +57,8 @@
  * Expansion of `'~'` in Windows now follows the definition of `fs::path_expand()` rather than `base::path.expand()`.
 
  * irace is now more strict in enforcing runtime bounds given with `scenario$boundMax` and will stop with an error if the `target-runner` reports a runtime larger than the given bound.
+
+ * All functions that contained a period (`'.'`) in the name have been renamed to use `'_'` instead.
 
 
 ## New features and improvements

diff --git a/R/aaa.R b/R/aaa.R
@@ -17,10 +17,10 @@ update_package_version <- function()
     cat(file='./R/version.R', sep='',
 "#' A character string containing the version of `irace` including git SHA.
 #' @export
-irace.version <- '", realversion, "'\n")
+irace_version <- '", realversion, "'\n")
   }
   invisible()
 }
 update_package_version()
-# We define this tentatively to avoid: undefined exports: irace.version
-irace.version <- "unknown"
+# We define this tentatively to avoid: undefined exports: irace_version
+irace_version <- "unknown"
diff --git a/R/ablation.R b/R/ablation.R
@@ -33,7 +33,7 @@ cat_ablation_license <- function()
 # WARRANTY; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 #------------------------------------------------------------------------------
 '
-  cat(sub("__VERSION__", irace.version, ablation_license, fixed=TRUE))
+  cat(sub("__VERSION__", irace_version, ablation_license, fixed=TRUE))
 }
 
 #' Launch ablation with command-line options.
@@ -334,10 +334,10 @@ ablation <- function(iraceResults, src = 1L, target = NULL,
   irace.note ("Starting ablation from ", src, " to ", target, "\n# Seed: ", seed, "\n")
   cat("# Source configuration (row number is ID):\n")
   src_configuration <- iraceResults$allConfigurations[src, , drop = FALSE]
-  configurations.print(src_configuration)
+  configurations_print(src_configuration)
   cat("# Target configuration (row number is ID):\n")
   target_configuration <- iraceResults$allConfigurations[target, , drop = FALSE]
-  configurations.print(target_configuration)
+  configurations_print(target_configuration)
 
   # Select the parameters used for ablation
   if (is.null(ab_params)) {
@@ -401,7 +401,7 @@ ablation <- function(iraceResults, src = 1L, target = NULL,
     ## FIXME: These should be generated with respect to the logFile to make
     ## sure we don't have duplicate IDs.
     aconfigurations[[".ID."]] <- max(0L, all_configurations[[".ID."]]) + seq_nrow(aconfigurations)
-    configurations.print(aconfigurations, metadata = FALSE)
+    configurations_print(aconfigurations, metadata = FALSE)
     all_configurations <- rbind(all_configurations, aconfigurations)
 
     # Set variables for the racing procedure
@@ -431,7 +431,7 @@ ablation <- function(iraceResults, src = 1L, target = NULL,
                                 parameters = parameters,
                                 scenario = scenario,
                                 elitistNewInstances = 0L)
-    results <- merge.matrix (results, race.output$experiments)
+    results <- merge_matrix (results, race.output$experiments)
 
     # Save log
     ablog <- save_ablog(complete = FALSE)
@@ -478,7 +478,7 @@ ablation <- function(iraceResults, src = 1L, target = NULL,
   ## ever.
   best_configuration <- all_configurations[trajectory[best_id],,drop=FALSE]
   irace.note("Final best configuration:\n")
-  configurations.print(best_configuration)
+  configurations_print(best_configuration)
 
   # Check for duplicated results:
   report_duplicated_results(results, all_configurations)

diff --git a/R/argparser.R b/R/argparser.R
@@ -1,6 +1,4 @@
-#' R6 Class for parsing command-line arguments
-#' 
-#' @export
+# R6 Class for parsing command-line arguments
 CommandArgsParser <- R6::R6Class("CommandArgsParser", cloneable = FALSE, lock_class = TRUE, list(
   argv = NULL,
   argsdef = NULL,
@@ -83,17 +81,16 @@ CommandArgsParser <- R6::R6Class("CommandArgsParser", cloneable = FALSE, lock_cl
     }
     params
   },
-  cmdline_usage = function(){
-    irace::cmdline_usage(self$argsdef)
+  cmdline_usage = function() {
+    cmdline_usage(self$argsdef)
   })
 )
 
-#' `cmdline_usage()` prints the output of `--help`
-#'
-#' @param cmdline_args Definition of the command-line arguments.
-#' 
-#' @rdname CommandArgsParser
-#' @export
+# `cmdline_usage()` prints the output of `--help`
+#
+# @param cmdline_args Definition of the command-line arguments.
+# 
+# @export
 cmdline_usage <- function(cmdline_args)
 {
   for (i in seq_len(nrow(cmdline_args))) {

diff --git a/R/configurations.R b/R/configurations.R
@@ -53,3 +53,80 @@ which_satisfied <- function(configurations, condition)
   which(r)
 }
 
+#' removeConfigurationsMetaData
+#'
+#' Remove the columns with "metadata" of a data frame containing
+#' configurations. Currently, metadata corresponds to column names starting
+#' with a period.  This function should be used before printing the
+#' configurations to output only the values for the parameters of the
+#' configuration without metadata possibly useless to the user.
+#'   
+#' @template arg_configurations
+#' 
+#' @return The same data frame without "metadata".
+#'    
+#' @seealso 
+#'   [configurations_print_command()] to print the configurations as command lines.
+#'   [configurations_print()] to print the configurations as a data frame.
+#' 
+#' @author Manuel López-Ibáñez and Jérémie Dubois-Lacoste
+#' @export
+removeConfigurationsMetaData <- function(configurations)
+  configurations[, !startsWith(colnames(configurations), "."), drop = FALSE]
+
+#' Print configurations as a data frame
+#' 
+#' @template arg_configurations
+#' @param metadata A Boolean specifying whether to print the metadata or
+#' not. The metadata are data for the configurations (additionally to the
+#' value of each parameter) used by \pkg{irace}.
+#' 
+#' @return None.
+#'
+#' @seealso
+#'  [configurations_print_command()] to print the configurations as command-line strings.
+#' 
+#' @author Manuel López-Ibáñez and Jérémie Dubois-Lacoste
+#' @export
+configurations_print <- function(configurations, metadata = FALSE)
+{
+  if (!is.data.frame(configurations))
+    configurations <- as.data.frame(configurations, stringsAsFactors = FALSE)
+
+  rownames(configurations) <- configurations[[".ID."]]
+  if (!metadata)
+    configurations <- removeConfigurationsMetaData(configurations)
+
+  print.data.frame(configurations, digits = 15L)
+}
+
+#' Print configurations as command-line strings.
+#' 
+#' Prints configurations after converting them into a representation for the
+#' command-line.
+#' 
+#' @template arg_configurations
+#' @template arg_parameters
+#' 
+#' @return None.
+#'
+#' @seealso
+#'  [configurations_print()] to print the configurations as a data frame.
+#' 
+#' @author Manuel López-Ibáñez and Jérémie Dubois-Lacoste
+#' @export
+configurations_print_command <- function(configurations, parameters)
+{
+  if (nrow(configurations) <= 0) return(invisible())
+  ids <- as.numeric(configurations$.ID.)
+  configurations <- removeConfigurationsMetaData(configurations)
+  # Re-sort the columns
+  configurations <- configurations[, parameters$names, drop = FALSE]
+  # A better way to do this? We cannot use apply() because that coerces
+  # to a character matrix thus messing up numerical values.
+  len <- nchar(max(ids))
+  for (i in seq_nrow(configurations)) {
+    cat(sprintf("%-*d %s\n", len, ids[i],
+                buildCommandLine(configurations[i, , drop=FALSE], parameters$switches)))
+  }
+}
diff --git a/R/irace.R b/R/irace.R
@@ -21,10 +21,10 @@ recoverFromFile <- function(filename)
   # substitute() is needed to evaluate filename here.
   eval.parent(substitute({
     iraceResults <- read_logfile(filename)
-    if (iraceResults$irace.version != irace::irace.version)
+    if (iraceResults$irace_version != irace::irace_version)
       irace.error("Recovery file '", filename, "' was generated by a version of irace (",
-                  iraceResults$irace.version, ") different from this version of irace (",
-                  irace::irace.version, ").")
+                  iraceResults$irace_version, ") different from this version of irace (",
+                  irace::irace_version, ").")
     # .Random.seed and .irace are special
     for (name in setdiff(names(iraceResults$state), c(".Random.seed", ".irace")))
       assign(name, iraceResults$state[[name]])
@@ -224,7 +224,7 @@ computeNbConfigurations <- function(currentBudget, indexIteration,
   # budget that we save (that is, number of entries that are not NA).
   savedBudget <- nElites *  nOldInstances
   n <- max (mu + blockSize * eachTest * min(5L, indexIteration),
-            round.to.next.multiple(nOldInstances + newInstances, blockSize * eachTest))
+            round_to_next_multiple(nOldInstances + newInstances, blockSize * eachTest))
   min (floor ((currentBudget + savedBudget) / n), maxConfigurations)
 }
 
@@ -604,7 +604,7 @@ allConfigurationsInit <- function(scenario, parameters)
 #' tuned_confs <- irace(scenario = scenario, parameters = parameters)
 #' 
 #' ## We can print the best configurations found by irace as follows:
-#' configurations.print(tuned_confs)
+#' configurations_print(tuned_confs)
 #' 
 #' ## We can evaluate the quality of the best configuration found by
 #' ## irace versus the default configuration of the SANN algorithm on
@@ -636,8 +636,8 @@ allConfigurationsInit <- function(scenario, parameters)
 #' }
 #' @seealso
 #'  \describe{
-#'  \item{[irace.main()]}{a higher-level interface to [irace()].}
-#'  \item{[irace.cmdline()]}{a command-line interface to [irace()].}
+#'  \item{[irace_main()]}{a higher-level interface to [irace()].}
+#'  \item{[irace_cmdline()]}{a command-line interface to [irace()].}
 #'  \item{[readScenario()]}{for reading a configuration scenario from a file.}
 #'  \item{[readParameters()]}{read the target algorithm parameters from a file.}
 #'  \item{[defaultScenario()]}{returns the default scenario settings of \pkg{irace}.}
@@ -681,10 +681,10 @@ irace_common <- function(scenario, parameters, simple, output.width = 9999L)
     order_str <- test.type.order.str(scenario$testType)
     cat("# Best configurations (first number is the configuration ID;",
         " listed from best to worst according to the ", order_str, "):\n", sep = "")
-    configurations.print(eliteConfigurations)
+    configurations_print(eliteConfigurations)
 
     cat("# Best configurations as commandlines (first number is the configuration ID;", " listed from best to worst according to the ", order_str, "):\n", sep = "")
-    configurations.print.command (eliteConfigurations, parameters)
+    configurations_print_command (eliteConfigurations, parameters)
   }
 
   if (scenario$postselection > 0) 
@@ -753,7 +753,7 @@ irace_run <- function(scenario, parameters)
     # To save the logs
     iraceResults <- list(
       scenario = scenario,
-      irace.version = irace.version,
+      irace_version = irace_version,
       parameters = parameters,
       iterationElites = c(),
       allElites = list(),
@@ -844,7 +844,7 @@ irace_run <- function(scenario, parameters)
                                             # These experiments are assigned iteration 0
                                             cbind(iteration=0L, output$experimentLog)) 
 
-        iraceResults$experiments <- merge.matrix (iraceResults$experiments,
+        iraceResults$experiments <- merge_matrix (iraceResults$experiments,
                                                   output$experiments)
         rownames(iraceResults$experiments) <- seq_nrow(iraceResults$experiments)
         rejectedIDs <- c(rejectedIDs, output$rejectedIDs)
@@ -1200,7 +1200,7 @@ irace_run <- function(scenario, parameters)
     if (debugLevel >= 2) {
       irace.note("Configurations for the race n ", indexIteration,
                  " (elite configurations listed first, then new configurations):\n")
-      configurations.print(raceConfigurations, metadata = TRUE)
+      configurations_print(raceConfigurations, metadata = TRUE)
     }
 
     # Get data from previous elite tests 
@@ -1239,7 +1239,7 @@ irace_run <- function(scenario, parameters)
                                               raceResults$experimentLog))
 
     # Merge new results.
-    iraceResults$experiments <- merge.matrix (iraceResults$experiments,
+    iraceResults$experiments <- merge_matrix (iraceResults$experiments,
                                               raceResults$experiments)
 
     if (length(raceResults$rejectedIDs) > 0L) {
@@ -1263,7 +1263,7 @@ irace_run <- function(scenario, parameters)
       irace.note("Results for the race of iteration ", indexIteration,
                  " (from best to worst, according to the ",
                  test.type.order.str(scenario$testType), "):\n")
-      configurations.print (raceResults$configurations, metadata = TRUE)
+      configurations_print(raceResults$configurations, metadata = TRUE)
     }
 
     if (debugLevel >= 1) irace.note("Extracting elites\n")
@@ -1275,7 +1275,7 @@ irace_run <- function(scenario, parameters)
     irace.note("Elite configurations (first number is the configuration ID;",
                " listed from best to worst according to the ",
                test.type.order.str(scenario$testType), "):\n")
-    if (!quiet) configurations.print(eliteConfigurations, metadata = debugLevel >= 1L)
+    if (!quiet) configurations_print(eliteConfigurations, metadata = debugLevel >= 1L)
     iraceResults$iterationElites[indexIteration] <- eliteConfigurations[[".ID."]][1L]
     iraceResults$allElites[[indexIteration]] <- eliteConfigurations[[".ID."]]
 
@@ -1290,7 +1290,7 @@ irace_run <- function(scenario, parameters)
       irace.note("End of iteration ", indexIteration, "\n")
       if (debugLevel >= 3) {
         irace.note("All configurations (sampling order):\n")
-        configurations.print(allConfigurations, metadata = TRUE)
+        configurations_print(allConfigurations, metadata = TRUE)
         irace.note("Memory used in irace():\n")
         irace.print.memUsed()
       }

diff --git a/R/irace_summarise.R b/R/irace_summarise.R
@@ -29,7 +29,7 @@ irace_summarise <- function(iraceResults)
   }
 
   list(
-    version = iraceResults$irace.version,
+    version = iraceResults$irace_version,
     n_iterations = niterations,
     n_configurations = nrow(iraceResults$allConfigurations),
     n_initial_configurations = if (is.null(iraceResults$scenario$initConfigurations)) 0L else nrow(iraceResults$scenario$initConfigurations),