Named simulationResults lists (#1383)

NEWS.md

@@ -1,22 +1,24 @@
 # ospsuite 12.0 (development)
 
 ## New dependencies
-- `{openxlsx}`
+
+  - `{openxlsx}`
 
 ## New features
 
-- Added a function `getSteadyState()` to calculate steady state values for simulations.
-This function is of particular use for models of endogenous substrates, where changing
-a parameter value (e.g., the production rate) will change the steady-state values of
-the substrate.
-The steady-state is considered to be the last values of the molecules amounts 
-  and state variable parameters in the simulation with sufficiently long simulation
-  time, i.e., where the rates of the processes do not (significantly) change.
-  The steady-state is NOT analytically calculated or estimated in any other way 
-  than simulating for the given time.
+  - Added a function `getSteadyState()` to calculate steady state values for
+    simulations. This function is of particular use for models of endogenous
+    substrates, where changing a parameter value (e.g., the production rate)
+    will change the steady-state values of the substrate. The steady-state is
+    considered to be the last values of the molecules amounts and state variable
+    parameters in the simulation with sufficiently long simulation time, i.e.,
+    where the rates of the processes do not (significantly) change. The
+    steady-state is NOT analytically calculated or estimated in any other way
+    than simulating for the given time.
 
-- Added a function `exportSteadyStateToXLS()` to export steady state values calculated 
-for one simulation using the `getSteadyState()` to an Excel file that can be imported in MoBi.
+  - Added a function `exportSteadyStateToXLS()` to export steady state values
+    calculated for one simulation using the `getSteadyState()` to an Excel file
+    that can be imported in MoBi.
 
 ## Breaking Changes
 
@@ -43,7 +45,11 @@ for one simulation using the `getSteadyState()` to an Excel file that can be imp
 
 
 ## Minor improvements and bug fixes
-
+
+  - Named `Simulation` lists can be passed to `runSimulations()` so that the
+    results are returned as a named list using the same names instead of the
+    simulation id. If no name is provided, the simulation id is used as before.
+    (\#1383)
   - The order of columns of the data frame returned by
     `DataCombined$toDataFrame()` has changed.
   - `DataCombined$toDataFrame()`
@@ -59,7 +65,7 @@ not present in the `DataCombined`.
     through new `DefaultPlotConfiguration` fields (\#1216)
   - `plotObsVsPred()` now have foldDistance argument set to `NULL` by default
     (previously 2). The function will not add any fold lines on the plot by
-    default but display identity line. Set this argument to `FALSE` to not draw 
+    default but display identity line. Set this argument to `FALSE` to not draw
     any lines.
   - `DefaultPlotConfiguration` has a new setting: `displayLLOQ` (default TRUE)
     to control plotting of LLOQ lines.
@@ -75,14 +81,17 @@ not present in the `DataCombined`.
     repeatedly, consider switching the parameter from the default `FALSE` value
     to `TRUE`.
   - `simulationResultsToDataFrame()` is faster than before (\#1317, @Felixmil).
-  - `DataCombined` gets a new method `setDataTypes()` to change data types (observed
-  or simulated) for existing data sets. This method is useful when you want to
-  enforce a certain data type, e.g., for adding artificial data set as simulated results.
+  - `DataCombined` gets a new method `setDataTypes()` to change data types
+    (observed or simulated) for existing data sets. This method is useful when
+    you want to enforce a certain data type, e.g., for adding artificial data
+    set as simulated results.
   - New function `setOutputs()` to change outputs of `SimulationBatch` objects.
-  It combines `clearOutputs()` and `setOutputs()` in one function.
-  - New simulations life cycle flowcharts in the `vignette("efficient-calculations")` vignette.
+    It combines `clearOutputs()` and `setOutputs()` in one function.
+  - New simulations life cycle flowcharts in the
+    `vignette("efficient-calculations")` vignette.
   - New internal function `.setEndSimulationTime()` to set the end time of the
-    simulation. The function will either extend or shorten the simulation time to the specified end time.
+    simulation. The function will either extend or shorten the simulation time
+    to the specified end time.
 
 
 # ospsuite 11.1.197

R/utilities-simulation.R

@@ -132,8 +132,9 @@ runSimulation <- function(simulation, population = NULL, agingData = NULL, simul
 #' For single simulation, either individual or population simulations can be
 #' performed.
 #'
-#' @param simulations One `Simulation` or list of `Simulation` objects
-#' to simulate.
+#' @param simulations One `Simulation` or a list or vector of `Simulation` objects
+#' to simulate. List or vector can be named, in which case the names will reused in the `simulationResults` output list.
+#' If not named, the output list will use simulation ids.
 #' @param population Optional instance of a `Population` to use for the simulation.
 #' Only allowed when simulating one simulation.
 #' Alternatively, you can also pass the result of `createPopulation` directly.
@@ -188,21 +189,38 @@ runSimulations <- function(simulations, population = NULL, agingData = NULL, sim
     )
     outputList <- list()
     outputList[[simulations[[1]]$id]] <- results
-    return(outputList)
+  } else {
+
+    # more than one simulation? This is a concurrent run.
+
+    # We do not allow population variation
+    if (!is.null(population)) {
+      stop(messages$errorMultipleSimulationsCannotBeUsedWithPopulation)
+    }
+
+    # we are now running the simulations concurrently
+    outputList <- .runSimulationsConcurrently(
+      simulations = simulations,
+      simulationRunOptions = simulationRunOptions,
+      silentMode = silentMode,
+      stopIfFails = stopIfFails
+    )
   }
 
-  # more than one simulation? This is a concurrent run. We do not allow population variation
-  if (!is.null(population)) {
-    stop(messages$errorMultipleSimulationsCannotBeUsedWithPopulation)
+
+  simulationNames <- names(simulations)
+
+  if (!is.null(simulationNames)) {
+    for (i in seq_along(outputList)) {
+      if (simulationNames[i] != "") {
+        names(outputList)[i] <- simulationNames[i]
+      }
+    }
   }
 
-  # we are now running the simulations concurrently
-  return(.runSimulationsConcurrently(
-    simulations = simulations,
-    simulationRunOptions = simulationRunOptions,
-    silentMode = silentMode,
-    stopIfFails = stopIfFails
-  ))
+
+
+  return(outputList)
 }
 
 .runSingleSimulation <- function(simulation, simulationRunOptions, population = NULL, agingData = NULL) {

tests/testthat/test-utilities-simulation.R

@@ -171,6 +171,41 @@ test_that("runSimulations returns a named list for one simulation", {
   expect_true(isOfType(results[[1]], "SimulationResults"))
 })
 
+test_that("runSimulations returns named list using input list names", {
+  resetSimulationCache()
+  sim1 <- loadTestSimulation("S1", loadFromCache = FALSE)
+  sim2 <- loadTestSimulation("S1", loadFromCache = FALSE)
+
+
+  # No names
+  expect_contains(
+    names(runSimulations(list(sim1, sim2))),
+    c(sim1$id, sim2$id)
+  )
+
+  # One name element
+  expect_equal(
+    names(runSimulations(list(sim1 = sim1))),
+    "sim1"
+  )
+
+  # Full named list
+  expect_equal(
+    names(runSimulations(list(sim1 = sim1, sim2 = sim2))),
+    c("sim1", "sim2")
+  )
+
+  # Partially named list
+  expect_equal(
+    names(runSimulations(list(sim1 = sim1, sim2))),
+    c("sim1", sim2$id)
+  )
+  expect_equal(
+    names(runSimulations(list(sim1, sim2 = sim2))),
+    c(sim1$id, "sim2")
+  )
+})
+
 test_that("It runs multiple individual simulations", {
   resetSimulationCache()
   sim <- loadTestSimulation("S1", loadFromCache = FALSE)