v 1.0.0 documentation (#172)

* Update pkgdown site * WIP * Adding additional vignettes * Update nav and test build * Add link to resutls model docs * Add custom style for HADES logo * Further adjustments to documentation * Adjustments from jpg feedback * Fix GHA test failure * revise gha workflow --------- Co-authored-by: Anthony Sena <[email protected]>
OHDSI · Oct 7, 2024 · 8c5cbe8 · 8c5cbe8
1 parent fc2c9d1
commit 8c5cbe8
Show file tree

Hide file tree

Showing 66 changed files with 2,559 additions and 2,490 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,19 +1,18 @@
 Package: Strategus
 Type: Package
-Title: Coordinating and Executing Analytics Using HADES Modules
+Title: Coordinate and Execute OHDSI HADES Modules
 Version: 1.0.0
-Date: 2024-07-10
+Date: 2024-10-03
 Authors@R: c(
-	person("Martijn", "Schuemie", email = "[email protected]", role = c("aut")),
 	person("Anthony", "Sena", email = "[email protected]", role = c("aut", "cre")),
+	person("Martijn", "Schuemie", email = "[email protected]", role = c("aut")),
 	person("Jamie", "Gilbert", role = c("aut")),
 	person("Observational Health Data Science and Informatics", role = c("cph"))
   )
 Maintainer: Anthony Sena <[email protected]>
-Description: An R package for coordinating and executing analytics using HADES modules.
-License: Apache License 2.0
-URL: https://ohdsi.github.io/Strategus, https://github.com/OHDSI/Strategus, https://ohdsi.github.io/Strategus/
-BugReports: https://github.com/OHDSI/Strategus/issues
+Description: Coordinate and execute large scale analytics using OHDSI Health
+  Analytics Data-to-Evidence Suite (HADES) (<https://ohdsi.github.io/Hades/>) 
+  modules.
 Depends:
 	R (>= 4.2.0),
 	CohortGenerator (>= 0.11.0),
@@ -58,7 +57,10 @@ Remotes:
   ohdsi/PatientLevelPrediction,
   ohdsi/ResultModelManager,
   ohdsi/SelfControlledCaseSeries
+License: Apache License 2.0
 VignetteBuilder: knitr
+URL: https://ohdsi.github.io/Strategus, https://github.com/OHDSI/Strategus
+BugReports: https://github.com/OHDSI/Strategus/issues
 NeedsCompilation: no
 RoxygenNote: 7.3.2
 Roxygen: list(markdown = TRUE)

diff --git a/NAMESPACE b/NAMESPACE
@@ -26,7 +26,6 @@ export(createResultsDataModelSettings)
 export(createResultsExecutionSettings)
 export(execute)
 export(getCdmDatabaseMetaData)
-export(getDatabaseIdentifierFilePath)
 export(uploadResults)
 export(zipResults)
 import(CohortGenerator)

diff --git a/NEWS.md b/NEWS.md
@@ -1,3 +1,24 @@
+Strategus 1.0.0
+===============
+
+## Breaking Changes
+
+- Eliminated the dependencies for `keyring`, `renv` and `targets` (#135)
+- Centralized all modules into the Strategus package (#29, #45, #51, #140)
+- Strategus execution provides a summary of the execution time (#4) and continues after an error (#64, #141)
+- Modules provide functions for creating their results data model (#43) and to upload results.
+- Allow modules to obtain the full set of OMOP CDM metadata collected (#20, #154)
+- Adds the `cdm_holder` attribute to the database_id hash calculation (#48)
+- Moves the `incremental` setting to the execution settings vs. the module settings (#155)
+- Adds threading options via execution settings (#151)
+- Select subset of modules to execute from analysis specification (#169)
+- Ensure release of Strategus has Python dependencies (#22) and OHDSI Shiny App dependencies (#78). See [StrategusStudyRepoTemplate](https://github.com/ohdsi-studies/StrategusStudyRepoTemplate) for more details.
+- Document the results data model for HADES modules (#143)
+
+## Bug Fixes
+- Make negative control outcome shared resource optional (#153)
+- Export results data model specification file for PatientLevelPrediction (#165)
+
 Strategus 0.3.0
 ===============
 - Provide option to skip modules (#87)
@@ -60,7 +81,7 @@ Strategus 0.0.3
 - Breaking change: removed function `createExecutionSettings()` and replaced with 2 new functions: `createCdmExecutionSettings()` and `createResultsExecutionSettings()`. (#19)
 - Added Vignettes (#23)
 - Provide better support for `keyring` to handle named/locked keyrings (#24)
-- Add function to list Strategus modules (#30)
+- Add function to list HADES modules (#30)
 - Fixes from testing (#36)
 - Enforce module structure for proper use with renv (#37)
 - Support CDM 5.4 source table format (#41)

diff --git a/R/DatabaseMetaData.R b/R/DatabaseMetaData.R
@@ -31,7 +31,8 @@
 #' may be needed to purge old results for a given database identifier.
 #'
 #' @template resultsFolder
-#' @export
+#' @noRd
+#' @keywords internal
 getDatabaseIdentifierFilePath <- function(resultsFolder) {
   return(file.path(.getDatabaseMetaDataResultsFolder(resultsFolder), "database_meta_data.csv"))
 }

diff --git a/R/Module-Characterization.R b/R/Module-Characterization.R
@@ -1,9 +1,9 @@
 # CharacterizationModule -------------
-#' @title Module for generating cohort characterization information
+#' @title Characterize cohorts with the \href{https://ohdsi.github.io/Characterization/}{HADES Characterization Package}
 #' @export
 #' @description
-#' Computes cohort characterization information against the OMOP CDM
-#' package version 2.0.1
+#' Computes cohort characterization information against
+#' the OMOP Common Data Model
 CharacterizationModule <- R6::R6Class(
   classname = "CharacterizationModule",
   inherit = StrategusModule,

diff --git a/R/Module-CohortDiagnostics.R b/R/Module-CohortDiagnostics.R
@@ -1,8 +1,8 @@
 # CohortDiagnosticsModule -------------
-#' @title Module for the development and evaluation of phenotype algorithms
+#' @title Evaluate phenotypes with the \href{https://ohdsi.github.io/CohortDiagnostics/}{HADES CohortDiagnostics Package}
 #' @export
 #' @description
-#' Module for the development and evaluation of phenotype algorithms
+#' Development and evaluation of phenotype algorithms
 #' against the OMOP Common Data Model.
 CohortDiagnosticsModule <- R6::R6Class(
   classname = "CohortDiagnosticsModule",

diff --git a/R/Module-CohortGenerator.R b/R/Module-CohortGenerator.R
@@ -1,8 +1,8 @@
 # CohortGeneratorModule -------------
-#' @title Module for generating cohorts against an OMOP CDM
+#' @title Generate cohorts with the \href{https://ohdsi.github.io/CohortGenerator/}{HADES CohortGenerator Package}
 #' @export
 #' @description
-#' Generates cohorts against the OMOP CDM
+#' Generates cohorts against the OMOP Common Data Model
 CohortGeneratorModule <- R6::R6Class(
   classname = "CohortGeneratorModule",
   inherit = StrategusModule,

diff --git a/R/Module-CohortIncidence.R b/R/Module-CohortIncidence.R
@@ -1,8 +1,8 @@
 # CohortIncidenceModule -------------
-#' @title Module for computing incidence rates for cohorts against an OMOP CDM
+#' @title Compute incidence with the \href{https://ohdsi.github.io/CohortIncidence/}{HADES CohortIncidence Package}
 #' @export
 #' @description
-#' Computes incidence rates for cohorts against the OMOP CDM
+#' Computes incidence rates for cohorts against the OMOP Common Data Model
 CohortIncidenceModule <- R6::R6Class(
   classname = "CohortIncidenceModule",
   inherit = StrategusModule,
@@ -141,12 +141,7 @@ CohortIncidenceModule <- R6::R6Class(
       super$uploadResults(resultsConnectionDetails, analysisSpecifications, resultsDataModelSettings)
       resultsFolder <- private$jobContext$moduleExecutionSettings$resultsSubFolder
       exportFolder <- private$jobContext$moduleExecutionSettings$resultsSubFolder
-
-      # use the results model spec that was saved along with the results output, not the embedded model spec.
-      resultsModelSpec <- readr::read_csv(
-        file = file.path(file.path(exportFolder, "resultsDataModelSpecification.csv")),
-        show_col_types = FALSE
-      )
+      resultsModelSpec <- self$getResultsDataModelSpecification()
 
       ResultModelManager::uploadResults(
         connectionDetails = resultsConnectionDetails,

diff --git a/R/Module-CohortMethod.R b/R/Module-CohortMethod.R
@@ -1,9 +1,9 @@
 # CohortMethodModule -------------
-#' @title Module for performing new-user cohort studies
+#' @title New-user cohort studies with the \href{https://ohdsi.github.io/CohortMethod/}{HADES CohortMethod Package}
 #' @export
 #' @description
-#' Module for performing new-user cohort studies in an observational
-#' database in the OMOP Common Data Model.
+#' Module for performing new-user cohort studies against
+#' the OMOP Common Data Model
 CohortMethodModule <- R6::R6Class(
   classname = "CohortMethodModule",
   inherit = StrategusModule,

diff --git a/R/Module-EvidenceSynthesis.R b/R/Module-EvidenceSynthesis.R
@@ -1,7 +1,5 @@
 # EvidenceSynthesisModule -------------
-#' @title Module for for combining causal effect estimates and study diagnostics
-#' across multiple data sites in a distributed study. This includes functions
-#' for performing meta-analysis and forest plots
+#' @title Meta-analysis with the \href{https://ohdsi.github.io/EvidenceSynthesis/}{HADES EvidenceSynthesis Package}
 #' @export
 #' @description
 #' Module for for combining causal effect estimates and study diagnostics

diff --git a/R/Module-PatientLevelPrediction.R b/R/Module-PatientLevelPrediction.R
@@ -1,5 +1,5 @@
 # PatientLevelPredictionModule -------------
-#' @title Module for performing patient-level prediction studies
+#' @title Patient-level prediction with the \href{https://ohdsi.github.io/PatientLevelPrediction/}{HADES PatientLevelPrediction Package}
 #' @export
 #' @description
 #' Module for performing patient-level prediction in an observational
@@ -135,7 +135,7 @@ PatientLevelPredictionModule <- R6::R6Class(
       )
     },
     #' @description Creates the PatientLevelprediction Module Specifications
-    #' @param modelDesignList description
+    #' @param modelDesignList A list of model designs created using \code{PatientLevelPrediction::createModelDesign()}
     createModuleSpecifications = function(modelDesignList) {
       analysis <- list()
       for (name in names(formals(self$createModuleSpecifications))) {

diff --git a/R/Module-SelfControlledCaseSeries.R b/R/Module-SelfControlledCaseSeries.R
@@ -1,10 +1,9 @@
 # SelfControlledCaseSeriesModule -------------
-#' @title Module for performing Self-Controlled Case Series (SCCS) analyses
-#' in an observational database in the OMOP Common Data Model.
+#' @title Self-Controlled Case Series design with the \href{https://ohdsi.github.io/SelfControlledCaseSeries/}{HADES SelfControlledCaseSeries Package}
 #' @export
 #' @description
 #' Module for performing Self-Controlled Case Series (SCCS) analyses
-#' in an observational database in the OMOP Common Data Model.
+#' against the OMOP Common Data Model.
 SelfControlledCaseSeriesModule <- R6::R6Class(
   classname = "SelfControlledCaseSeriesModule",
   inherit = StrategusModule,

diff --git a/R/Settings.R b/R/Settings.R
@@ -21,7 +21,7 @@
 # carefully consider serialization and deserialization to JSON, which currently
 # uses custom functionality in ParallelLogger to maintain object attributes.
 
-#' Add shared resources to analysis specifications
+#' Add shared resources (i.e. cohorts) to analysis specifications
 #'
 #' @template analysisSpecifications
 #' @param sharedResources   An object of type `SharedResources`.
@@ -40,7 +40,7 @@ addSharedResources <- function(analysisSpecifications, sharedResources) {
   return(analysisSpecifications)
 }
 
-#' Add module specifications to analysis specifications
+#' Add generic module specifications to analysis specifications
 #'
 #' @template analysisSpecifications
 #' @template moduleSpecifications
@@ -62,7 +62,7 @@ addModuleSpecifications <- function(analysisSpecifications, moduleSpecifications
 #' Add Characterization module specifications to analysis specifications
 #'
 #' @template analysisSpecifications
-#' @param moduleSpecifications   An object of type `CharacterizationModule`.
+#' @param moduleSpecifications   Created by the \href{../../docs/reference/CharacterizationModule.html#method-CharacterizationModule-createModuleSpecifications}{\code{CharacterizationModule$createModuleSpecifications()}} function.
 #'
 #' @return
 #' Returns the `analysisSpecifications` object with the module specifications added.
@@ -81,7 +81,7 @@ addCharacterizationModuleSpecifications <- function(analysisSpecifications, modu
 #' Add Cohort Diagnostics module specifications to analysis specifications
 #'
 #' @template analysisSpecifications
-#' @param moduleSpecifications   An object of type `CohortDiagnosticsModule`.
+#' @param moduleSpecifications  Created by the \href{../../docs/reference/CohortDiagnosticsModule.html#method-CohortDiagnosticsModule-createModuleSpecifications}{\code{CohortDiagnosticsModule$createModuleSpecifications()}} function.
 #'
 #' @return
 #' Returns the `analysisSpecifications` object with the module specifications added.
@@ -100,7 +100,7 @@ addCohortDiagnosticsModuleSpecifications <- function(analysisSpecifications, mod
 #' Add Cohort Generator module specifications to analysis specifications
 #'
 #' @template analysisSpecifications
-#' @param moduleSpecifications   An object of type `CohortGeneratorModule`.
+#' @param moduleSpecifications  Created by the \href{../../docs/reference/CohortGeneratorModule.html#method-CohortGeneratorModule-createModuleSpecifications}{\code{CohortGeneratorModule$createModuleSpecifications()}} function.
 #'
 #' @return
 #' Returns the `analysisSpecifications` object with the module specifications added.
@@ -119,7 +119,7 @@ addCohortGeneratorModuleSpecifications <- function(analysisSpecifications, modul
 #' Add Cohort Incidence module specifications to analysis specifications
 #'
 #' @template analysisSpecifications
-#' @param moduleSpecifications   An object of type `CohortIncidenceModule`.
+#' @param moduleSpecifications  Created by the \href{../../docs/reference/CohortIncidenceModule.html#method-CohortIncidenceModule-createModuleSpecifications}{\code{CohortIncidenceModule$createModuleSpecifications()}} function.
 #'
 #' @return
 #' Returns the `analysisSpecifications` object with the module specifications added.
@@ -138,7 +138,7 @@ addCohortIncidenceModuleSpecifications <- function(analysisSpecifications, modul
 #' Add Cohort Method module specifications to analysis specifications
 #'
 #' @template analysisSpecifications
-#' @param moduleSpecifications   An object of type `CohortMethodModule`.
+#' @param moduleSpecifications  Created by the \href{../../docs/reference/CohortMethodModule.html#method-CohortMethodModule-createModuleSpecifications}{\code{CohortMethodModule$createModuleSpecifications()}} function.
 #'
 #' @return
 #' Returns the `analysisSpecifications` object with the module specifications added.
@@ -157,7 +157,7 @@ addCohortMethodeModuleSpecifications <- function(analysisSpecifications, moduleS
 #' Add Evidence Synthesis module specifications to analysis specifications
 #'
 #' @template analysisSpecifications
-#' @param moduleSpecifications   An object of type `EvidenceSynthesisModule`.
+#' @param moduleSpecifications  Created by the \href{../../docs/reference/EvidenceSynthesisModule.html#method-EvidenceSynthesisModule-createModuleSpecifications}{\code{EvidenceSynthesisModule$createModuleSpecifications()}} function.
 #'
 #' @return
 #' Returns the `analysisSpecifications` object with the module specifications added.
@@ -176,7 +176,7 @@ addEvidenceSynthesisModuleSpecifications <- function(analysisSpecifications, mod
 #' Add Patient Level Prediction module specifications to analysis specifications
 #'
 #' @template analysisSpecifications
-#' @param moduleSpecifications   An object of type `PatientLevelPredictionModule`.
+#' @param moduleSpecifications  Created by the \href{../../docs/reference/PatientLevelPredictionModule.html#method-PatientLevelPredictionModule-createModuleSpecifications}{\code{PatientLevelPredictionModule$createModuleSpecifications()}} function.
 #'
 #' @return
 #' Returns the `analysisSpecifications` object with the module specifications added.
@@ -195,7 +195,7 @@ addPatientLevelPredictionModuleSpecifications <- function(analysisSpecifications
 #' Add Self Controlled Case Series Module module specifications to analysis specifications
 #'
 #' @template analysisSpecifications
-#' @param moduleSpecifications   An object of type `SelfControlledCaseSeriesModule`.
+#' @param moduleSpecifications  Created by the \href{../../docs/reference/SelfControlledCaseSeriesModule.html#method-SelfControlledCaseSeriesModule-createModuleSpecifications}{\code{SelfControlledCaseSeriesModule$createModuleSpecifications()}} function.
 #'
 #' @return
 #' Returns the `analysisSpecifications` object with the module specifications added.

diff --git a/R/StrategusModule.R b/R/StrategusModule.R
@@ -4,6 +4,8 @@
 #' @description
 #' This is an internal class used by the StrategusModule (and child classes)
 #' execute function
+#' @noRd
+#' @keywords internal
 JobContext <- R6::R6Class(
   classname = "JobContext",
   public = list(
@@ -19,10 +21,13 @@ JobContext <- R6::R6Class(
 )
 
 # StrategusModule -------------
-#' @title StrategusModule defines the base class for each HADES Strategus module
+#' @title StrategusModule defines the base class for each HADES module
 #' @export
 #' @description
-#' Provides a base class for HADES Strategus modules to inherit
+#' StrategusModule serves as an internal base class that defines the core
+#' functions and structure to be inherited and implemented by any specific
+#' HADES module. It provides a standardized framework for creating modular
+#' components within the Strategus pipeline.
 StrategusModule <- R6::R6Class(
   classname = "StrategusModule",
   public = list(

diff --git a/README.md b/README.md
@@ -4,16 +4,15 @@ Strategus
 [![Build Status](https://github.com/OHDSI/Strategus/actions/workflows/R_CMD_check_Hades.yaml/badge.svg?branch=main)](https://github.com/OHDSI/Strategus/actions/workflows/R_CMD_check_Hades.yaml/badge.svg?branch=main)
 [![codecov.io](https://codecov.io/github/OHDSI/Strategus/coverage.svg?branch=main)](https://codecov.io/github/OHDSI/Strategus?branch=main)
 
-
 Introduction
 ============
-Strategus is an R package for coordinating and executing analytics using HADES modules. Please see the [Introduction To Strategus](https://ohdsi.github.io/Strategus/articles/IntroductionToStrategus.html) for more details.
+Strategus is an R package for coordinating and executing analytics using [OHDSI HADES](https://ohdsi.github.io/Hades/) modules. Please see the [Introduction To Strategus](https://ohdsi.github.io/Strategus/articles/IntroductionToStrategus.html) for more details.
 
 Features
 ========
 - Design study analysis specifications
 - Execute study analysis specifications against the OMOP CDM
-- Modular design for encapsulating analytics [vignette](https://ohdsi.github.io/Strategus/articles/CreatingModules.html)
+- Upload and review study results
 
 Technology
 ============
@@ -33,23 +32,13 @@ Installation
   install.packages("remotes")
   remotes::install_github("ohdsi/Strategus")
   ```
-3. If using Linux, please refer to the [keyring Linux secret service setup](https://r-lib.github.io/keyring/index.html#linux) as this is required to execute studies using Strategus. In addition to those instructions, members of the OHDSI community have shared the following guidance:
-
-Run in a terminal the following before installing keyring:
-
-```bash
-sudo yum install libsodium libsodium-devel
-sudo yum install libsecret libsecret-devel
-sudo chmod 777 /home/idies/.config 
-```
-
 User Documentation
 ==================
 Documentation can be found on the [package website](https://ohdsi.github.io/Strategus).
 
 PDF versions of the documentation are also available:
-* Package manual: [Strategus.pdf](https://raw.githubusercontent.com/OHDSI/Strategus/main/extras/Strategus.pdf)
-* Vignette: [Creating Strategus Modules](https://github.com/OHDSI/Strategus/raw/main/inst/doc/CreatingModules.pdf)
+- Package manual: [Strategus.pdf](https://raw.githubusercontent.com/OHDSI/Strategus/main/extras/Strategus.pdf)
+- Vignette: [Creating HADES Modules](https://github.com/OHDSI/Strategus/raw/main/inst/doc/CreatingModules.pdf)
 
 Support
 =======

diff --git a/Strategus.Rproj b/Strategus.Rproj
@@ -16,6 +16,7 @@ AutoAppendNewline: Yes
 StripTrailingWhitespace: Yes
 
 BuildType: Package
+PackageUseDevtools: Yes
 PackageInstallArgs: --no-multiarch --with-keep.source
 PackageBuildArgs: --resave-data
 PackageCheckArgs: --no-manual --no-build-vignettes