Update documentation (#90)

* Updating documentation * Add Linux keyring guidance to README * Revise vignette eval flags
OHDSI · Oct 2, 2023 · 2723361 · 2723361
1 parent 00899d8
commit 2723361
Show file tree

Hide file tree

Showing 57 changed files with 2,668 additions and 396 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -2,10 +2,10 @@ Package: Strategus
 Type: Package
 Title: Coordinating and Executing Analytics Using HADES Modules
 Version: 0.1.0
-Date: 2023-08-15
+Date: 2023-09-25
 Authors@R: c(
-	person("Martijn", "Schuemie", email = "[email protected]", role = c("aut", "cre")),
-	person("Anthony", "Sena", email = "[email protected]", role = c("aut")),
+	person("Martijn", "Schuemie", email = "[email protected]", role = c("aut")),
+	person("Anthony", "Sena", email = "[email protected]", role = c("aut", "cre")),
 	person("Jamie", "Gilbert", role = c("aut")),
 	person("Observational Health Data Science and Informatics", role = c("cph"))
   )

diff --git a/R/Execution.R b/R/Execution.R
@@ -102,32 +102,33 @@ generateTargetsScript <- function(analysisSpecifications, executionSettings, dep
   }
 
   ### Note anything inisde this block will be scoped inside the targets script file
-  targets::tar_script({
-    ##
-    # Generated by Strategus - not advisable to edit by hand
-    ##
-    analysisSpecificationsLoad <- readRDS(analysisSpecificationsFileName)
-    moduleToTargetNames <- readRDS(moduleToTargetNamesFileName)
-    dependencies <- readRDS(dependenciesFileName)
-
-    targets::tar_option_set(packages = c("Strategus", "keyring"), imports = c("Strategus", "keyring"))
-    targetList <- list(
-      targets::tar_target(analysisSpecifications, readRDS(analysisSpecificationsFileName)),
-      # NOTE Execution settings could be mapped to many different cdms making re-execution across cdms much simpler
-      targets::tar_target(executionSettings, readRDS(executionSettingsFileName)),
-      targets::tar_target(keyringSettings, readRDS(keyringSettingsFileName))
-    )
-
-    # factory for producing module targets based on their dependencies
-    # This could be inside Strategus as an exported function
-    # it would also be much cleaner to use a targets pattern = cross(analysisSpecifications$moduleSpecifications)
-    # however, working out how to handle dependencies wasn't obvious
-    # This approach could be modified to allow multiple executionSettings, but that would require a substantial re-write
-    for (i in 1:length(analysisSpecificationsLoad$moduleSpecifications)) {
-      moduleSpecification <- analysisSpecificationsLoad$moduleSpecifications[[i]]
-      targetName <- sprintf("%s_%d", moduleSpecification$module, i)
-      dependencyModules <- dependencies[dependencies$module == moduleSpecification$module,]$dependsOn
-      dependencyTargetNames <- moduleToTargetNames[moduleToTargetNames$module %in% dependencyModules,]$targetName
+  targets::tar_script(
+    {
+      ##
+      # Generated by Strategus - not advisable to edit by hand
+      ##
+      analysisSpecificationsLoad <- readRDS(analysisSpecificationsFileName)
+      moduleToTargetNames <- readRDS(moduleToTargetNamesFileName)
+      dependencies <- readRDS(dependenciesFileName)
+
+      targets::tar_option_set(packages = c("Strategus", "keyring"), imports = c("Strategus", "keyring"))
+      targetList <- list(
+        targets::tar_target(analysisSpecifications, readRDS(analysisSpecificationsFileName)),
+        # NOTE Execution settings could be mapped to many different cdms making re-execution across cdms much simpler
+        targets::tar_target(executionSettings, readRDS(executionSettingsFileName)),
+        targets::tar_target(keyringSettings, readRDS(keyringSettingsFileName))
+      )
+
+      # factory for producing module targets based on their dependencies
+      # This could be inside Strategus as an exported function
+      # it would also be much cleaner to use a targets pattern = cross(analysisSpecifications$moduleSpecifications)
+      # however, working out how to handle dependencies wasn't obvious
+      # This approach could be modified to allow multiple executionSettings, but that would require a substantial re-write
+      for (i in 1:length(analysisSpecificationsLoad$moduleSpecifications)) {
+        moduleSpecification <- analysisSpecificationsLoad$moduleSpecifications[[i]]
+        targetName <- sprintf("%s_%d", moduleSpecification$module, i)
+        dependencyModules <- dependencies[dependencies$module == moduleSpecification$module, ]$dependsOn
+        dependencyTargetNames <- moduleToTargetNames[moduleToTargetNames$module %in% dependencyModules, ]$targetName
 
         # Use of tar_target_raw allows dynamic names
         targetList[[length(targetList) + 1]] <- targets::tar_target_raw(targetName,
@@ -148,9 +149,11 @@ generateTargetsScript <- function(analysisSpecifications, executionSettings, dep
         }
       }
       targetList
-  }, script = fileName)
+    },
+    script = fileName
+  )
 
-  #Store settings objects in the temp folder so they are available in targets
+  # Store settings objects in the temp folder so they are available in targets
   analysisSpecificationsFileName <- gsub("\\\\", "/", file.path(executionScriptFolder, "analysisSpecifications.rds"))
   saveRDS(analysisSpecifications, analysisSpecificationsFileName)
   executionSettingsFileName <- gsub("\\\\", "/", file.path(executionScriptFolder, "executionSettings.rds"))
@@ -175,9 +178,11 @@ generateTargetsScript <- function(analysisSpecifications, executionSettings, dep
   dependenciesFileName <- gsub("\\\\", "/", file.path(executionScriptFolder, "dependencies.rds"))
   saveRDS(dependencies, dependenciesFileName)
 
-  execResultsUpload <- all(c(is(executionSettings, "CdmExecutionSettings"),
-                             !is.null(executionSettings$resultsConnectionDetailsReference),
-                             !is.null(executionSettings$resultsDatabaseSchema)))
+  execResultsUpload <- all(c(
+    is(executionSettings, "CdmExecutionSettings"),
+    !is.null(executionSettings$resultsConnectionDetailsReference),
+    !is.null(executionSettings$resultsDatabaseSchema)
+  ))
 
   # Settings required inside script. There is probably a much cleaner way of doing this
   writeLines(c(
@@ -192,4 +197,3 @@ generateTargetsScript <- function(analysisSpecifications, executionSettings, dep
 
   return(fileName)
 }
-
diff --git a/R/ModuleEnv.R b/R/ModuleEnv.R
@@ -14,12 +14,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-.handleInjectVar <- function (x) {
+.handleInjectVar <- function(x) {
   hVar <- function(x) {
     if (is.character(x)) {
       return(sprintf('"%s"', x))
     } else {
-      return(sprintf('%s', x))
+      return(sprintf("%s", x))
     }
   }
 

diff --git a/R/ModuleInstantiation.R b/R/ModuleInstantiation.R
@@ -194,10 +194,10 @@ instantiateModule <- function(module, version, remoteRepo, remoteUsername, modul
   withModuleRenv(
     code = {
       ParallelLogger::addDefaultFileLogger(
-        fileName = file.path(moduleFolder, 'moduleInitLog.txt')
+        fileName = file.path(moduleFolder, "moduleInitLog.txt")
       )
       ParallelLogger::addDefaultErrorReportLogger(
-        fileName = file.path(moduleFolder, 'moduleInitErrorReport.txt')
+        fileName = file.path(moduleFolder, "moduleInitErrorReport.txt")
       )
       renv::restore(prompt = FALSE)
     },

diff --git a/R/ResultModelCreation.R b/R/ResultModelCreation.R
@@ -53,22 +53,23 @@ createResultDataModels <- function(analysisSpecifications,
   ##
   # Code execution inside targets block
   ##
-  targets::tar_script({
-    ##
-    # Generated by Strategus - not advisable to edit by hand
-    ##
-    analysisSpecificationsLoad <- readRDS(analysisSpecificationsFileName)
-
-    targets::tar_option_set(packages = c("Strategus", "keyring"), imports = c("Strategus", "keyring"))
-    targetList <- list(
-      targets::tar_target(analysisSpecifications, readRDS(analysisSpecificationsFileName)),
-      targets::tar_target(executionSettings, readRDS(executionSettingsFileName)),
-      targets::tar_target(keyringSettings, readRDS(keyringSettingsFileName))
-    )
-
-    for (i in 1:length(analysisSpecificationsLoad$moduleSpecifications)) {
-      moduleSpecification <- analysisSpecificationsLoad$moduleSpecifications[[i]]
-      targetName <- sprintf("%s_%d_schema_creation", moduleSpecification$module, i)
+  targets::tar_script(
+    {
+      ##
+      # Generated by Strategus - not advisable to edit by hand
+      ##
+      analysisSpecificationsLoad <- readRDS(analysisSpecificationsFileName)
+
+      targets::tar_option_set(packages = c("Strategus", "keyring"), imports = c("Strategus", "keyring"))
+      targetList <- list(
+        targets::tar_target(analysisSpecifications, readRDS(analysisSpecificationsFileName)),
+        targets::tar_target(executionSettings, readRDS(executionSettingsFileName)),
+        targets::tar_target(keyringSettings, readRDS(keyringSettingsFileName))
+      )
+
+      for (i in 1:length(analysisSpecificationsLoad$moduleSpecifications)) {
+        moduleSpecification <- analysisSpecificationsLoad$moduleSpecifications[[i]]
+        targetName <- sprintf("%s_%d_schema_creation", moduleSpecification$module, i)
 
         # Use of tar_target_raw allows dynamic names
         targetList[[length(targetList) + 1]] <- targets::tar_target_raw(targetName,
@@ -83,7 +84,7 @@ createResultDataModels <- function(analysisSpecifications,
     script = script
   )
 
-  #Store settings objects in the temp folder so they are available in targets
+  # Store settings objects in the temp folder so they are available in targets
   analysisSpecificationsFileName <- gsub("\\\\", "/", file.path(executionScriptFolder, "analysisSpecifications.rds"))
   saveRDS(analysisSpecifications, analysisSpecificationsFileName)
   executionSettingsFileName <- gsub("\\\\", "/", file.path(executionScriptFolder, "executionSettings.rds"))
@@ -175,29 +176,28 @@ runSchemaCreation <- function(analysisSpecifications, keyringSettings, moduleInd
       createDataModelSchema <- NULL
 
       getDataModelSpecifications <- function(...) {
-        if (file.exists('resultsDataModelSpecification.csv')) {
+        if (file.exists("resultsDataModelSpecification.csv")) {
           res <- CohortGenerator::readCsv(
-            file = 'resultsDataModelSpecification.csv'
+            file = "resultsDataModelSpecification.csv"
           )
           return(res)
         }
         return(NULL)
       }
 
-      source('Main.R')
+      source("Main.R")
 
       jobContext <- readRDS(jobContextFileName)
       specifications <- getDataModelSpecifications(jobContext)
 
-      if (Sys.getenv('FORCE_RENV_USE', '') == 'TRUE') {
-        renv::use(lockfile = 'renv.lock')
+      if (Sys.getenv("FORCE_RENV_USE", "") == "TRUE") {
+        renv::use(lockfile = "renv.lock")
       }
 
-      ParallelLogger::addDefaultFileLogger(file.path(jobContext$moduleExecutionSettings$resultsSubFolder, 'log.txt'))
-      ParallelLogger::addDefaultErrorReportLogger(file.path(jobContext$moduleExecutionSettings$resultsSubFolder, 'errorReportR.txt'))
+      ParallelLogger::addDefaultFileLogger(file.path(jobContext$moduleExecutionSettings$resultsSubFolder, "log.txt"))
+      ParallelLogger::addDefaultErrorReportLogger(file.path(jobContext$moduleExecutionSettings$resultsSubFolder, "errorReportR.txt"))
       # Main.R can override default behaviour by implementing this function
       if (is.function(createDataModelSchema)) {
-
         # If the keyring is locked, unlock it, set the value and then re-lock it
         keyringName <- jobContext$keyringSettings$keyringName
         keyringLocked <- Strategus::unlockKeyring(keyringName = keyringName)
@@ -212,27 +212,27 @@ runSchemaCreation <- function(analysisSpecifications, keyringSettings, moduleInd
         if (keyringLocked) {
           keyring::keyring_lock(keyring = keyringName)
         }
-        writeLines('schema.created', doneFile)
+        writeLines("schema.created", doneFile)
       } else if (is.data.frame(specifications)) {
         # Export schema to readable location
         CohortGenerator::writeCsv(
           x = specifications,
           file = dataModelExportPath,
           warnOnCaseMismatch = FALSE
         )
-        writeLines('specifications.written', doneFile)
+        writeLines("specifications.written", doneFile)
       } else {
         warning("Module does not include data specifications file or createDataModelSchema function")
         CohortGenerator::writeCsv(
           x = specifications,
           file = dataModelExportPath,
           warnOnCaseMismatch = FALSE
         )
-        writeLines('specifications.not.written', doneFile)
+        writeLines("specifications.not.written", doneFile)
       }
 
-      ParallelLogger::unregisterLogger('DEFAULT_FILE_LOGGER', silent = TRUE)
-      ParallelLogger::unregisterLogger('DEFAULT_ERRORREPORT_LOGGER', silent = TRUE)
+      ParallelLogger::unregisterLogger("DEFAULT_FILE_LOGGER", silent = TRUE)
+      ParallelLogger::unregisterLogger("DEFAULT_ERRORREPORT_LOGGER", silent = TRUE)
     },
     moduleFolder = moduleFolder,
     tempScriptFile = file.path(moduleExecutionSettings$workSubFolder, "SchemaCreation.R"),
@@ -244,8 +244,8 @@ runSchemaCreation <- function(analysisSpecifications, keyringSettings, moduleInd
   )
 
   workStatus <- readLines(doneFile)
-  if (workStatus == 'specifications.written') {
-    moduleInfo <- ParallelLogger::loadSettingsFromJson(file.path(moduleFolder, 'MetaData.json'))
+  if (workStatus == "specifications.written") {
+    moduleInfo <- ParallelLogger::loadSettingsFromJson(file.path(moduleFolder, "MetaData.json"))
     keyringName <- jobContext$keyringSettings$keyringName
     keyringLocked <- Strategus::unlockKeyring(keyringName = keyringName)
 
@@ -258,14 +258,15 @@ runSchemaCreation <- function(analysisSpecifications, keyringSettings, moduleInd
 
     sql <- ResultModelManager::generateSqlSchema(csvFilepath = dataModelExportPath)
     DatabaseConnector::renderTranslateExecuteSql(connection,
-                                                 sql,
-                                                 table_prefix = moduleInfo$TablePrefix,
-                                                 database_schema = jobContext$moduleExecutionSettings$resultsDatabaseSchema)
+      sql,
+      table_prefix = moduleInfo$TablePrefix,
+      database_schema = jobContext$moduleExecutionSettings$resultsDatabaseSchema
+    )
 
     if (keyringLocked) {
       keyring::keyring_lock(keyring = keyringName)
     }
-  } else if (workStatus == 'schema.created')  {
+  } else if (workStatus == "schema.created") {
     message("Result schema creation handled inside module execution envrionment")
   } else {
     message("Schema not created for module")