CohortDiagnostics

https://ohdsi.github.io/CohortDiagnostics
Admin
CohortDiagnostics is an R utility package for developing and evaluating phenotype algorithms on OMOP...
Tokens:17,819
Snippets:189
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Hydra from GitHub

Source: https://ohdsi.github.io/CohortDiagnostics/articles/CreatingAStudyPackage.html

Ensures you have the latest version of Hydra, which is necessary for Cohort Diagnostics support. This command installs the 'develop' branch.

```r
remotes::install_github("OHDSI/Hydra", ref = "develop")
```

--------------------------------

### Install CohortDiagnostics Package

Source: https://ohdsi.github.io/CohortDiagnostics/index.html

Use this command to download and install the CohortDiagnostics package from GitHub. Ensure your R environment is configured, including Java, before installation.

```r
remotes::install_github("OHDSI/CohortDiagnostics")
```

--------------------------------

### Install CohortDiagnostics Dependencies

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Installs the CohortDiagnostics package and the Eunomia test package. Optionally installs ROhdsiWebApi for loading cohort definitions from ATLAS.

```r
remotes::install_github("OHDSI/Eunomia")
remotes::install_github("OHDSI/ROhdsiWebApi")
```

--------------------------------

### Example YAML Configuration for PostgreSQL

Source: https://ohdsi.github.io/CohortDiagnostics/articles/DatabaseModeInDiagnosticsExplorer.html

This YAML configuration specifies connection details for a PostgreSQL database, including server address, user credentials, port, and schema information. It is used to configure the Diagnostics Explorer application for remote database access.

```yaml
# Alter these configuration settings for usage with remote databases
connectionDetails:
  dbms: "postgresql"
  server: "my-database-server.com/myDatabaseName"
  user: "postrgres"
  password: "secret_password"
  port: 5432

# Store connection details as a json string in keyring
# Store with keyring::key_set_with_value("KEYNAME", jsonlite::toJSON(myConnectionDetails))
connectionDetailsSecureKey: ~

# If you used a table prefix to store the results (e.g. cd_)
tablePrefix: ""

# Results schema being used
resultsDatabaseSchema: "cohort_diagnostics"

# Vocabulary schemas. Should include the reuslts schema and optional custom vocabularies
vocabularyDatabaseSchemas: ["cohort_diagnostics"]

# Custom table name for cohorts and cdm databases (probably not needed, ignores table prefix)
cohortTableName: "cohort"
databaseTableName: "database"

# If you wish to enable annotation - not currently reccomended in multi-user environments
enableAnnotation: FALSE
enableAuthorization: FALSE
```

--------------------------------

### Study Package Specification Example

Source: https://ohdsi.github.io/CohortDiagnostics/articles/CreatingAStudyPackage.html

This JSON file serves as the input for Hydra, a tool used in creating skeleton cohort diagnostics study packages. Ensure you are using Hydra version 0.3 or later.

```json
{
  "studyName": "My Study Name",
  "description": "A description of my study.",
  "வுகள்": [
    {
      "id": 1,
      "name": "Cohort 1",
      "sql": "SELECT * FROM cohort WHERE cohort_definition_id = 1;"
    },
    {
      "id": 2,
      "name": "Cohort 2",
      "sql": "SELECT * FROM cohort WHERE cohort_definition_id = 2;"
    }
  ],
  "settings": {
    "connectionDetails": {
      "dbms": "postgresql",
      "server": "your_server",
      "user": "your_user",
      "password": "your_password",
      "database": "your_database"
    },
    "outputFolder": "results"
  }
}
```

--------------------------------

### Install OHDSI Shiny Modules

Source: https://ohdsi.github.io/CohortDiagnostics/articles/ViewingResultsUsingDiagnosticsExplorer.html

Updates the OHDSI Shiny modules to the latest version, which is recommended before publishing the Shiny app. This ensures all dependencies are up-to-date.

```r
remotes::install_packages('OHDSI/OhdsiShinyModules')
```

--------------------------------

### Get Data Migrator Instance

Source: https://ohdsi.github.io/CohortDiagnostics/reference/getDataMigrator.html

Call this function to get an instance of DataMigrationManager. Ensure you have provided the necessary connection details and database schema.

```r
getDataMigrator(connectionDetails, databaseSchema, tablePrefix = "")
```

--------------------------------

### Get Results Data Model Specifications

Source: https://ohdsi.github.io/CohortDiagnostics/reference/getResultsDataModelSpecifications.html

Call this function to retrieve the data model specifications as a tibble data frame. No arguments are required.

```r
getResultsDataModelSpecifications()
```

--------------------------------

### Get Default Vocabulary Table Names in R

Source: https://ohdsi.github.io/CohortDiagnostics/reference/getDefaultVocabularyTableNames.html

Call this function to retrieve a list of the default vocabulary table names. This is useful for understanding the expected schema or for programmatic access to these tables.

```r
getDefaultVocabularyTableNames()
```

--------------------------------

### Get Default Covariate Settings

Source: https://ohdsi.github.io/CohortDiagnostics/reference/getDefaultCovariateSettings.html

Call this function to retrieve the default covariate settings. Note that specific time windows are mandatory for other diagnostics and will always be included.

```r
getDefaultCovariateSettings()
```

--------------------------------

### Get Cohort Counts Function Signature

Source: https://ohdsi.github.io/CohortDiagnostics/reference/getCohortCounts.html

This is the usage signature for the `getCohortCounts` function. It outlines the parameters required to compute cohort counts, including connection details, database schema, and cohort table information.

```r
getCohortCounts(
  connectionDetails = NULL,
  connection = NULL,
  cohortDatabaseSchema,
  cohortTable = "cohort",
  cohortIds = c()
)
```

--------------------------------

### Configure PostgreSQL Connection Details

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Sets up connection details for a PostgreSQL database. Ensure to replace placeholder values with your actual server, user, and password.

```r
library(CohortDiagnostics)

connectionDetails <- createConnectionDetails(
  dbms = "postgresql",
  server = "localhost/ohdsi",
  user = "joe",
  password = "supersecret"
)
```

--------------------------------

### Create Temporary Directory and Generate Study Specifications

