CRAN Revisions 5 (#32)

* Modified 'DESCRIPTION' to comply with CRAN requirements. Started modifications to 'compileModel.R' and 'createModel.R'.

* Change default compilation location to tmp directory. Use writeTmp=T to write compilation files to temp directory and use writeTmp=F to write compilation files to same directory as .model file

* Added 'Free Software Foundation, Inc.' with role 'cph' to 'Authors' field in file 'DESCRIPTION'.

* Copy whole file to tmp as opposed copying contents of file. Issue with End of Line (EOL) characters caused problems in Windows

* Add missing comma in DESCRIPTION

* Suppress console prints from C code

* Made minor revisions to 'MCSim_model.R' and 'createModel.R'. Updated vignettes to reflect new default behavior for saving model output files and to remove the (now unnecssaary) calls to the 'cleanup()' method.

* Added various error checking features. Still working on making mod translator output available when there is an error in translation.

* Revised 'compileModel.R' to ensure that problems with MCSim model text translation are logged and appropriate error message is provided.

* Used styler to ensure proper formatting of 'compileModel.R'.

* Revised 'compileModel.R' to ensure the C compiler output is captured and logged.

* Applied styler to correct formatting of 'compileModel.R'.

* add tests

* Made minor revisions to 'compileModel.R' and 'test-compileModel.R'.

---------

Co-authored-by: AA\tzurlind <[email protected]>
Co-authored-by: Andy Shapiro <[email protected]>

Author: 3 people

DESCRIPTION

@@ -1,14 +1,15 @@
 Package: MCSimMod
-Title: An 'R' Package for Working with 'MCSim' Models
+Title: Working with 'MCSim' Models
 Version: 0.9
 Authors@R: c(
  person("Dustin F.", "Kapraun", role=c("aut", "cre"), email = "[email protected]", comment = c(ORCID = "0000-0001-5570-6383")),
 	person("Todd J.", "Zurlinden", role="aut", comment = c(ORCID = "0000-0003-1372-3913")),
 	person("Andrew J.", "Shapiro", role="aut", comment = c(ORCID = "0000-0002-5233-8092")),
 	person("Ryan D.", "Friese", role="aut", comment = c(ORCID = "0000-0002-4121-2195")),
-	person("Frederic Y.", "Bois", role="ctb", comment = c(ORCID = " 0000-0002-4154-0391"))
+	person("Frederic Y.", "Bois", role="ctb", comment = c(ORCID = " 0000-0002-4154-0391")),
+	person("Free Software Foundation, Inc.", role="cph")
 	)
-Description: Tools that facilitate ordinary differential equation (ODE) modeling in 'R'. This package allows one to perform simulations for ODE models that are encoded in the GNU 'MCSim' model specification language using ODE solvers from the 'R' package 'deSolve'.
+Description: Tools that facilitate ordinary differential equation (ODE) modeling in 'R'. This package allows one to perform simulations for ODE models that are encoded in the GNU 'MCSim' model specification language (Bois, 2009) <doi:10.1093/bioinformatics/btp162> using ODE solvers from the 'R' package 'deSolve' (Soetaert et al., 2010) <doi:10.18637/jss.v033.i09>.
 Depends:
 	methods,
 	tools

R/MCSim_model.R

@@ -31,22 +31,36 @@ Model <- setRefClass("Model",
     #' @field parms Named vector of parameter values for the associated MCSim model.
     #' @field Y0 Named vector of initial conditions for the state variables of the associated MCSim model.
     #' @field paths List of character strings that are names of files associated with the model.
+    #' @field writeTemp Boolean specifying whether to write model files to a temporary directory. If value is TRUE, model files will be Written to a temporary directory; if value is FALSE, model files will be Written to the same directory that contains the model specification file.
     mName = "character", mString = "character", initParms = "function",
     initStates = "function", Outputs = "ANY", parms = "numeric", Y0 = "numeric",
-    paths = "list"
+    paths = "list", writeTemp = "logical"
   ),
   methods = list(
     initialize = function(...) {
       "Initialize the Model object using an MCSim model specification file (mName) or an MCSim model specification string (mString)."
       callSuper(...)
+      if (length(mName) == 0 & length(mString) == 0) {
+        stop("To create a Model object, supply either a file name (mName) or a model specification string (mString).")
+      }
       if (length(mName) > 0 & length(mString) > 0) {
         stop("Cannot create a Model object using both a file name (mName) and a model specification string (mString). Provide only one of these arguments.")
       }
       if (length(mString) > 0) {
+        if (writeTemp == FALSE) {
+          stop("The value of writeTemp must be TRUE when creating a Model object using a model specification string (mstring).")
+        }
         file <- tempfile(pattern = "mcsimmod_", fileext = ".model")
         writeLines(mString, file)
       } else {
-        file <- normalizePath(paste0(mName, ".model"))
+        if (writeTemp == TRUE) {
+          source_file <- normalizePath(paste0(mName, ".model"))
+          temp_directory <- tempdir()
+          file <- file.path(temp_directory, basename(source_file))
+          file_copied <- file.copy(from = source_file, to = file)
+        } else {
+          file <- normalizePath(paste0(mName, ".model"))
+        }
       }
       mList <- .fixPath(file)
       mName <<- mList$mName

R/compileModel.R

@@ -9,7 +9,7 @@
 #' @param dll_name Name of a DLL or SO file without the extension (".dll" or ".so").
 #' @param dll_file Name of the same DLL or SO file with the appropriate extension (".dll" or ".so").
 #' @param hash_file Name of a file containing a hash key for determining if `model_file` has changed since the previous translation and compilation.
-#'
+#' @returns No return value. Creates files and saves them in locations specified by function arguments.
 #' @import tools
 #' @useDynLib MCSimMod, .registration=TRUE
 #' @export
@@ -19,23 +19,74 @@ compileModel <- function(model_file, c_file, dll_name, dll_file, hash_file = NUL
     dyn.unload(dll_file)
   }
 
+  # Create a text connection to store output messages generated during the
+  # translation from MCSim model specification text to C.
+  text_conn <- textConnection("mod_output", open = "w")
+
   # Create a C model file (ending with ".c") and an R parameter
   # initialization file (ending with "_inits.R") from the GNU MCSim model
-  # definition file (ending with ".model"). Using the "-R" option generates
-  # code compatible with functions in the R deSolve package.
+  # specification file (ending with ".model"). Write translator output to the
+  # text connection.
+  sink(text_conn)
+  .C("c_mod", model_file, c_file)
+  sink()
+  close(text_conn)
+  mod_output <- paste(mod_output, collapse = "\n")
 
-  # if (.C("c_mod", model_file, c_file)[[1]] < 0) {
-  if (is.null(.C("c_mod", model_file, c_file)[[2]])) {
-    stop("c_mod failed")
+  # Check to see if there was an error during translation. If so, save the
+  # translator output to a file, print a message about its location, and stop
+  # execution.
+  if (grepl("*** Error:", mod_output, fixed = TRUE)) {
+    temp_directory <- tempdir()
+    out_file <- file.path(temp_directory, "mod_output.txt")
+    write(mod_output, file = out_file)
+    stop(
+      "An error was identified when translating the MCSim model specification ",
+      "text to C. Full details are available in the file ",
+      normalizePath(out_file), "."
+    )
   }
 
-  # Compile the C model to obtain "mName_model.o" and "mName_model.dll".
+  # Check to see if there was a warning during translation. If so, save the
+  # translator output to a file, print a message about its location, and raise a
+  # warning.
+  if (grepl("*** Warning:", mod_output, fixed = TRUE)) {
+    temp_directory <- tempdir()
+    out_file <- file.path(temp_directory, "mod_output.txt")
+    write(mod_output, file = out_file)
+    warning(
+      "A warning was identified when translating the MCSim model ",
+      "specification text to C. Full details are available in the file ",
+      normalizePath(out_file), "."
+    )
+  }
+
+  # Compile the C model to obtain an object file (ending with ".o") and a
+  # machine code file (ending with ".dll" or ".so"). Write compiler output
+  # to a character string.
   r_path <- file.path(R.home("bin"), "R")
-  system(paste0(r_path, " CMD SHLIB ", c_file))
+  compiler_output <- system(paste(
+    shQuote(r_path), "CMD SHLIB",
+    shQuote(c_file)
+  ), intern = TRUE)
+
+  # Save the compiler output to a file and print a message about its location.
+  temp_directory <- tempdir()
+  out_file <- file.path(temp_directory, "compiler_output.txt")
+  write(compiler_output, file = out_file)
+  message(
+    "C compilation complete. Full details are available in the file ",
+    normalizePath(out_file), "."
+  )
 
+  # If hash file name was provided, create a hash (md5 sum) for the model file
+  # and print a message about its location.
   if (!is.null(hash_file)) {
     file_hash <- as.character(md5sum(model_file))
     write(file_hash, file = hash_file)
-    cat("Hash calculated and saved to", hash_file, "\n")
+    message(
+      "Hash created and saved in the file ", normalizePath(hash_file),
+      "."
+    )
   }
 }

R/createModel.R

@@ -23,7 +23,9 @@
 #'
 #' @param mName Name of an MCSim model specification file, excluding the file name extension `.model`.
 #' @param mString A character string containing MCSim model specification text.
+#' @param writeTemp Boolean specifying whether to write model files to a temporary directory. If value is TRUE (the default), model files will be Written to a temporary directory; if value is FALSE, model files will be Written to the same directory that contains the model specification file.
+#' @returns Model object.
 #' @export
-createModel <- function(mName = character(0), mString = character(0)) {
-  return(Model(mName = mName, mString = mString))
+createModel <- function(mName = character(0), mString = character(0), writeTemp = TRUE) {
+  return(Model(mName = mName, mString = mString, writeTemp = writeTemp))
 }

man/Model-class.Rd

@@ -0,0 +1,38 @@
+testthat::test_that("compileModel::error", {
+  modelString <- "bad model"
+  model <- createModel(mString = modelString)
+  testthat::expect_error(
+    model$loadModel(),
+    "An error was identified when translating the MCSim model specification"
+  )
+})
+
+testthat::test_that("compileModel::warning", {
+  # defining the input Bin as a dynamic will trigger a warning
+  modelString <- "
+    States = {A};
+    Outputs = {Bout, Cout};
+    Inputs = {Bin, Cin};
+    A0 = 1e-6;
+    r = 1.4;
+
+    Initialize {
+        A = A0;
+    }
+
+    Dynamics {
+        Bin = 2;
+        Bout = Bin;
+        Cout = Cin;
+        dt(A) = r * A;
+    }
+
+    End.
+    "
+
+  model <- createModel(mString = modelString)
+  testthat::expect_warning(
+    model$loadModel(),
+    "A warning was identified when translating the MCSim model specification"
+  )
+})

man/compileModel.Rd

@@ -134,11 +134,3 @@ plot(out[, "time"], out[, "C"],
   xlab = "Time (h)", ylab = "Concentration (mg/L)"
 )
 ```
-
-## Removing Output Files
-
-We can remove output files that were created when building the model (i.e., files with names ending in ".c", ".o", "_inits.R", and ".dll" or ".so") by calling the `cleanup()` method.
-```{r, results='hide'}
-# Remove output files that were created when building the model.
-pk1_mod$cleanup()
-```

man/createModel.Rd

@@ -101,7 +101,7 @@ exp_mod_name <- file.path(mod_path, "exponential")
 exp_mod <- createModel(exp_mod_name)
 ```
 
-Once the model object is created, we can "load" the model (so that it's ready for use in a given R session) as follows. If necessary (e.g., when the model has not previously been "built"), this step will create output files (with names ending in ".c", ".o", "_inits.R", and ".dll" or ".so") in the same directory that contains the model specification file (with a name ending in ".model"). Some of these model files (the ones with names ending in "_inits.R" and ".dll" or ".so") are used to perform simulations with the model.
+Once the model object is created, we can "load" the model (so that it's ready for use in a given R session) as follows. If necessary (e.g., when the model has not previously been "built"), this step will create output files (with names ending in ".c", ".o", "_inits.R", and ".dll" or ".so") in a temporary directory. Some of these model files (the ones with names ending in "_inits.R" and ".dll" or ".so") are used to perform simulations with the model.
 ```{r, results='hide'}
 # Load the model.
 exp_mod$loadModel()
@@ -153,11 +153,3 @@ plot(out[, "time"], out[, "A"],
   xlab = "Time", ylab = "Amount"
 )
 ```
-
-## Removing Output Files
-
-We can remove output files that were created when building the model (i.e., files with names ending in ".c", ".o", "_inits.R", and ".dll" or ".so") by calling the `cleanup()` method.
-```{r, results='hide'}
-# Remove output files that were created when building the model.
-exp_mod$cleanup()
-```

tests/testthat/test-compileModel.R

@@ -140,11 +140,3 @@ legend("topright",
 )
 ```
 Note that for the "varying body mass" simulation, the increase in body mass had a diluting effect on concentration. That is, concentrations tended to be less for the "varying body mass" scenario than for the "constant body mass" scenario because increases in body mass ($M$) and corresponding increases in volume of distribution ($V_\textrm{d}$) caused concentration ($C$) to decrease more rapidly than would be the case for a constant body mass scenario in which clearance processes alone effect reductions in concentration.
-
-## Removing Output Files
-
-We can remove output files that were created when building the model (i.e., files with names ending in ".c", ".o", "_inits.R", and ".dll" or ".so") by calling the `cleanup()` method.
-```{r, results='hide'}
-# Remove output files that were created when building the model.
-pk1_mod$cleanup()
-```

vignettes/events_demo.Rmd

@@ -108,11 +108,3 @@ legend("topright", c("Tea", "Ambient Air"),
   lwd = c(2, 2)
 )
 ```
-
-## Removing Output Files
-
-We can remove output files that were created when building the model (i.e., files with names ending in ".c", ".o", "_inits.R", and ".dll" or ".so") by calling the `cleanup()` method.
-```{r, results='hide'}
-# Remove output files that were created when building the model.
-newt_mod$cleanup()
-```

vignettes/exponential_demo.Rmd

@@ -159,16 +159,10 @@ lines(out_IV[, "time"], out_IV[, "C"], lty = 2, lwd = 2)
 legend("topright", c("Oral", "IV"), lty = c(1, 2), lwd = 2)
 ```
 
+## Comparing AUC Values for Oral and IV Dosing Scenarios
+
 Because the PK model we're using assumes that 100% of the substance in the exposure compartment (i.e., $A_0$) will eventually be transferred to the central compartment (i.e., 100% bioavailability for the oral exposure scenario) and 100% of an IV dose is delivered directly to the central compartment, the AUCs (at $t = \infty$) for the oral and IV exposure scenarios should be equal. We can verify that the AUCs at $t = 20$ hours (by which time most of the substance has been cleared) for both scenarios are approximately equal by examining the value of the $\textrm{AUC}$ output variable in the final row of the respective output matrices.
 ```{r}
 out_oral[nrow(out_oral), "AUC"]
 out_IV[nrow(out_IV), "AUC"]
 ```
-
-## Removing Output Files
-
-We can remove output files that were created when building the model (i.e., files with names ending in ".c", ".o", "_inits.R", and ".dll" or ".so") by calling the `cleanup` method.
-```{r, results='hide'}
-# Remove output files that were created when building the model.
-pk1_mod$cleanup()
-```

vignettes/inputs_demo.Rmd

@@ -77,10 +77,3 @@ plot(out[, "time"], out[, "y"],
   ylab = "y"
 )
 ```
-
-We can remove output files that were created when building the model (i.e., files with names ending in ".c", ".o", "_inits.R", and ".dll" or ".so") by calling the `cleanup()` method. Using the argument `deleteModel = TRUE` causes the model file (with name ending in ".model") that was created from the model string to also be deleted.
-
-```{r, results='hide'}
-# Remove temporary files that were created when building the model.
-model$cleanup(deleteModel = TRUE)
-```