Add options to directly supply text for various variables

NEWS.md

@@ -57,6 +57,11 @@
    `repairConfiguration` function (see `defaultScenario()`) only needs two
    arguments: `configuration` and `parameters`. See examples in the user-guide.
 
+ * New options `trainInstancesText`, `testInstancesText`, `parameterText`, and
+   `configurationsText` which accepts the content that is normally in
+   `trainInstancesFile`, `testInstancesFile`, `parameterText`, and 
+   `configurationsText` as a string. (Deyao Chen)
+
 ## Fixes
 
  * Fix (#44): irace now will give an error if the domain of real-valued (r)

R/irace-options.R

@@ -5,13 +5,14 @@
 # FIXME: Add special type for R functions.
 # FIXME: For i and r add their domain.
 .irace.params.def <- structure(list(name = c(".help", ".version", ".check", ".init", 
-".onlytest", "scenarioFile", "execDir", "parameterFile", "initConfigurations", 
-"configurationsFile", "logFile", "recoveryFile", "instances", 
-"trainInstancesDir", "trainInstancesFile", "sampleInstances", 
-"testInstancesDir", "testInstancesFile", "testInstances", "testNbElites", 
-"testIterationElites", "testType", "firstTest", "blockSize", 
-"eachTest", "targetRunner", "targetRunnerLauncher", "targetCmdline", 
-"targetRunnerRetries", "targetRunnerData", "targetRunnerParallel", 
+".onlytest", "scenarioFile", "execDir", "parameterFile", "parameterText", 
+"initConfigurations", "configurationsFile", "configurationsText", 
+"logFile", "recoveryFile", "instances", "trainInstancesDir", 
+"trainInstancesFile", "trainInstancesText", "sampleInstances", 
+"testInstancesDir", "testInstancesFile", "testInstancesText", 
+"testInstances", "testNbElites", "testIterationElites", "testType", 
+"firstTest", "blockSize", "eachTest", "targetRunner", "targetRunnerLauncher", 
+"targetCmdline", "targetRunnerRetries", "targetRunnerData", "targetRunnerParallel", 
 "targetEvaluator", "deterministic", "maxExperiments", "maxTime", 
 "budgetEstimation", "minMeasurableTime", "parallel", "loadBalancing", 
 "mpi", "batchmode", "digits", "quiet", "debugLevel", "seed", 
@@ -20,25 +21,27 @@
 "boundType", "boundMax", "boundDigits", "boundPar", "boundAsTimeout", 
 "postselection", "aclib", "nbIterations", "nbExperimentsPerIteration", 
 "minNbSurvival", "nbConfigurations", "mu", "confidence"), type = c("x", 
-"x", "x", "x", "p", "p", "p", "p", "x", "p", "p", "p", "s", "p", 
-"p", "b", "p", "p", "x", "i", "b", "s", "i", "i", "i", "p", "p", 
-"s", "i", "x", "x", "p", "b", "i", "i", "r", "r", "i", "b", "b", 
-"s", "i", "b", "i", "i", "b", "r", "b", "i", "i", "x", "b", "s", 
-"s", "i", "i", "i", "b", "r", "b", "i", "i", "i", "i", "i", "r"
-), short = c("-h", "-v", "-c", "-i", "", "-s", "", "-p", "", 
-"", "-l", "", "", "", "", "", "", "", "", "", "", "", "", "", 
+"x", "x", "x", "p", "p", "p", "p", "p", "x", "p", "p", "p", "p", 
+"s", "p", "p", "p", "b", "p", "p", "p", "x", "i", "b", "s", "i", 
+"i", "i", "p", "p", "s", "i", "x", "x", "p", "b", "i", "i", "r", 
+"r", "i", "b", "b", "s", "i", "b", "i", "i", "b", "r", "b", "i", 
+"i", "x", "b", "s", "s", "i", "i", "i", "b", "r", "b", "i", "i", 
+"i", "i", "i", "r"), short = c("-h", "-v", "-c", "-i", "", "-s", 
+"", "-p", "", "", "", "", "-l", "", "", "", "", "", "", "", "", 
+"", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", 
+"", "", "", "", "", "", "", "", "", "-q", "", "", "", "", "-e", 
 "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", 
-"", "", "-q", "", "", "", "", "-e", "", "", "", "", "", "", "", 
-"", "", "", "", "", "", "", "", "", "", ""), long = c("--help", 
-"--version", "--check", "--init", "--only-test", "--scenario", 
-"--exec-dir", "--parameter-file", "", "--configurations-file", 
+"", ""), long = c("--help", "--version", "--check", "--init", 
+"--only-test", "--scenario", "--exec-dir", "--parameter-file", 
+"--parameter-text", "", "--configurations-file", "--configurations-text", 
 "--log-file", "--recovery-file", "", "--train-instances-dir", 
-"--train-instances-file", "--sample-instances", "--test-instances-dir", 
-"--test-instances-file", "", "--test-num-elites", "--test-iteration-elites", 
-"--test-type", "--first-test", "--block-size", "--each-test", 
-"--target-runner", "--target-runner-launcher", "--target-cmdline", 
-"--target-runner-retries", "", "", "--target-evaluator", "--deterministic", 
-"--max-experiments", "--max-time", "--budget-estimation", "--min-measurable-time", 
+"--train-instances-file", "--train-instances-text", "--sample-instances", 
+"--test-instances-dir", "--test-instances-file", "--test-instances-text", 
+"", "--test-num-elites", "--test-iteration-elites", "--test-type", 
+"--first-test", "--block-size", "--each-test", "--target-runner", 
+"--target-runner-launcher", "--target-cmdline", "--target-runner-retries", 
+"", "", "--target-evaluator", "--deterministic", "--max-experiments", 
+"--max-time", "--budget-estimation", "--min-measurable-time", 
 "--parallel", "--load-balancing", "--mpi", "--batchmode", "--digits", 
 "--quiet", "--debug-level", "--seed", "--soft-restart", "--soft-restart-threshold", 
 "--elitist", "--elitist-new-instances", "--elitist-limit", "", 
@@ -47,29 +50,35 @@
 "--aclib", "--iterations", "--experiments-per-iteration", "--min-survival", 
 "--num-configurations", "--mu", "--confidence"), default = c(NA, 
 NA, NA, "", "", "./scenario.txt", "./", "./parameters.txt", "", 
-"", "./irace.Rdata", "", "", "./Instances", "", "1", "", "", 
-"", "1", "0", "", "5", "1", "1", "./target-runner", "", "{configurationID} {instanceID} {seed} {instance} {bound} {targetRunnerArgs}", 
+"", "", "", "./irace.Rdata", "", "", "./Instances", "", "", "1", 
+"", "", "", "", "1", "0", "", "5", "1", "1", "./target-runner", 
+"", "{configurationID} {instanceID} {seed} {instance} {bound} {targetRunnerArgs}", 
 "0", "", "", "", "0", "0", "0", "0.02", "0.01", "0", "1", "0", 
 "0", "4", "0", "0", NA, "1", "", "1", "1", "2", "", NA, "median", 
 "candidate", "0", "0", "1", "1", "0", "0", "0", "0", "0", "0", 
 "5", "0.95"), domain = c(NA, NA, NA, NA, NA, NA, NA, NA, NA, 
-NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, "F-test,t-test,t-test-holm,t-test-bonferroni", 
 NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, 
-NA, NA, "sge,pbs,torque,slurm,htcondor", NA, NA, NA, NA, NA, 
-NA, NA, NA, NA, NA, NA, "median,mean,worst,best", "instance,candidate", 
-NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA), description = c("Show this help.", 
-"Show irace package version.", "Check scenario.", "Initialize the working directory with template config files.", 
+"F-test,t-test,t-test-holm,t-test-bonferroni", NA, NA, NA, NA, 
+NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, "sge,pbs,torque,slurm,htcondor", 
+NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, "median,mean,worst,best", 
+"instance,candidate", NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, 
+NA, NA), description = c("Show this help.", "Show irace package version.", 
+"Check scenario.", "Initialize the working directory with template config files.", 
 "Only test the configurations given in the file passed as argument.", 
 "File that describes the configuration scenario setup and other irace settings.", 
 "Directory where the programs will be run.", "File that contains the description of the parameters of the target algorithm.", 
+"A string that contains the description of the parameters of the target algorithm.", 
 "", "File that contains a table of initial configurations. If empty or `NULL`, all initial configurations are randomly generated.", 
+"A string that contains a table of initial configurations. If empty or `NULL`, all initial configurations are randomly generated.", 
 "File to save tuning results as an R dataset, either absolute path or relative to execDir.", 
 "Previously saved log file to recover the execution of `irace`, either absolute path or relative to the current directory.  If empty or `NULL`, recovery is not performed.", 
-"", "Directory where training instances are located; either absolute path or relative to current directory. If no `trainInstancesFiles` is provided, all the files in `trainInstancesDir` will be listed as instances.", 
+"", "Directory where training instances are located; either absolute path or relative to current directory. If no `trainInstancesFiles` or `trainInstancesText` is provided, all the files in `trainInstancesDir` will be listed as instances.", 
 "File that contains a list of training instances and optionally additional parameters for them. If `trainInstancesDir` is provided, `irace` will search for the files in this folder.", 
+"A string that contains a list of training instances and optionally additional parameters for them. If `trainInstancesDir` is provided, `irace` will search for the files in this folder.", 
 "Randomly sample the training instances or use them in the order given.", 
 "Directory where testing instances are located, either absolute or relative to current directory.", 
 "File containing a list of test instances and optionally additional parameters for them.", 
+"A string containing a list of test instances and optionally additional parameters for them.", 
 "", "Number of elite configurations returned by irace that will be tested if test instances are provided.", 
 "Enable/disable testing the elite configurations found at each iteration.", 
 "Statistical test used for elimination. The default value selects `t-test` if `capping` is enabled or `F-test`, otherwise. Valid values are: F-test (Friedman test), t-test (pairwise t-tests with no correction), t-test-bonferroni (t-test with Bonferroni's correction for multiple comparisons), t-test-holm (t-test with Holm's correction for multiple comparisons).", 
@@ -114,28 +123,29 @@ NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA), description = c("Show this help
 "Parameter used to define the number of configurations sampled and evaluated at each iteration.", 
 "Confidence level for the elimination test.")), row.names = c(".help", 
 ".version", ".check", ".init", ".onlytest", "scenarioFile", "execDir", 
-"parameterFile", "initConfigurations", "configurationsFile", 
+"parameterFile", "parameterText", "initConfigurations", "configurationsFile", 
+"configurationsText", "logFile", "recoveryFile", "instances", 
+"trainInstancesDir", "trainInstancesFile", "trainInstancesText", 
+"sampleInstances", "testInstancesDir", "testInstancesFile", "testInstancesText", 
+"testInstances", "testNbElites", "testIterationElites", "testType", 
+"firstTest", "blockSize", "eachTest", "targetRunner", "targetRunnerLauncher", 
+"targetCmdline", "targetRunnerRetries", "targetRunnerData", "targetRunnerParallel", 
+"targetEvaluator", "deterministic", "maxExperiments", "maxTime", 
+"budgetEstimation", "minMeasurableTime", "parallel", "loadBalancing", 
+"mpi", "batchmode", "digits", "quiet", "debugLevel", "seed", 
+"softRestart", "softRestartThreshold", "elitist", "elitistNewInstances", 
+"elitistLimit", "repairConfiguration", "capping", "cappingType", 
+"boundType", "boundMax", "boundDigits", "boundPar", "boundAsTimeout", 
+"postselection", "aclib", "nbIterations", "nbExperimentsPerIteration", 
+"minNbSurvival", "nbConfigurations", "mu", "confidence"), class = "data.frame")
+.irace.params.names <- c("scenarioFile", "execDir", "parameterFile", "parameterText", 
+"initConfigurations", "configurationsFile", "configurationsText", 
 "logFile", "recoveryFile", "instances", "trainInstancesDir", 
-"trainInstancesFile", "sampleInstances", "testInstancesDir", 
-"testInstancesFile", "testInstances", "testNbElites", "testIterationElites", 
-"testType", "firstTest", "blockSize", "eachTest", "targetRunner", 
-"targetRunnerLauncher", "targetCmdline", "targetRunnerRetries", 
-"targetRunnerData", "targetRunnerParallel", "targetEvaluator", 
-"deterministic", "maxExperiments", "maxTime", "budgetEstimation", 
-"minMeasurableTime", "parallel", "loadBalancing", "mpi", "batchmode", 
-"digits", "quiet", "debugLevel", "seed", "softRestart", "softRestartThreshold", 
-"elitist", "elitistNewInstances", "elitistLimit", "repairConfiguration", 
-"capping", "cappingType", "boundType", "boundMax", "boundDigits", 
-"boundPar", "boundAsTimeout", "postselection", "aclib", "nbIterations", 
-"nbExperimentsPerIteration", "minNbSurvival", "nbConfigurations", 
-"mu", "confidence"), class = "data.frame")
-.irace.params.names <- c("scenarioFile", "execDir", "parameterFile", "initConfigurations", 
-"configurationsFile", "logFile", "recoveryFile", "instances", 
-"trainInstancesDir", "trainInstancesFile", "sampleInstances", 
-"testInstancesDir", "testInstancesFile", "testInstances", "testNbElites", 
-"testIterationElites", "testType", "firstTest", "blockSize", 
-"eachTest", "targetRunner", "targetRunnerLauncher", "targetCmdline", 
-"targetRunnerRetries", "targetRunnerData", "targetRunnerParallel", 
+"trainInstancesFile", "trainInstancesText", "sampleInstances", 
+"testInstancesDir", "testInstancesFile", "testInstancesText", 
+"testInstances", "testNbElites", "testIterationElites", "testType", 
+"firstTest", "blockSize", "eachTest", "targetRunner", "targetRunnerLauncher", 
+"targetCmdline", "targetRunnerRetries", "targetRunnerData", "targetRunnerParallel", 
 "targetEvaluator", "deterministic", "maxExperiments", "maxTime", 
 "budgetEstimation", "minMeasurableTime", "parallel", "loadBalancing", 
 "mpi", "batchmode", "digits", "quiet", "debugLevel", "seed", 

R/irace.R

@@ -479,13 +479,15 @@ allConfigurationsInit <- function(scenario, parameters)
   confs_from_file <- NULL
   if (!is.null.or.empty(scenario$configurationsFile)) {
     confs_from_file <- readConfigurationsFile(scenario$configurationsFile,
-                                              parameters, scenario$debugLevel)
+                                              parameters, scenario$debugLevel,
+                                              scenario$configurationsText)
   }
   if (!is.null.or.empty(initConfigurations)) {
-    if (!is.null.or.empty(scenario$configurationsFile) && !identical(initConfigurations, confs_from_file))
+    if ((!is.null.or.empty(scenario$configurationsFile) || !is.null.or.empty(scenario$configurationsText)) 
+      && !identical(initConfigurations, confs_from_file))
       irace.warning("'initConfigurations' provided in 'scenario',",
                     " thus ignoring configurations from file '",
-                    scenario$configurationsFile, "'.")
+                    scenario$configurationsFile, "'and text '", scenario$configurationsText, "'.")
     cat("# Adding", nrow(initConfigurations), "initial configuration(s)\n")
     fix_configurations(initConfigurations, parameters, debugLevel = scenario$debugLevel)
   } else {
@@ -571,7 +573,8 @@ irace_common <- function(scenario, parameters, simple, output.width = 9999L)
     # Read parameters definition
     parameters <- readParameters (file = scenario$parameterFile,
                                   digits = scenario$digits,
-                                  debugLevel = debugLevel)
+                                  debugLevel = debugLevel,
+                                  text = scenario$parameterText)
   } else {
     parameters <- checkParameters(parameters)
   }