Source: https://ohdsi.github.io/CohortDiagnostics/articles/CreatingAStudyPackage.html

Sets up a temporary directory to store the study package files and then creates a JSON file containing the compiled study specifications.

```r
tempFolder <- tempdir()
unlink(x = tempFolder, recursive = TRUE, force = TRUE)
dir.create(path = tempFolder, showWarnings = FALSE, recursive = TRUE)

specifications <- list(
  id = 1,
  version = version,
  name = name,
  packageName = packageName,
  skeletonVersion = skeletonVersion,
  createdBy = createdBy,
  createdDate = createdDate,
  modifiedBy = modifiedBy,
  modifiedDate = modifiedDate,
  skeletonType = skeletonType,
  organizationName = organizationName,
  description = description,
  cohortDefinitions = cohortDefinitionsArray
)

jsonFileName <- paste0(file.path(tempFolder, "CohortDiagnosticsSpecs.json"))
write(x = specifications %>% RJSONIO::toJSON(pretty = TRUE, digits = 23), file = jsonFileName)
```

--------------------------------

### Launch Diagnostics Explorer for Publishing

Source: https://ohdsi.github.io/CohortDiagnostics/articles/ViewingResultsUsingDiagnosticsExplorer.html

Launches the Diagnostics Explorer application with options to create a publishable version. This generates a folder containing the app and its dependencies, ready for deployment. It allows overwriting an existing publish directory and includes the SQLite results file.

```r
launchDiagnosticsExplorer(
  sqliteDbPath = "MyCohortDiagnosticsResulst.sqlite",
  makePublishable = TRUE,
  publishDir = file.path(getwd(), "MyStudyDiagnosticsExplorer"),
  overwritePublishDir = TRUE
)
```

--------------------------------

### Launch Diagnostics Explorer with Configuration and Publishing

Source: https://ohdsi.github.io/CohortDiagnostics/articles/DatabaseModeInDiagnosticsExplorer.html

Launches the Diagnostics Explorer Shiny application using a specified configuration file and prepares it for publishing. This function allows for remote database connections and generates a publishable version of the application.

```r
launchDiagnosticsExplorer(
  shinyConfigPath = "path/to/config.yml",
  makePublishable = TRUE,
  publishDir = file.path(getwd(), "MyStudyDiagnosticsExplorer"),
  overwritePublishDir = TRUE
)
```

--------------------------------

### Build Study Package using Hydra Specifications

Source: https://ohdsi.github.io/CohortDiagnostics/articles/CreatingAStudyPackage.html

This R code demonstrates how to build a study package using Hydra. It loads specifications from a JSON file, ensures the output directory is clean, and then runs the Hydra::hydrate function.

```r
hydraSpecificationFromFile <- Hydra::loadSpecifications(fileName = jsonFileName)
unlink(x = outputFolder, recursive = TRUE)
dir.create(path = outputFolder, showWarnings = FALSE, recursive = TRUE)
Hydra::hydrate(
  specifications = hydraSpecificationFromFile,
  outputFolder = outputFolder
)
```

--------------------------------

### Download and Unzip Skeleton Study Package

Source: https://ohdsi.github.io/CohortDiagnostics/articles/CreatingAStudyPackage.html

This R code downloads a skeleton study package from GitHub and unzips it into a temporary folder. It then lists all files within the extracted package.

```r
# download.file(url = "https://github.com/OHDSI/SkeletonCohortDiagnosticsStudy/archive/refs/heads/main.zip",
#                          destfile = file.path(tempFolder, 'skeleton.zip'))
# unzip(zipfile =  file.path(tempFolder, 'skeleton.zip'),
#       overwrite = TRUE,
#       exdir = file.path(tempFolder, "skeleton")
#         )
# fileList <- list.files(path = file.path(tempFolder, "skeleton"), full.names = TRUE, recursive = TRUE, all.files = TRUE)
# DatabaseConnector::createZipFile(zipFile = file.path(tempFolder, 'skeleton.zip'),
#                                  files = fileList,
#                                  rootFolder = list.dirs(file.path(tempFolder, 'skeleton'), recursive = FALSE))
```

--------------------------------

### Launch Diagnostics Explorer (Network)

Source: https://ohdsi.github.io/CohortDiagnostics/articles/ViewingResultsUsingDiagnosticsExplorer.html

Launches the Diagnostics Explorer Shiny application and makes it accessible over the network within the local firewall. Set 'runOverNetwork' to TRUE to enable network access.

```r
launchDiagnosticsExplorer(runOverNetwork = TRUE)
```

--------------------------------

### Create Cohort Tables

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Creates the necessary tables in the database for cohort generation. Setting incremental to FALSE will delete existing tables.

```r
CohortGenerator::createCohortTables(
  connectionDetails = connectionDetails,
  cohortTableNames = cohortTableNames,
  cohortDatabaseSchema = "main",
  incremental = FALSE
)
```

--------------------------------

### Launch Diagnostics Explorer (SQLite Mode)

Source: https://ohdsi.github.io/CohortDiagnostics/articles/ViewingResultsUsingDiagnosticsExplorer.html

Launches the Diagnostics Explorer Shiny application using a pre-existing SQLite database file. Ensure the SQLite file is in a 'data' folder if running from RStudio.

```r
launchDiagnosticsExplorer(sqliteDbPath = "MyCohortDiagnosticsResulst.sqlite")
```

--------------------------------

### Configure Eunomia Test Connection

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Retrieves connection details for the Eunomia test CDM package, which uses a locally stored SQLite database. Defines schemas and table names for cohort instantiation.

```r
connectionDetails <- Eunomia::getEunomiaConnectionDetails()

cdmDatabaseSchema <- "main"
tempEmulationSchema <- NULL
cohortDatabaseSchema <- "main"
cohortTable <- "cohort"
```

--------------------------------

### Launch Diagnostics Explorer Shiny App

Source: https://ohdsi.github.io/CohortDiagnostics/reference/launchDiagnosticsExplorer.html

Launches the Diagnostics Explorer Shiny app. Specify the path to an SQLite database file or connection details for a remote database. Optional arguments allow customization of schemas, table names, and app content.

