Document results data model for modules (#167)

* Add functions to expose rdms for each module and test
* Create full data model SQL

.Rbuildignore

@@ -11,3 +11,7 @@ compare_versions
 .github
 docs
 .idea
+^_pkgdown\.yml$
+^docs$
+^pkgdown$
+^\.github$

.github/.gitignore

@@ -0,0 +1 @@
+*.html

.github/workflows/pkgdown.yaml

@@ -0,0 +1,104 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+name: pkgdown.yaml
+
+permissions: read-all
+
+jobs:
+  pkgdown:
+    runs-on: ubuntu-latest
+    # Only restrict concurrency for non-PR jobs
+    concurrency:
+      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
+    services:
+      postgres:
+        image: postgres:latest
+        env:
+          POSTGRES_DB: strategus
+          POSTGRES_USER: user
+          POSTGRES_PASSWORD: password
+          POSTGRES_HOST: postgres
+          POSTGRES_PORT: 5432
+        ports:
+          - 5432:5432
+        options: --name postgres --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Setup Pandoc
+      uses: r-lib/actions/setup-pandoc@v2
+
+    - name: Setup R
+      uses: r-lib/actions/setup-r@v2
+      with:
+        use-public-rspm: true
+
+    - name: Setup R Dependencies
+      uses: r-lib/actions/setup-r-dependencies@v2
+      with:
+        extra-packages: any::pkgdown, local::.
+        needs: website
+
+    - name: Build site
+      run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+      shell: Rscript {0}
+
+    - name: Wait for PostgreSQL to be ready
+      run: |
+        until pg_isready -h 127.0.0.1 -p 5432 -U myuser; do
+          echo "Waiting for postgres...";
+          sleep 3;
+        done
+
+    - name: Run SQL Script
+      run: |
+        PGPASSWORD=password psql -h 127.0.0.1 -U user -d strategus -f extras/rdms/full_data_model_pg.sql
+
+    - name: Configure SchemaSpy environment
+      run: |
+        sudo apt-get update
+        sudo apt-get install default-jdk -y
+        sudo apt-get install postgresql-client -y
+
+    - name: Download PostgreSQL JDBC Driver
+      run: |
+        wget https://jdbc.postgresql.org/download/postgresql-42.2.24.jar -O $HOME/postgresql-jdbc.jar
+
+    - name: Execute SchemaSpy
+      run: |
+        java -jar extras/rdms/schemaspy-6.2.4.jar -vizjs -dp $HOME -configFile extras/rdms/schemaspy-config.properties -meta extras/rdms/schema_meta.xml -debug -desc "Results data model" -noTablePaging -noimplied
+
+    - name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+       name: documentation-artifact
+       path: public
+
+    - name: download documentation
+      uses: actions/download-artifact@v4
+      with:
+        name: documentation-artifact
+        path: docs/results-schema
+
+    - name: Deploy to GitHub pages 🚀
+      if: github.event_name != 'pull_request'
+      uses: JamesIves/[email protected]
+      with:
+        clean: false
+        branch: gh-pages
+        folder: docs

.gitignore

@@ -19,3 +19,7 @@ src/*.dll
 /Debug
 standalone/build/*
 _targets
+docs
+
+extras/rdms/public
+extras/rdms/*.class

DESCRIPTION

@@ -12,7 +12,7 @@ Authors@R: c(
 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
+URL: https://ohdsi.github.io/Strategus, https://github.com/OHDSI/Strategus, https://ohdsi.github.io/Strategus/
 BugReports: https://github.com/OHDSI/Strategus/issues
 Depends:
 	R (>= 4.2.0),

R/Module-Characterization.R

@@ -45,19 +45,10 @@ CharacterizationModule <- R6::R6Class(
       )
 
       # Export the resultsDataModelSpecification.csv
-      resultsDataModel <- CohortGenerator::readCsv(
-        file = system.file(
-          "settings/resultsDataModelSpecification.csv",
-          package = "Characterization"
-        ),
-        warnOnCaseMismatch = FALSE
-      )
-
-      # add the prefix to the tableName column
-      resultsDataModel$tableName <- paste0(self$tablePrefix, resultsDataModel$tableName)
+      resultsDataModelSpecification <- self$getResultsDataModelSpecification()
 
       CohortGenerator::writeCsv(
-        x = resultsDataModel,
+        x = resultsDataModelSpecification,
         file = file.path(resultsFolder, "resultsDataModelSpecification.csv"),
         warnOnCaseMismatch = FALSE,
         warnOnFileNameCaseMismatch = FALSE,
@@ -81,6 +72,21 @@ CharacterizationModule <- R6::R6Class(
         tablePrefix = tablePrefix
           )
     },
+    #' @description Get the results data model specification for the module
+    #' @template tablePrefix
+    getResultsDataModelSpecification = function(tablePrefix = "") {
+      resultsDataModelSpecification <- CohortGenerator::readCsv(
+        file = system.file(
+          file.path("settings", "resultsDataModelSpecification.csv"),
+          package = "Characterization"
+        ),
+        warnOnCaseMismatch = FALSE
+      )
+
+      # add the prefix to the tableName column
+      resultsDataModelSpecification$tableName <- paste0(tablePrefix, self$tablePrefix, resultsDataModelSpecification$tableName)
+      return(resultsDataModelSpecification)
+    },
     #' @description Upload the results for the module
     #' @template resultsConnectionDetails
     #' @template analysisSpecifications

R/Module-CohortDiagnostics.R

@@ -42,19 +42,18 @@ CohortDiagnosticsModule <- R6::R6Class(
       # TODO: Removing this to make the upload easier
       # unlink(file.path(exportFolder, sprintf("Results_%s.zip", jobContext$moduleExecutionSettings$cdmDatabaseMetaData$databaseId)))
 
-      resultsDataModel <- CohortGenerator::readCsv(
-        file = system.file("settings", "resultsDataModelSpecification.csv", package = "CohortDiagnostics"),
-        warnOnCaseMismatch = FALSE
-      )
-      resultsDataModel <- resultsDataModel[file.exists(file.path(exportFolder, paste0(resultsDataModel$tableName, ".csv"))), ]
-      newTableNames <- paste0(self$tablePrefix, resultsDataModel$tableName)
+      # NOTE: CD exports data without the table prefix and this section
+      # will manipulate the files to include the table prefix
+      resultsDataModelSpecification <- private$.getResultsDataModelSpecification()
+      resultsDataModelSpecification <- resultsDataModelSpecification[file.exists(file.path(exportFolder, paste0(resultsDataModelSpecification$tableName, ".csv"))), ]
+      newTableNames <- paste0(self$tablePrefix, resultsDataModelSpecification$tableName)
       file.rename(
-        file.path(exportFolder, paste0(unique(resultsDataModel$tableName), ".csv")),
+        file.path(exportFolder, paste0(unique(resultsDataModelSpecification$tableName), ".csv")),
         file.path(exportFolder, paste0(unique(newTableNames), ".csv"))
       )
-      resultsDataModel$tableName <- newTableNames
+      resultsDataModelSpecification$tableName <- newTableNames
       CohortGenerator::writeCsv(
-        x = resultsDataModel,
+        x = resultsDataModelSpecification,
         file.path(exportFolder, "resultsDataModelSpecification.csv"),
         warnOnFileNameCaseMismatch = FALSE
       )
@@ -73,6 +72,14 @@ CohortDiagnosticsModule <- R6::R6Class(
         tablePrefix = tablePrefix
       )
     },
+    #' @description Get the results data model specification for the module
+    #' @template tablePrefix
+    getResultsDataModelSpecification = function(tablePrefix = "") {
+      resultsDataModelSpecification <- private$.getResultsDataModelSpecification()
+      # add the prefix to the tableName column
+      resultsDataModelSpecification$tableName <- paste0(tablePrefix, self$tablePrefix, resultsDataModelSpecification$tableName)
+      return(resultsDataModelSpecification)
+    },
     #' @description Upload the results for the module
     #' @template resultsConnectionDetails
     #' @template analysisSpecifications
@@ -207,6 +214,16 @@ CohortDiagnosticsModule <- R6::R6Class(
       }
         '
       ParallelLogger::convertJsonToSettings(covariateSettings)
+    },
+    .getResultsDataModelSpecification = function() {
+      resultsDataModelSpecification <- CohortGenerator::readCsv(
+        file = system.file(
+          file.path("settings", "resultsDataModelSpecification.csv"),
+          package = "CohortDiagnostics"
+        ),
+        warnOnCaseMismatch = FALSE
+      )
+      return(resultsDataModelSpecification)
     }
   )
 )

R/Module-CohortGenerator.R

@@ -67,6 +67,21 @@ CohortGeneratorModule <- R6::R6Class(
         tablePrefix = tablePrefix
       )
     },
+    #' @description Get the results data model specification for the module
+    #' @template tablePrefix
+    getResultsDataModelSpecification = function(tablePrefix = "") {
+      resultsDataModelSpecification <- CohortGenerator::readCsv(
+        file = system.file(
+          file.path("csv", "resultsDataModelSpecification.csv"),
+          package = "CohortGenerator"
+        ),
+        warnOnCaseMismatch = FALSE
+      )
+
+      # add the prefix to the tableName column
+      resultsDataModelSpecification$tableName <- paste0(tablePrefix, resultsDataModelSpecification$tableName)
+      return(resultsDataModelSpecification)
+    },
     #' @description Upload the results for the module
     #' @template resultsConnectionDetails
     #' @template analysisSpecifications

R/Module-CohortIncidence.R

@@ -95,8 +95,12 @@ CohortIncidenceModule <- R6::R6Class(
       target_outcome_ref$ref_id <- refId
       readr::write_csv(target_outcome_ref, file.path(exportFolder, paste0(self$tablePrefix,"target_outcome_ref",".csv")))
 
-      resultsDataModel <- private$.getResultsDataModelSpecification()
-      readr::write_csv(resultsDataModel, file.path(exportFolder, "resultsDataModelSpecification.csv"))
+      resultsDataModelSpecification <- self$getResultsDataModelSpecification()
+      CohortGenerator::writeCsv(
+        x = resultsDataModelSpecification,
+        file.path(exportFolder, "resultsDataModelSpecification.csv"),
+        warnOnFileNameCaseMismatch = FALSE
+      )
 
       private$.message(paste("Results available at:", resultsFolder))
     },
@@ -114,11 +118,21 @@ CohortIncidenceModule <- R6::R6Class(
       on.exit(DatabaseConnector::disconnect(connection))
 
       # Create the results model
-      sql <- ResultModelManager::generateSqlSchema(schemaDefinition = private$.getResultsDataModelSpecification())
+      sql <- ResultModelManager::generateSqlSchema(schemaDefinition = self$getResultsDataModelSpecification())
       sql <- SqlRender::render(sql= sql, warnOnMissingParameters = TRUE, database_schema = resultsDatabaseSchema)
       sql <- SqlRender::translate(sql = sql, targetDialect = resultsConnectionDetails$dbms)
       DatabaseConnector::executeSql(connection, sql)
     },
+    #' @description Get the results data model specification for the module
+    #' @template tablePrefix
+    getResultsDataModelSpecification = function(tablePrefix = "") {
+      resultsDataModelSpecification <- CohortGenerator::readCsv(
+        file = private$.getResultsDataModelSpecificationFileLocation(),
+        warnOnCaseMismatch = FALSE
+      )
+      resultsDataModelSpecification$tableName <-paste0(tablePrefix, self$tablePrefix, resultsDataModelSpecification$tableName)
+      return(resultsDataModelSpecification)
+    },
     #' @description Upload the results for the module
     #' @template resultsConnectionDetails
     #' @template analysisSpecifications
@@ -197,14 +211,6 @@ CohortIncidenceModule <- R6::R6Class(
 
       return(data)
     },
-    .getResultsDataModelSpecification = function() {
-      rdms <- CohortGenerator::readCsv(
-        file = private$.getResultsDataModelSpecificationFileLocation(),
-        warnOnCaseMismatch = FALSE
-      )
-      rdms$tableName <-paste0(self$tablePrefix, rdms$tableName)
-      return(rdms)
-    },
     .getResultsDataModelSpecificationFileLocation = function() {
       return(system.file(
         file.path("csv", "cohortIncidenceRdms.csv"),

R/Module-CohortMethod.R

@@ -47,9 +47,9 @@ CohortMethodModule <- R6::R6Class(
       # TODO: Removing this to make the upload easier
       #unlink(file.path(exportFolder, sprintf("Results_%s.zip", jobContext$moduleExecutionSettings$cdmDatabaseMetaData$databaseId)))
 
-      resultsDataModel <- CohortGenerator::readCsv(file = system.file("csv", "resultsDataModelSpecification.csv", package = "CohortMethod"))
+      resultsDataModelSpecification <- self$getResultsDataModelSpecification()
       CohortGenerator::writeCsv(
-        x = resultsDataModel,
+        x = resultsDataModelSpecification,
         file = file.path(exportFolder, "resultsDataModelSpecification.csv"),
         warnOnFileNameCaseMismatch = FALSE
       )
@@ -67,6 +67,21 @@ CohortMethodModule <- R6::R6Class(
         tablePrefix = tablePrefix
       )
     },
+    #' @description Get the results data model specification for the module
+    #' @template tablePrefix
+    getResultsDataModelSpecification = function(tablePrefix = "") {
+      resultsDataModelSpecification <- CohortGenerator::readCsv(
+        file = system.file(
+          file.path("csv", "resultsDataModelSpecification.csv"),
+          package = "CohortMethod"
+        ),
+        warnOnCaseMismatch = FALSE
+      )
+
+      # add the prefix to the tableName column
+      resultsDataModelSpecification$tableName <- paste0(tablePrefix, resultsDataModelSpecification$tableName)
+      return(resultsDataModelSpecification)
+    },
     #' @description Upload the results for the module
     #' @template resultsConnectionDetails
     #' @template analysisSpecifications

R/Module-EvidenceSynthesis.R

@@ -72,6 +72,18 @@ EvidenceSynthesisModule <- R6::R6Class(
       sql <- SqlRender::translate(sql = sql, targetDialect = resultsConnectionDetails$dbms)
       DatabaseConnector::executeSql(connection, sql)
     },
+    #' @description Get the results data model specification for the module
+    #' @template tablePrefix
+    getResultsDataModelSpecification = function(tablePrefix = "") {
+      resultsDataModelSpecification <- CohortGenerator::readCsv(
+        file = private$.getResultsDataModelSpecificationFileLocation(),
+        warnOnCaseMismatch = FALSE
+      )
+
+      # add the prefix to the tableName column
+      resultsDataModelSpecification$tableName <- paste0(tablePrefix, resultsDataModelSpecification$tableName)
+      return(resultsDataModelSpecification)
+    },
     #' @description Upload the results for the module
     #' @template resultsConnectionDetails
     #' @template analysisSpecifications