R/main.R

@@ -66,11 +66,12 @@ cat_irace_license <- function()
 #'   output.
 #'
 #' @details This function checks the correctness of the scenario, reads the
-#'   parameter space from \code{scenario$parameterFile}, invokes [irace()],
-#'   prints its results in various formatted ways, (optionally) calls
-#'   [psRace()] and, finally, evaluates the best configurations on the test
-#'   instances (if provided). If you want a lower-level interface that just
-#'   runs irace, please see function [irace()].
+#'   parameter space from \code{scenario$parameterFile} or 
+#'   \code{scenario$parameterText}, invokes [irace()], prints its results in 
+#'   various formatted ways, (optionally) calls [psRace()] and, finally, 
+#'   evaluates the best configurations on the test instances (if provided). 
+#'   If you want a lower-level interface that just runs irace, 
+#'   please see function [irace()].
 #'
 #' @templateVar return_invisible TRUE
 #' @template return_irace
@@ -206,8 +207,10 @@ testing_fromfile <- function(filename, scenario)
   if (!scenario$quiet) printScenario(scenario)
 
   irace.note("Reading parameter file '", scenario$parameterFile, "'.\n")
+  irace.note("Parsing parameter text '", scenario$parameterText, "'.\n")
   parameters <- readParameters (file = scenario$parameterFile,
-                                digits = scenario$digits)
+                                digits = scenario$digits,
+                                text = scenario$parameterText)
   configurations <- readConfigurationsFile (filename, parameters)
   configurations <- cbind(.ID. = 1:nrow(configurations),
                              configurations,
@@ -255,9 +258,10 @@ testing_common <- function(configurations, scenario, parameters, iraceResults)
 #' \code{FALSE} otherwise.
 #' 
 #' @details If the `parameters` argument is missing, then the parameters 
-#'   will be read from the file `parameterFile`  given by `scenario`. If
-#'   `parameters` is provided, then `parameterFile` will not be read.  This function will
-#'   try to execute the target-algorithm.
+#'   will be read from the file `parameterFile` or string `parameterText` 
+#'   given by `scenario`. If `parameters` is provided, then `parameterFile` 
+#'   or `parameterText` will not be read.  This function will try to execute 
+#'   the target-algorithm.
 #'
 #' @seealso
 #'  \describe{
@@ -280,11 +284,13 @@ checkIraceScenario <- function(scenario, parameters)
     irace.note("Reading parameter file '", scenario$parameterFile, "'.\n")
     parameters <- readParameters (file = scenario$parameterFile,
                                   digits = scenario$digits,
-                                  debugLevel = 2)
-  } else if (!is.null.or.empty(scenario$parameterFile)) {
+                                  debugLevel = 2,
+                                  text = scenario$parameterText)
+  } else if (!is.null.or.empty(scenario$parameterFile) || !is.null.or.empty(scenario$parameterText)) {
     if (!scenario$quiet) 
       cat("# checkIraceScenario(): 'parameters' provided by user. ",
-          "Parameter file '", scenario$parameterFile, "' will be ignored\n", sep = "")
+          "Parameter file '", scenario$parameterFile, "' and parameter text '", 
+          scenario$parameterText, "' will be ignored\n", sep = "")
   }
   checkParameters(parameters)
   irace.note("Checking target runner.\n")