```r
launchDiagnosticsExplorer(
  sqliteDbPath = "MergedCohortDiagnosticsData.sqlite",
  connectionDetails = NULL,
  shinyConfigPath = NULL,
  resultsDatabaseSchema = NULL,
  vocabularyDatabaseSchema = NULL,
  vocabularyDatabaseSchemas = resultsDatabaseSchema,
  tablePrefix = "",
  cohortTableName = "cohort",
  databaseTableName = "database",
  aboutText = NULL,
  runOverNetwork = FALSE,
  port = 80,
  makePublishable = FALSE,
  publishDir = file.path(getwd(), "DiagnosticsExplorer"),
  overwritePublishDir = FALSE,
  launch.browser = FALSE
)
```

--------------------------------

### View Cohort Definition Set

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Displays the loaded cohort definition set, showing the SQL and JSON for each cohort. This is useful for inspecting the cohort definitions.

```r
View(cohortDefinitionSet)
```

--------------------------------

### Deploy Posit Connect App Function Signature

Source: https://ohdsi.github.io/CohortDiagnostics/reference/deployPositConnectApp.html

This is the function signature for `deployPositConnectApp`. It shows all the available arguments for deploying a Shiny application to Posit Connect or shinyapps.io.

```r
deployPositConnectApp(
  appName,
  appDir = tempfile(),
  sqliteDbPath = "MergedCohortDiagnosticsData.sqlite",
  shinyDirectory = system.file(file.path("shiny", "DiagnosticsExplorer"), package =
    "CohortDiagnostics"),
  connectionDetails = NULL,
  shinyConfigPath = NULL,
  resultsDatabaseSchema = NULL,
  vocabularyDatabaseSchemas = resultsDatabaseSchema,
  tablePrefix = "",
  cohortTableName = "cohort",
  databaseTableName = "database",
  port = 80,
  useRenvironFile = FALSE,
  ...
)
```

--------------------------------

### Define Study Package Metadata

Source: https://ohdsi.github.io/CohortDiagnostics/articles/CreatingAStudyPackage.html

Populate the variables with information specific to your study package, such as version, name, package name, creator, and description.

```r
outputFolder <- "d:/temp/output" # location where you study package will be created

version <- "v0.1.0"
name <- "Thrombosis With Thrombocytopenia Syndrome cohorts - an OHDSI network study"
packageName <- "ThrombosisWithThrombocytopeniaSyndrome"
skeletonVersion <- "v0.0.1"
createdBy <- "rao@ohdsi.org"
createdDate <- Sys.Date() # default
modifiedBy <- "rao@ohdsi.org"
modifiedDate <- Sys.Date()skeletonType <- "CohortDiagnosticsStudy"
organizationName <- "OHDSI"
description <- "Cohort diagnostics on Thrombosis With Thrombocytopenia Syndrome cohorts."
```

--------------------------------

### Hydrate Study Package

Source: https://ohdsi.github.io/CohortDiagnostics/articles/CreatingAStudyPackage.html

Hydrates a study package from a specification file. Ensure the output folder and skeleton file path are correctly specified.

```r
Hydra::hydrate(specifications = hydraSpecificationFromFile,
               outputFolder = outputFolder,
               skeletonFileName = file.path(tempFolder, 'skeleton.zip')
)
```

--------------------------------

### Execute Cohort Diagnostics

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Executes the cohort diagnostics using the provided cohort definition set and connection details. Results are exported to the specified export folder. Ensure minCellCount is set appropriately for privacy.

```r
executeDiagnostics(cohortDefinitionSet,
  connectionDetails = connectionDetails,
  cohortTable = cohortTable,
  cohortDatabaseSchema = cohortDatabaseSchema,
  cdmDatabaseSchema = cdmDatabaseSchema,
  exportFolder = exportFolder,
  databaseId = "MyCdm",
  minCellCount = 5
)
```

--------------------------------

### Load Cohort Definition Set from Package

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Loads a cohort definition set from a study package. This is the preferred method for reproducibility, ensuring cohort definitions and resources are version-controlled.

```r
library(CohortDiagnostics)
covariateSettings <- CohortGenerator::getCohortDefinitionSet(
  settingsFileName = "Cohorts.csv",
  jsonFolder = "cohorts",
  sqlFolder = "sql/sql_server",
  packageName = "CohortDiagnostics"
)
```

--------------------------------

### launchDiagnosticsExplorer

Source: https://ohdsi.github.io/CohortDiagnostics/reference/launchDiagnosticsExplorer.html

Launches a Shiny app that allows the user to explore the diagnostics. It can be configured using various parameters to specify data sources, database connections, and app behavior.

```APIDOC
## Function: launchDiagnosticsExplorer

### Description
Launches a Shiny app that allows the user to explore the diagnostics.

### Usage
```R
launchDiagnosticsExplorer(
  sqliteDbPath = "MergedCohortDiagnosticsData.sqlite",
  connectionDetails = NULL,
  shinyConfigPath = NULL,
  resultsDatabaseSchema = NULL,
  vocabularyDatabaseSchema = NULL,
  vocabularyDatabaseSchemas = resultsDatabaseSchema,
  tablePrefix = "",
  cohortTableName = "cohort",
  databaseTableName = "database",
  aboutText = NULL,
  runOverNetwork = FALSE,
  port = 80,
  makePublishable = FALSE,
  publishDir = file.path(getwd(), "DiagnosticsExplorer"),
  overwritePublishDir = FALSE,
  launch.browser = FALSE
)
```

### Arguments

*   **sqliteDbPath** (string) - Path to merged sqlite file. See `createMergedResultsFile` to create file.
*   **connectionDetails** (object) - An object of type `connectionDetails` as created using the `createConnectionDetails` function in the DatabaseConnector package, specifying how to connect to the server where the CohortDiagnostics results have been uploaded using the `uploadResults` function.
*   **shinyConfigPath** (string) - Path to shiny yml configuration file (use instead of sqliteDbPath or connectionDetails object).
*   **resultsDatabaseSchema** (string) - The schema on the database server where the CohortDiagnostics results have been uploaded.
*   **vocabularyDatabaseSchema** (string) - (Deprecated) Please use vocabularyDatabaseSchemas.
*   **vocabularyDatabaseSchemas** (list) - (optional) A list of one or more schemas on the database server where the vocabulary tables are located. The default value is the value of the resultsDatabaseSchema. We can provide a list of vocabulary schema that might represent different versions of the OMOP vocabulary tables. The default value is the value of the resultsDatabaseSchema. We can provide a list of vocabulary schema that might represent different versions of the OMOP vocabulary tables. It allows us to compare the impact of vocabulary changes on Diagnostics. Not supported with an sqlite database.
*   **tablePrefix** (string) - (Optional) string to insert before table names (e.g. "cd_") for database table names.
*   **cohortTableName** (string) - (Optional) if cohort table name differs from the standard - cohort (ignores prefix if set).
*   **databaseTableName** (string) - (Optional) if database table name differs from the standard - database (ignores prefix if set).
*   **aboutText** (string) - Text (using HTML markup) that will be displayed in an About tab in the Shiny app. If not provided, no About tab will be shown.
*   **runOverNetwork** (boolean) - (optional) Do you want the app to run over your network?
*   **port** (integer) - (optional) Only used if `runOverNetwork` = TRUE.
*   **makePublishable** (boolean) - (Optional) copy data files to make app publishable to posit connect/shinyapp.io.
*   **publishDir** (string) - If make publishable is true - the directory that the shiny app is copied to.
*   **overwritePublishDir** (boolean) - (Optional) If make publishable is true - overwrite the directory for publishing.
*   **launch.browser** (boolean) - Should the app be launched in your default browser, or in a Shiny window. Note: copying to clipboard will not work in a Shiny window.
```

--------------------------------

### Create Diagnostics Explorer Zip

Source: https://ohdsi.github.io/CohortDiagnostics/reference/createDiagnosticsExplorerZip.html

Use this function to create a zip archive of your Shiny application and its SQLite database. It is useful for sharing diagnostic projects, especially when dealing with large database files. Ensure the `sqliteDbPath` points to your merged results file.

```r
createDiagnosticsExplorerZip(
  outputZipfile = file.path(getwd(), "DiagnosticsExplorer.zip"),
  sqliteDbPath = "MergedCohortDiagnosticsData.sqlite",
  shinyDirectory = system.file(file.path("shiny", "DiagnosticsExplorer"), package =
    "CohortDiagnostics"),
  overwrite = FALSE
)
```

--------------------------------

### Set Export Folder

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Sets the directory where the cohort diagnostics results will be exported. This is a prerequisite for executing the diagnostics.

```r
exportFolder <- "export"
```

--------------------------------

### Create Merged Results File (SQLite)

Source: https://ohdsi.github.io/CohortDiagnostics/articles/ViewingResultsUsingDiagnosticsExplorer.html

Converts CSV files from Cohort Diagnostics output into an SQLite database for faster loading in the Shiny application. Specify the directory containing the CSV files and the desired path for the SQLite database.

```r
createMergedResultsFile("C:/temp/allZipFiles", sqliteDbPath = "MyCohortDiagnosticsResulst.sqlite")
```

--------------------------------

### Load Cohort Definition Set from WebAPI

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Creates a cohort definition set from cohort IDs stored in an ATLAS instance. This method is less preferred for reproducibility and network studies.

```r
# Set up url
baseUrl <- "https://atlas.hosting.com/WebAPI"
# list of cohort ids
cohortIds <- c(18345, 18346)

covariateSettings <- ROhdsiWebApi::exportCohortDefinitionSet(
  baseUrl = baseUrl,
  cohortIds = cohortIds,
  generateStats = TRUE
)
```

--------------------------------

### Execute Diagnostics with Package Cohorts

Source: https://ohdsi.github.io/CohortDiagnostics/reference/executeDiagnostics.html

This snippet demonstrates how to use executeDiagnostics with cohorts defined within a package. It requires setting up cohort table names, cohort definitions, and connection details before calling the function.

```r
if (FALSE) { # \dontrun{
# Load cohorts (assumes that they have already been instantiated)
cohortTableNames <- CohortGenerator::getCohortTableNames(cohortTable = "cohort")
cohorts <- CohortGenerator::getCohortDefinitionSet(packageName = "MyGreatPackage")
connectionDetails <- createConnectionDetails(
  dbms = "postgresql",
  server = "ohdsi.com",
  port = 5432,
  user = "me",
  password = "secure"
)

executeDiagnostics(
  cohorts = cohorts,
  exportFolder = "export",
  cohortTableNames = cohortTableNames,
  cohortDatabaseSchema = "results",
  cdmDatabaseSchema = "cdm",
  databaseId = "mySpecialCdm",
  connectionDetails = connectionDetails
)

} # } 

```

--------------------------------

### Create Merged Results File

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Optionally creates a merged SQLite database file from multiple diagnostic result zip files, enabling easier exploration with the Shiny app.

```r
createMergedResultsFile(exportFolder)
```

--------------------------------

### Create Diagnostics Explorer Zip Archive

Source: https://ohdsi.github.io/CohortDiagnostics/articles/ViewingResultsUsingDiagnosticsExplorer.html

Generates a zip archive of the Diagnostics Explorer Shiny application, suitable for deployment on shared environments. This function bundles the application and its necessary files, including the SQLite results database.

```r
createDiagnosticsExplorerZip(outputZipfile = "MyCdProject.zip", sqliteDbPath = "MyCohortDiagnosticsResulst.sqlite")
```

--------------------------------

### uploadResults

Source: https://ohdsi.github.io/CohortDiagnostics/reference/uploadResults.html

Uploads analysis results to the database server. This function requires the results data model tables to be created beforehand. It supports bulk upload via PostgreSQL's psql executable if the POSTGRES_PATH environmental variable is set.

```APIDOC
## uploadResults

### Description
Uploads analysis results to the database server. This function requires the results data model tables to be created beforehand. It supports bulk upload via PostgreSQL's psql executable if the POSTGRES_PATH environmental variable is set.

### Method
`R function call`

### Parameters
#### Arguments
- **connectionDetails** (object of type `connectionDetails`) - Description: An object of type `connectionDetails` as created using the `createConnectionDetails` function in the DatabaseConnector package.
- **schema** (string) - Description: The schema on the postgres server where the tables have been created.
- **zipFileName** (string) - Description: The name of the zip file.
- **forceOverWriteOfSpecifications** (boolean) - Description: If TRUE, specifications of the phenotypes, cohort definitions, and analysis will be overwritten if they already exist on the database. Only use this if these specifications have changed since the last upload.
- **purgeSiteDataBeforeUploading** (boolean) - Description: If TRUE, before inserting data for a specific databaseId all the data for that site will be dropped. This assumes the input zip file contains the full data for that data site.
- **tempFolder** (string) - Description: A folder on the local file system where the zip files are extracted to. Will be cleaned up when the function is finished. Can be used to specify a temp folder on a drive that has sufficient space if the default system temp space is too limited.
- **tablePrefix** (string, Optional) - Description: string to insert before table names (e.g. "cd_") for database table names.
- **...** - Description: See ResultModelManager::uploadResults
```

--------------------------------

### runCohortTimeSeriesDiagnostics

Source: https://ohdsi.github.io/CohortDiagnostics/reference/runCohortTimeSeriesDiagnostics.html

Generates a time series for instantiated cohorts. It creates a calendar period table and computes time series data for each interval, supporting month, quarter, and year. The output is an R dataframe.

```APIDOC
## runCohortTimeSeriesDiagnostics

### Description
Computes calendar period-based time series for cohorts. Supports stratification by gender and age group. Can generate cohort-level and data source-level time series.

### Arguments

* **connectionDetails** (object) - An object of type `connectionDetails` as created using the `createConnectionDetails` function in the DatabaseConnector package. Can be left NULL if `connection` is provided.
* **connection** (object) - An object of type `connection` as created using the `connect` function in the DatabaseConnector package. Can be left NULL if `connectionDetails` is provided.
* **tempEmulationSchema** (string) - Schema name for emulating temp tables on platforms like Oracle and Impala.
* **cdmDatabaseSchema** (string) - Schema name where patient-level data in OMOP CDM format resides. For SQL Server, include database and schema name (e.g., 'cdm_data.dbo').
* **cohortDatabaseSchema** (string) - Schema name where the cohort table resides. For SQL Server, include database and schema name (e.g., 'scratch.dbo').
* **cohortTable** (string) - Name of the cohort table.
* **runCohortTimeSeries** (boolean) - Generate and export the cohort level time series? Default TRUE.
* **runDataSourceTimeSeries** (boolean) - Generate and export the Data source level time series? Default FALSE.
* **timeSeriesMinDate** (Date) - (optional) Minimum date for time series. Default value January 1st 1980.
* **timeSeriesMaxDate** (Date) - (optional) Maximum date for time series. Default value System date.
* **stratifyByGender** (boolean) - Stratify by Gender? Default TRUE.
* **stratifyByAgeGroup** (boolean) - Stratify by Age group? Default TRUE.
* **cohortIds** (vector of integers) - A vector of one or more Cohort Ids to compute time distribution for.
```

--------------------------------

### Migrate Data Model Function Signature

Source: https://ohdsi.github.io/CohortDiagnostics/reference/migrateDataModel.html

This is the function signature for migrating data models. Ensure you have backups before proceeding.

```r
migrateDataModel(connectionDetails, databaseSchema, tablePrefix = "")
```

--------------------------------

### getCdmDataSourceInformation

Source: https://ohdsi.github.io/CohortDiagnostics/reference/getCdmDataSourceInformation.html

Fetches metadata from the CDM source table, providing details about the data source's name, description, release dates, and version information.

```APIDOC
## getCdmDataSourceInformation

### Description
Retrieves CDM source name, description, release date, CDM release date, version, and vocabulary version, where available.

### Usage
```R
getCdmDataSourceInformation(
  connectionDetails = NULL,
  connection = NULL,
  cdmDatabaseSchema
)
```

### Arguments

* **connectionDetails** (object of type `connectionDetails`) - An object of type `connectionDetails` as created using the `createConnectionDetails` function in the DatabaseConnector package. Can be left NULL if `connection` is provided.
* **connection** (object of type `connection`) - An object of type `connection` as created using the `connect` function in the DatabaseConnector package. Can be left NULL if `connectionDetails` is provided, in which case a new connection will be opened at the start of the function, and closed when the function finishes.
* **cdmDatabaseSchema** (string) - Schema name where your patient-level data in OMOP CDM format resides. Note that for SQL Server, this should include both the database and schema name, for example 'cdm_data.dbo'.

### Value
Returns a data frame from CDM Data source.
```

--------------------------------

### Retrieve and Filter Cohort Definitions

Source: https://ohdsi.github.io/CohortDiagnostics/articles/CreatingAStudyPackage.html

Connects to the Web API to fetch cohort definition metadata and filters them based on a provided list of cohort IDs.

```r
library(magrittr)
# Set up
baseUrl <- Sys.getenv("baseUrl")
# if you have security enabled, please authorize the use - example below
# ROhdsiWebApi::authorizeWebApi(baseUrl, 'windows')
cohortIds <- c(
  22040,
  22042,
  22041,
  22039,
  22038,
  22037,
  22036,
  22035,
  22034,
  22033,
  22031,
  22032,
  22030,
  22028,
  22029
)


webApiCohorts <- ROhdsiWebApi::getCohortDefinitionsMetaData(baseUrl = baseUrl)
studyCohorts <- webApiCohorts %>%
  dplyr::filter(.data$id %in% cohortIds)
```

--------------------------------

### Generate Cohort Table Names

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Defines the names for the cohort tables that will be created. This is a prerequisite for instantiating cohorts using CohortGenerator.

```r
cohortTableNames <- CohortGenerator::getCohortTableNames(cohortTable = cohortTable)
```

--------------------------------

### Compile Cohort Definitions into an Array

Source: https://ohdsi.github.io/CohortDiagnostics/articles/CreatingAStudyPackage.html

Iterates through the filtered study cohorts, retrieves the full cohort definition for each, and compiles them into a list suitable for the study package specification.

```r
# compile them into a data table
cohortDefinitionsArray <- list()
for (i in (1:nrow(studyCohorts))) {
  cohortDefinition <- 
    ROhdsiWebApi::getCohortDefinition(
      cohortId = studyCohorts$id[[i]],
      baseUrl = baseUrl
    )
  cohortDefinitionsArray[[i]] <- list(
    id = studyCohorts$id[[i]],
    createdDate = studyCohorts$createdDate[[i]],
    modifiedDate = studyCohorts$createdDate[[i]],
    logicDescription = studyCohorts$description[[i]],
    name = stringr::str_trim(stringr::str_squish(cohortDefinition$name)),
    expression = cohortDefinition$expression
  )
}
```

--------------------------------

### Create Merged Results File Function Signature

Source: https://ohdsi.github.io/CohortDiagnostics/reference/createMergedResultsFile.html

This is the function signature for creating a merged results file. It takes the data folder, output SQLite database path, an overwrite flag, and an optional table prefix as arguments.

```r
createMergedResultsFile(
  dataFolder,
  sqliteDbPath = "MergedCohortDiagnosticsData.sqlite",
  overwrite = FALSE,
  tablePrefix = ""
)
```

--------------------------------

### R Function to Create Results Data Model Tables

Source: https://ohdsi.github.io/CohortDiagnostics/reference/createResultsDataModel.html

This R code defines the usage of the `createResultsDataModel` function. It requires connection details, a database schema, and an optional table prefix. Only PostgreSQL servers are supported.

```r
createResultsDataModel(
  connectionDetails = NULL,
  databaseSchema,
  tablePrefix = ""
)
```

--------------------------------

### Generate Cohort Set

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Generates the cohort set based on the provided cohort definition set and connection details. Incremental mode can be enabled by setting incremental = TRUE.

```r
CohortGenerator::generateCohortSet(
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = cdmDatabaseSchema,
  cohortDatabaseSchema = cohortDatabaseSchema,
  cohortTableNames = cohortTableNames,
  cohortDefinitionSet = cohortDefinitionSet,
  incremental = FALSE
)
```

--------------------------------

### Clean Up Temporary Folder

Source: https://ohdsi.github.io/CohortDiagnostics/articles/CreatingAStudyPackage.html

Removes a temporary folder and its contents. Use with caution as this is a recursive and forceful deletion.

```r
unlink(x = tempFolder, recursive = TRUE, force = TRUE)
```

--------------------------------

### Execute Diagnostics with Data Frame Cohorts

Source: https://ohdsi.github.io/CohortDiagnostics/reference/executeDiagnostics.html

This snippet shows how to use executeDiagnostics with a custom set of cohorts defined in a data frame. The data frame must include columns for cohortId, cohortName, logicDescription, sql, and json.

```r
# Use a custom set of cohorts defined in a data.frame
cohorts <- data.frame(
  cohortId = c(100),
  cohortName = c("Cohort Name"),
  logicDescription = c("My Cohort"),
  sql = c(readLines("path_to.sql")),
  json = c(readLines("path_to.json"))
)
executeDiagnostics(
  cohorts = cohorts,
  exportFolder = "export",
  cohortTable = "cohort",
  cohortDatabaseSchema = "results",
  cdmDatabaseSchema = "cdm",
  databaseId = "mySpecialCdm",
  connectionDetails = connectionDetails
)

```

--------------------------------

### createMergedResultsFile

Source: https://ohdsi.github.io/CohortDiagnostics/reference/createMergedResultsFile.html

Combines diagnostics results from one or more databases into a single SQLite file. The result is an sqlite database that can be used as input for the Diagnostics Explorer Shiny app. It also checks whether the results conform to the results data model specifications.

```APIDOC
## createMergedResultsFile

### Description
Combines diagnostics results from one or more databases into a single SQLite file. The result is an sqlite database that can be used as input for the Diagnostics Explorer Shiny app. It also checks whether the results conform to the results data model specifications.

### Usage
```R
createMergedResultsFile(
  dataFolder,
  sqliteDbPath = "MergedCohortDiagnosticsData.sqlite",
  overwrite = FALSE,
  tablePrefix = ""
)
```

### Arguments 

* **dataFolder** (character) - Folder where the exported zip files for the diagnostics are stored. Use the `executeDiagnostics` function to generate these zip files. Zip files containing results from multiple databases may be placed in the same folder.
* **sqliteDbPath** (character) - Output path where sqlite database is placed. Defaults to "MergedCohortDiagnosticsData.sqlite".
* **overwrite** (logical) - Optional. Overwrite existing sqlite lite db if it exists. Defaults to FALSE.
* **tablePrefix** (character) - Optional. String to insert before table names (e.g. "cd_") for database table names.
```

--------------------------------

### Run Cohort Time Series Diagnostics Function Signature

Source: https://ohdsi.github.io/CohortDiagnostics/reference/runCohortTimeSeriesDiagnostics.html

This is the function signature for `runCohortTimeSeriesDiagnostics`. It outlines the parameters available for configuring the time series diagnostics, including database connection details, schema names, table names, date ranges, and stratification options.

```r
runCohortTimeSeriesDiagnostics(
  connectionDetails = NULL,
  connection = NULL,
  tempEmulationSchema = NULL,
  cdmDatabaseSchema,
  cohortDatabaseSchema = cdmDatabaseSchema,
  cohortTable = "cohort",
  runCohortTimeSeries = TRUE,
  runDataSourceTimeSeries = FALSE,
  timeSeriesMinDate = as.Date("1980-01-01"),
  timeSeriesMaxDate = as.Date(Sys.Date()),
  stratifyByGender = TRUE,
  stratifyByAgeGroup = TRUE,
  cohortIds = NULL
)
```

--------------------------------

### executeDiagnostics

Source: https://ohdsi.github.io/CohortDiagnostics/reference/executeDiagnostics.html

Executes a suite of diagnostic analyses for cohorts. This function assumes cohorts have already been instantiated and can optionally run temporal cohort characterization.

```APIDOC
## executeDiagnostics

### Description
Runs the cohort diagnostics on all (or a subset of) the cohorts instantiated using the CohortGenerator package. Assumes the cohorts have already been instantiated.

### Usage
```R
executeDiagnostics(
  cohortDefinitionSet,
  exportFolder,
  databaseId,
  cohortDatabaseSchema,
  databaseName = NULL,
  databaseDescription = NULL,
  connectionDetails = NULL,
  connection = NULL,
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  cohortTable = "cohort",
  cohortTableNames = CohortGenerator::getCohortTableNames(cohortTable = cohortTable),
  vocabularyDatabaseSchema = cdmDatabaseSchema,
  cohortIds = NULL,
  cdmVersion = 5,
  runInclusionStatistics = TRUE,
  runIncludedSourceConcepts = TRUE,
  runOrphanConcepts = TRUE,
  runTimeSeries = FALSE,
  runVisitContext = TRUE,
  runBreakdownIndexEvents = TRUE,
  runIncidenceRate = TRUE,
  runCohortRelationship = TRUE,
  runTemporalCohortCharacterization = TRUE,
  temporalCovariateSettings = getDefaultCovariateSettings(),
  minCellCount = 5,
  minCharacterizationMean = 0.01,
  irWashoutPeriod = 0,
  incremental = FALSE,
  incrementalFolder = file.path(exportFolder, "incremental"),
  runFeatureExtractionOnSample = FALSE,
  sampleN = 1000,
  seed = 64374,
  seedArgs = NULL
)
```

### Arguments

* **cohortDefinitionSet** (Data.frame) - Must include columns cohortId, cohortName, json, sql.
* **exportFolder** (string) - The folder where the output will be exported to. If this folder does not exist it will be created.
* **databaseId** (string) - A short string for identifying the database (e.g. 'Synpuf').
* **cohortDatabaseSchema** (string) - Schema name where your cohort table resides. Note that for SQL Server, this should include both the database and schema name, for example 'scratch.dbo'.
* **databaseName** (string, optional) - The full name of the database. If NULL, defaults to value in cdm_source table.
* **databaseDescription** (string, optional) - A short description (several sentences) of the database. If NULL, defaults to value in cdm_source table.
* **connectionDetails** (object, optional) - An object of type `connectionDetails` as created using the `createConnectionDetails` function in the DatabaseConnector package. Can be left NULL if `connection` is provided.
* **connection** (object, optional) - An object of type `connection` as created using the `connect` function in the DatabaseConnector package. Can be left NULL if `connectionDetails` is provided, in which case a new connection will be opened at the start of the function, and closed when the function finishes.
* **cdmDatabaseSchema** (string) - Schema name where your patient-level data in OMOP CDM format resides. Note that for SQL Server, this should include both the database and schema name, for example 'cdm_data.dbo'.
* **tempEmulationSchema** (string, optional) - Some database platforms like Oracle and Impala do not truly support temp tables. To emulate temp tables, provide a schema with write privileges where temp tables can be created. Defaults to `getOption("sqlRenderTempEmulationSchema")`.
* **cohortTable** (string, optional) - Name of the cohort table. Defaults to "cohort".
* **cohortTableNames** (object, optional) - Cohort Table names used by CohortGenerator package.
* **vocabularyDatabaseSchema** (string, optional) - Schema name where your OMOP vocabulary data resides. This is commonly the same as cdmDatabaseSchema. Note that for SQL Server, this should include both the database and schema name, for example 'vocabulary.dbo'. Defaults to `cdmDatabaseSchema`.
* **cohortIds** (array, optional) - Optionally, provide a subset of cohort IDs to restrict the diagnostics to.
* **cdmVersion** (numeric, optional) - The version of the OMOP CDM. Default 5. (Note: only 5 is supported.)
* **runInclusionStatistics** (boolean, optional) - Generate and export statistic on the cohort inclusion rules? Defaults to TRUE.
* **runIncludedSourceConcepts** (boolean, optional) - Generate and export the source concepts included in the cohorts? Defaults to TRUE.
* **runOrphanConcepts** (boolean, optional) - Generate and export potential orphan concepts? Defaults to TRUE.
* **runTimeSeries** (boolean, optional) - Generate and export the time series diagnostics? Defaults to FALSE.
* **runVisitContext** (boolean, optional) - Generate and export index-date visit context? Defaults to TRUE.
* **runBreakdownIndexEvents** (boolean, optional) - Generate and export the breakdown of index events? Defaults to TRUE.
* **runIncidenceRate** (boolean, optional) - Generate and export the cohort incidence rates? Defaults to TRUE.
* **runCohortRelationship** (boolean, optional) - Compute cohort relationships. Overlap is now computed with FeaturExtraction, time paramters are derived from temporalCovariateSettings relationship between two or more cohorts. Defaults to TRUE.
* **runTemporalCohortCharacterization** (boolean, optional) - Generate and export the temporal cohort characterization? Only records with values greater than 0.001 are returned. Defaults to TRUE.
* **temporalCovariateSettings** (object, optional) - A covariate setting object. If `runTemporalCohortCharacterization` is TRUE, a default covariate setting object will be created using `RFeatureExtraction::createTemporalCovariateSettings`. Alternatively, a custom object can be provided.
* **minCellCount** (numeric, optional) - Minimum cell count for reporting. Defaults to 5.
* **minCharacterizationMean** (numeric, optional) - Minimum mean for reporting in characterization. Defaults to 0.01.
* **irWashoutPeriod** (numeric, optional) - Washout period for incidence rate calculation. Defaults to 0.
* **incremental** (boolean, optional) - Whether to run in incremental mode. Defaults to FALSE.
* **incrementalFolder** (string, optional) - The folder for incremental results. Defaults to `file.path(exportFolder, "incremental")`.
* **runFeatureExtractionOnSample** (boolean, optional) - Whether to run feature extraction on a sample of the cohort. Defaults to FALSE.
* **sampleN** (numeric, optional) - The number of samples to draw if `runFeatureExtractionOnSample` is TRUE. Defaults to 1000.
* **seed** (numeric, optional) - Seed for random number generation. Defaults to 64374.
* **seedArgs** (list, optional) - Additional arguments for seeding.

```

--------------------------------

### getCohortCounts

Source: https://ohdsi.github.io/CohortDiagnostics/reference/getCohortCounts.html

Computes the subject and entry count per cohort from a specified cohort table.

```APIDOC
## getCohortCounts

### Description
Computes the subject and entry count per cohort.

### Method
`getCohortCounts(
  connectionDetails = NULL,
  connection = NULL,
  cohortDatabaseSchema,
  cohortTable = "cohort",
  cohortIds = c()
)`

### Parameters
#### Arguments
- **connectionDetails** (object) - An object of type `connectionDetails` as created using the `createConnectionDetails` function in the DatabaseConnector package. Can be left NULL if `connection` is provided.
- **connection** (object) - An object of type `connection` as created using the `connect` function in the DatabaseConnector package. Can be left NULL if `connectionDetails` is provided, in which case a new connection will be opened at the start of the function, and closed when the function finishes.
- **cohortDatabaseSchema** (string) - Schema name where your cohort table resides. Note that for SQL Server, this should include both the database and schema name, for example 'scratch.dbo'.
- **cohortTable** (string) - Name of the cohort table. Defaults to "cohort".
- **cohortIds** (array) - The cohort Id(s) used to reference the cohort in the cohort table. If left empty, all cohorts in the table will be included.

### Value
A tibble with cohort counts.
```

--------------------------------

### Upload Results Function Signature

Source: https://ohdsi.github.io/CohortDiagnostics/reference/uploadResults.html

This is the function signature for uploadResults. It outlines the parameters required for uploading results, including connection details, schema, zip file name, and optional parameters for overwriting, purging data, temporary folder, and table prefix.

```R
uploadResults(
  connectionDetails,
  schema,
  zipFileName,
  forceOverWriteOfSpecifications = FALSE,
  purgeSiteDataBeforeUploading = TRUE,
  tempFolder = tempdir(),
  tablePrefix = "",
  ...
)
```

--------------------------------

### R Function Signature for getCdmDataSourceInformation

Source: https://ohdsi.github.io/CohortDiagnostics/reference/getCdmDataSourceInformation.html

This snippet shows the signature of the R function `getCdmDataSourceInformation`. It outlines the required and optional arguments for calling the function, including connection details and the CDM database schema.

```r
getCdmDataSourceInformation(
  connectionDetails = NULL,
  connection = NULL,
  cdmDatabaseSchema
)
```

--------------------------------

### Check Input File Encoding Function

Source: https://ohdsi.github.io/CohortDiagnostics/reference/checkInputFileEncoding.html

This R function checks if the specified file has a UTF-8 or ASCII encoding. It is used to validate input files before processing them with CohortDiagnostics.

```r
checkInputFileEncoding <- function(fileName) {
  if (is.null(fileName)) {
    return(NULL)
  }
  encoding <- tryCatch({
    readr::guess_encoding(fileName)
  }, error = function(e) {
    # If guess_encoding fails, assume it's not a text file and throw an error
    stop("Could not read file: ", fileName, ". Ensure it is a text file.")
  })
  if (nrow(encoding) == 0 || encoding$encoding[1] != "UTF-8") {
    stop("Input file '", fileName, "' has encoding '", encoding$encoding[1], "'. Only UTF-8 or ASCII is allowed.")
  }
  invisible(NULL)
}
```

--------------------------------

### Execute Cohort Diagnostics Function Signature

Source: https://ohdsi.github.io/CohortDiagnostics/reference/executeDiagnostics.html

This is the function signature for executeDiagnostics, outlining all available arguments and their default values. Use this to understand the parameters required for running cohort diagnostics.

```R
executeDiagnostics(
  cohortDefinitionSet,
  exportFolder,
  databaseId,
  cohortDatabaseSchema,
  databaseName = NULL,
  databaseDescription = NULL,
  connectionDetails = NULL,
  connection = NULL,
  cdmDatabaseSchema,
  tempEmulationSchema = getOption("sqlRenderTempEmulationSchema"),
  cohortTable = "cohort",
  cohortTableNames = CohortGenerator::getCohortTableNames(cohortTable = cohortTable),
  vocabularyDatabaseSchema = cdmDatabaseSchema,
  cohortIds = NULL,
  cdmVersion = 5,
  runInclusionStatistics = TRUE,
  runIncludedSourceConcepts = TRUE,
  runOrphanConcepts = TRUE,
  runTimeSeries = FALSE,
  runVisitContext = TRUE,
  runBreakdownIndexEvents = TRUE,
  runIncidenceRate = TRUE,
  runCohortRelationship = TRUE,
  runTemporalCohortCharacterization = TRUE,
  temporalCovariateSettings = getDefaultCovariateSettings(),
  minCellCount = 5,
  minCharacterizationMean = 0.01,
  irWashoutPeriod = 0,
  incremental = FALSE,
  incrementalFolder = file.path(exportFolder, "incremental"),
  runFeatureExtractionOnSample = FALSE,
  sampleN = 1000,
  seed = 64374,
  seedArgs = NULL
)
```

--------------------------------

### BibTeX Citation for CohortDiagnostics

Source: https://ohdsi.github.io/CohortDiagnostics/authors.html

This snippet provides the BibTeX formatted citation for the CohortDiagnostics R package. Use this in LaTeX documents for proper referencing.

```bibtex
@Manual{
  title = {CohortDiagnostics: Diagnostics for OHDSI Cohorts},
  author = {Jamie Gilbert and Gowtham Rao and Martijn Schuemie and Patrick Ryan and James Weaver},
  year = {2025},
  note = {R package version 3.4.2, https://github.com/OHDSI/CohortDiagnostics},
  url = {https://ohdsi.github.io/CohortDiagnostics},
}
```

--------------------------------

### Drop Cohort Statistics Tables

Source: https://ohdsi.github.io/CohortDiagnostics/articles/RunningCohortDiagnostics.html

Removes residual tables created during the cohort generation process that are no longer required after completion.

```r
CohortGenerator::dropCohortStatsTables(
  connectionDetails = connectionDetails,
  cohortDatabaseSchema = cohortDatabaseSchema,
  cohortTableNames = cohortTableNames
)
```
Tokens:
Raw