### Connect to CDM and Run Achilles Analysis

Source: https://github.com/ohdsi/achilles/blob/main/docs/articles/GettingStarted.html

Demonstrates how to establish connection details for a database and then execute the Achilles analysis. The 'cdmVersion', 'connectionDetails', 'cdmDatabaseSchema', and 'resultsDatabaseSchema' parameters are crucial for specifying the CDM version, connection, and schema locations for data and results.

```R
library(Achilles)
connectionDetails <- createConnectionDetails(
  dbms="redshift", 
  server="server.com", 
  user="secret", 
  password='secret', 
  port="5439")

```

```R
Achilles::achilles(
    cdmVersion = "5.4", 
    connectionDetails = connectionDetails,
    cdmDatabaseSchema = "yourCdmSchema",
    resultsDatabaseSchema = "yourResultsSchema"
)
```

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

### Install Achilles R Package

Source: https://github.com/ohdsi/achilles/blob/main/docs/articles/GettingStarted.html

Installs the Achilles R package from GitHub. It supports installing the master branch, the latest release, or a specific build to avoid multi-arch issues with Java. Ensure 'remotes' package is installed first.

```R
if (!require("remotes")) install.packages("remotes")

# To install the master branch
remotes::install_github("OHDSI/Achilles")

# To install latest release (if master branch contains a bug for you)
# remotes::install_github("OHDSI/Achilles@*release")  

# To avoid Java 32 vs 64 issues 
# remotes::install_github("OHDSI/Achilles", args="--no-multiarch")  
```

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

### Create PostgreSQL Connection Details in R

Source: https://github.com/ohdsi/achilles/wiki/Additional-instructions-for-Linux

Example of how to create a connection object in R for a PostgreSQL database. This function specifies the database type, server address, port, schema, username, and password required to connect to the OMOP database.

```r
connectionDetails <- createConnectionDetails(dbms="postgresql",server="localhost/omop",port="5432",
                                         schema="omop",user="achilles",password="achilles")
```

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

### Example Usage of fetchAchillesAnalysisResults (R)

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/fetchAchillesAnalysisResults.html

An example demonstrating how to establish connection details using DatabaseConnector, run an Achilles analysis (though not shown here), and then fetch the results for a specific analysis ID using fetchAchillesAnalysisResults.

```r
if (FALSE) {
  connectionDetails <- DatabaseConnector::createConnectionDetails(dbms="sql server", server="myserver")
  achillesResults <- achilles(connectionDetails, "cdm4_sim", "scratch", "TestDB")
  fetchAchillesAnalysisResults(connectionDetails, "scratch",106)
}
```

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

### Install PHP PostgreSQL Support (CentOS)

Source: https://github.com/ohdsi/achilles/wiki/Additional-instructions-for-Linux

Installs the PHP module necessary for PHP applications to interact with PostgreSQL databases using the YUM package manager on CentOS systems.

```bash
yum install php-pgsql
```

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

### Achilles Function Example

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/achilles.html

Demonstrates how to execute the Achilles function with specified connection details and database schemas. This example highlights the necessary parameters for running the analysis, including connection information, schema names, source name, CDM version, number of threads, and output folder.

```r
if (FALSE) {
connectionDetails <- createConnectionDetails(dbms = "sql server", server = "some_server")
achillesResults <- achilles(connectionDetails = connectionDetails,
  cdmDatabaseSchema = "cdm",
  resultsDatabaseSchema = "results",
  scratchDatabaseSchema = "scratch", 
  sourceName = "Some Source", 
  cdmVersion = "5.3", 
  numThreads = 10, 
  outputFolder = "output")
}
```

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

### Example: Adding a New CDM Data Source (R)

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/addDataSource.html

An illustrative example demonstrating how to use `addDataSource`. It first sets up connection details, exports CDM data to JSON files using `exportToJson`, and then calls `addDataSource` to register this new data source with AchillesWeb.

```r
if (FALSE) {
jsonFolderPath <- "your/output/path"
dataSourcesFilePath <- "/path/to/datasources.json"
dataSourceName <- "My New CDM"
connectionDetails <- DatabaseConnector::createConnectionDetails(dbms = "sql server",
                                                                    server = "yourserver")
exportToJson(connectionDetails,
             cdmDatabaseSchema = "cdm5",
             resultsDatabaseSchema = "results",
             outputPath = jsonFolderPath)
addDataSource(jsonFolderPath, dataSourcesFilePath, dataSourceName)
}
```

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

### Install rJava Package for R (Linux)

Source: https://github.com/ohdsi/achilles/wiki/Additional-instructions-for-Linux

Installs the 'rJava' package in R from a specific repository. This is often required for R packages that interface with Java, and the provided URL is a workaround for potential issues with default repositories.

```r
install.packages('rJava', .libPaths()[1], 'http://www.rforge.net/')
```

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

### Example Usage of runMissingAnalyses in Achilles R

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/runMissingAnalyses.html

An example demonstrating how to call the `runMissingAnalyses` function with specified connection details, CDM schema, results schema, and an output folder. This example is conditional and will only run if the `FALSE` block is uncommented.

```r
if (FALSE) {
Achilles::runMissingAnalyses(connectionDetails = connectionDetails,
                                 cdmDatabaseSchema = "cdm",
                                 resultsDatabaseSchema = "results",

      outputFolder = "/tmp")
}
```

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

### Configure Java for R (Linux)

Source: https://github.com/ohdsi/achilles/wiki/Additional-instructions-for-Linux

This command reconfigures R to recognize the Java installation. It is a necessary step after installing Java on a Linux system to ensure that R packages relying on Java can function correctly.

```bash
sudo R CMD javareconf
```

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

### R Example: Complete Temporal Characterization

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/performTemporalCharacterization.html

This R code shows how to perform a complete temporal characterization across all supported analyses. It requires connection details and database schemas, and specifies an output file. This example runs the analysis for all supported temporal analyses without specific filters.

```R
performTemporalCharacterization(
  connectionDetails     = connectionDetails,
  cdmDatabaseSchema     = "cdm",
  resultsDatabaseSchema = "results",
  outputFolder          = "output/CompleteTemporalChar.csv"
)
```

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

### Install Achilles R Package

Source: https://github.com/ohdsi/achilles/blob/main/README.md

Installs the Achilles R package from GitHub. This requires the 'remotes' package to be installed first. Ensure your R environment is configured with RTools and Java as per OHDSI Hades documentation.

```r
install.packages("remotes")
remotes::install_github("OHDSI/Achilles")
```

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

### Example Usage of exportToJson

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/exportToJson.html

This example demonstrates how to use the exportToJson function. It first creates connection details for a SQL Server database and then calls exportToJson, specifying the CDM schema and the desired output path for the generated JSON reports.

```r
if (FALSE) {
connectionDetails <- DatabaseConnector::createConnectionDetails(dbms = "sql server",
                                                                    server = "yourserver")
exportToJson(connectionDetails, cdmDatabaseSchema = "cdm4_sim", outputPath = "your/output/path")
}
```

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

### Adjust SELinux Permissions for Web Files (CentOS)

Source: https://github.com/ohdsi/achilles/wiki/Additional-instructions-for-Linux

These commands adjust SELinux security contexts to grant the web server (httpd) appropriate read and execute permissions for files in the /var/www/localhost directory. This is a common fix for 'Permission Denied' errors when AchillesWeb is hosted on CentOS.

```bash
chmod -R +x /var/www/localhost
chcon -Rv --type=httpd_sys_content_t /var/www/localhost
```

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

### Create Time Series from Data Frame (R)

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/createTimeSeries.html

Demonstrates how to create a multivariate time series object using the createTimeSeries function. It requires a data frame with specific columns (START_DATE, COUNT_VALUE, PREVALENCE, PROPORTION_WITHIN_YEAR) and returns a time series object that can be further analyzed. The example includes creating a sample data frame and extracting individual time series components.

```r
temporalData <- data.frame(START_DATE = seq.Date(as.Date("20210101", "%Y%m%d"),
                                                     as.Date("20231201",
      "%Y%m%d"), by = "month"), COUNT_VALUE = round(runif(36, 1, 1000)), PREVALENCE = round(runif(36, 
      0, 10), 2), PROPORTION_WITHIN_YEAR = round(runif(36, 0, 1), 2), stringsAsFactors = FALSE)
dummyTs <- createTimeSeries(temporalData)
dummyTs.cv <- dummyTs[, "COUNT_VALUE"]
dummyTs.pv <- dummyTs[, "PREVALENCE"]
dummyTs.pwy <- dummyTs[, "PROPORTION_WITHIN_YEAR"]

if (FALSE) {
# Example 2:
pneumonia <- 255848
temporalData <- getTemporalData(connectionDetails = connectionDetails, cdmDatabaseSchema = "cdm",
  resultsDatabaseSchema = "results", conceptId = pneumonia)
pneumoniaTs <- createTimeSeries(temporalData)
pneumoniaTs.cv <- pneumoniaTs[, "COUNT_VALUE"]
pneumoniaTs.pv <- pneumoniaTs[, "PREVALENCE"]
pneumoniaTs.pwy <- pneumoniaTs[, "PROPORTION_WITHIN_YEAR"]
}
```

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

### R Example: Temporal Characterization for Specific Analysis IDs

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/performTemporalCharacterization.html

This R code illustrates how to use performTemporalCharacterization to analyze temporal patterns for a defined set of analysis IDs (e.g., condition occurrence and drug exposure). It includes connection details, database schemas, the specified analysis IDs, and an output file name.

```R
performTemporalCharacterization(
  connectionDetails     = connectionDetails,
  cdmDatabaseSchema     = "cdm",
  resultsDatabaseSchema = "results",
  analysisIds           = c(402,702),
  outputFolder          = "output/conditionAndDrugTemporalChar.csv"
)
```

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

### Get Analysis Details with Achilles

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.md

Retrieves a data frame containing detailed information about all available Achilles analyses. This is useful for understanding analysis categories, names, and default execution status. It requires no specific input parameters beyond the package being loaded.

```r
details <- Achilles::getAnalysisDetails()
print(colnames(details))
print(length(which(details$IS_DEFAULT == 1)))
print(details[details$IS_DEFAULT == 0,c(1,5)])
print(unique(details$CATEGORY))
```

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

### Perform Temporal Characterization Analysis in R

Source: https://context7.com/ohdsi/achilles/llms.txt

This R code snippet demonstrates how to perform temporal characterization analysis on clinical data using the Achilles package. It includes setting up database connections, executing the temporal characterization for a specific concept, calculating seasonality scores, and testing for time series stationarity. Ensure the DatabaseConnector and Achilles packages are installed.

```r
library(Achilles)

connectionDetails <- DatabaseConnector::connect(
  DatabaseConnector::createConnectionDetails(
    dbms = "postgresql",
    server = "localhost/cdm",
    user = "user",
    password = "pass"
  )
)

# Perform temporal characterization for a specific concept
temporalData <- performTemporalCharacterization(
  connection = connectionDetails,
  cdmDatabaseSchema = "cdm",
  resultsDatabaseSchema = "results",
  conceptId = 313217,  # Atrial fibrillation
  startDate = "2015-01-01",
  endDate = "2020-12-31"
)

# Check for seasonality
seasonalityScore <- getSeasonalityScore(
  temporalData = temporalData,
  conceptId = 313217
)

# Test if time series is stationary
stationaryTest <- isStationary(temporalData)

DatabaseConnector::disconnect(connectionDetails)
```

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

### R Example: Temporal Characterization for a Specific Concept

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/performTemporalCharacterization.html

This R code demonstrates how to use performTemporalCharacterization to analyze temporal patterns for a specific concept ID (e.g., pneumonia). It specifies the connection details, CDM schema, results schema, the concept ID, and an output file path.

```R
pneumonia <- 255848
performTemporalCharacterization(
  connectionDetails     = connectionDetails,
  cdmDatabaseSchema     = "cdm",
  resultsDatabaseSchema = "results",
  conceptId             = pneumonia,
  outputFolder          = "output/pneumoniaTemporalChar.csv"
)
```

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

### Run All Analyses with Achilles (R)

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.html

This snippet demonstrates how to run all default analyses using the Achilles package. It requires connection details, CDM and results database schemas, and an output folder.

```r
Achilles::achilles(
  connectionDetails     = connectionDetails,
  cdmDatabaseSchema     = cdmDatabaseSchema,
  resultsDatabaseSchema = resultsDatabaseSchema,
  defaultAnalysesOnly   = TRUE,
  outputFolder          = "your output folder"
)
```

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

### Get All Analysis Details - R

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/getAnalysisDetails.html

The getAnalysisDetails() function in the Achilles R package retrieves a comprehensive list of all analyses. It returns a data frame containing the analysis IDs and their corresponding strata, useful for understanding the available analytical options.

```r
getAnalysisDetails()
```

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

### Run Achilles: Multi-Threaded Mode (R)

Source: https://github.com/ohdsi/achilles/blob/main/docs/articles/RunningAchilles.html

Executes the Achilles analysis in multi-threaded mode, allowing for parallel processing. This mode requires specifying a scratch database schema and the number of threads. Parameters include connection details, CDM schema, results schema, scratch schema, number of threads, and output folder.

```r
connectionDetails <- createConnectionDetails(dbms = "postgresql", 
                                                 server = "localhost/synpuf", 
                                                 user = "cdm_user", 
                                                 password = "cdm_password")
    
    achilles(connectionDetails = connectionDetails, 
             cdmDatabaseSchema = "cdm", 
             resultsDatabaseSchema = "results", 
             scratchDatabaseSchema = "scratch", 
             numThreads = 5,
             outputFolder = "output")
```

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

### Drop Staging Tables using Achilles R package

Source: https://github.com/ohdsi/achilles/blob/main/docs/articles/RunningAchilles.html

This function `dropAllScratchTables` is used to drop staging tables. It requires connection details to the database and optionally accepts a `scratchDatabaseSchema` and `numThreads` for multi-threaded execution. Ensure `achilles` has been executed or the step is enabled.

```r
connectionDetails <- createConnectionDetails(dbms = "postgresql", 
                                                 server = "localhost/synpuf", 
                                                 user = "cdm_user", 
                                                 password = "cdm_password")

dropAllScratchTables(connectionDetails = connectionDetails, 
                     scratchDatabaseSchema = "scratch", numThreads = 5)
```

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

### Retrieve Achilles Analysis Details

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.html

Fetches a data frame containing detailed information about all available Achilles analyses. This is useful for understanding the scope of analyses and their parameters. It requires the Achilles package to be installed.

```r
details <- Achilles::getAnalysisDetails()
colnames(details)
```

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

### Run Achilles: Single-Threaded Mode (R)

Source: https://github.com/ohdsi/achilles/blob/main/docs/articles/RunningAchilles.html

Executes the Achilles analysis in single-threaded mode. This mode does not require a scratch database schema. The function takes connection details, CDM schema, results schema, and output folder as parameters.

```r
connectionDetails <- createConnectionDetails(dbms = "postgresql", 
                                                 server = "localhost/synpuf", 
                                                 user = "cdm_user", 
                                                 password = "cdm_password")
    
    achilles(connectionDetails = connectionDetails, 
             cdmDatabaseSchema = "cdm", 
             resultsDatabaseSchema = "results", 
             outputFolder = "output")
```

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

### Run All Achilles Analyses

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.md

Executes all analyses, including both default and non-default ones, within the Achilles package. This is controlled by setting the 'defaultAnalysesOnly' parameter to FALSE. It requires connection details, the CDM database schema, the results database schema, and optionally an output folder.

```r
Achilles::achilles(
  connectionDetails     = connectionDetails,
  cdmDatabaseSchema     = cdmDatabaseSchema,
  resultsDatabaseSchema = resultsDatabaseSchema,
  defaultAnalysesOnly   = FALSE,
  outputFolder          = "your output folder"
)
```

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

### SQL-Only Mode for Query Generation

Source: https://context7.com/ohdsi/achilles/llms.txt

Generates SQL scripts for Achilles analyses without executing them. This allows for manual review or execution in different environments. Requires specifying the SQL dialect if `connectionDetails` is omitted.

```r
library(Achilles)

# Generate SQL for PostgreSQL without executing
achillesResults <- achilles(
  connectionDetails = NULL,  # Can be omitted in SQL-only mode
  cdmDatabaseSchema = "cdm",
  resultsDatabaseSchema = "results",
  sqlOnly = TRUE,
  sqlDialect = "postgresql",  # Must specify dialect when no connectionDetails
  outputFolder = "sql_output",
  cdmVersion = "5.3"
)

# All SQL scripts are written to:
# sql_output/achilles.sql

# Can also pass connectionDetails for dialect detection
connectionDetails <- DatabaseConnector::createConnectionDetails(
  dbms = "oracle"
)

achillesResults <- achilles(
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = "cdm",
  resultsDatabaseSchema = "results",
  sqlOnly = TRUE,
  outputFolder = "sql_output"
)
```

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

### List Missing Analyses in R

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/listMissingAnalyses.html

This R function, listMissingAnalyses, identifies which analyses from a predefined set (getAnalysisDetails) are not found in the Achilles results tables (achilles_results or achilles_results_dist). It requires connection details to the database and the schema where the results are stored. The function returns a dataframe containing the details of the missing analyses, which is a subset of the getAnalysisDetails dataframe. Ensure the DatabaseConnector package is installed for creating connectionDetails.

```r
listMissingAnalyses <- function(connectionDetails, resultsDatabaseSchema) {
  # Placeholder for function implementation
  # In a real scenario, this would query the database
  # and compare getAnalysisDetails with achilles_results/achilles_results_dist
  message("This is a placeholder for the listMissingAnalyses function.")
  message("It requires database connection details and results schema.")
  # Example of what might be returned:
  # data.frame(analysisId = c(1, 2, 3), analysisName = c("Age", "Gender", "Race"))
}
```

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

### Run Non-Default Analyses with Achilles (R)

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.html

This snippet shows how to run only non-default analyses by first retrieving all analysis details and then filtering for those where IS_DEFAULT is 0. It uses the 'analysisIds' parameter to specify which analyses to run.

```r
details     <- Achilles::getAnalysisDetails()
analyseIds <- details[which(details$IS_DEFAULT==0),]$ANALYSIS_ID

Achilles::achilles(
  connectionDetails     = connectionDetails,
  cdmDatabaseSchema     = cdmDatabaseSchema,
  resultsDatabaseSchema = resultsDatabaseSchema,
  analysisIds           = analysisIds,
  outputFolder          = "your output folder"
)
```

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

### Export Person Report to JSON (R)

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/exportPersonToJson.html

This R function exports the Achilles Person report data into individual JSON files. It requires database connection details, schema information for the Common Data Model (CDM), results, and optionally vocabulary. The output JSON files are saved to a specified directory. Ensure the necessary R packages (e.g., DatabaseConnector) are installed.

```r
exportPersonToJson(
  connectionDetails,
  cdmDatabaseSchema,
  resultsDatabaseSchema,
  outputPath,
  vocabDatabaseSchema = cdmDatabaseSchema
)
```

```r
if (FALSE) {
connectionDetails <- DatabaseConnector::createConnectionDetails(dbms = "sql server",
                                                                    server = "yourserver")
exportPersonToJson(connectionDetails,
                       cdmDatabaseSchema = "cdm4_sim",
                       outputPath = "your/output/path")
}
```

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

### Create Database Indices for Performance

Source: https://context7.com/ohdsi/achilles/llms.txt

Creates indices on Achilles results tables to enhance query performance. This is particularly useful for the `achilles_results` and `achilles_results_dist` tables. Index creation is automatically skipped for platforms that do not support indices.

```r
library(Achilles)

connectionDetails <- DatabaseConnector::createConnectionDetails(
  dbms = "postgresql",
  server = "localhost/cdm",
  user = "user",
  password = "pass"
)

# Create indices on both achilles_results and achilles_results_dist tables
createIndices(
  connectionDetails = connectionDetails,
  resultsDatabaseSchema = "results",
  outputFolder = "output",
  verboseMode = TRUE,
  achillesTables = c("achilles_results", "achilles_results_dist")
)

# Note: Index creation is automatically skipped for platforms
# that don't support indices (Redshift, BigQuery, Netezza, Snowflake, Spark)
```

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

### Run Default Achilles Analyses

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.md

Executes all analyses marked as default within the Achilles package. This function requires connection details, the CDM database schema, and the results database schema. An output folder can also be specified, defaulting to the current working directory's 'output' subfolder if omitted.

```r
Achilles::achilles(
  connectionDetails     = connectionDetails,
  cdmDatabaseSchema     = cdmDatabaseSchema,
  resultsDatabaseSchema = resultsDatabaseSchema,
  outputFolder          = "your output folder"
)
```

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

### Launch Achilles Heel Shiny App (R)

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/launchHeelResultsViewer.html

Launches the Achilles Heel Shiny application, enabling users to interactively explore the results of Achilles analyses. This function requires database connection details and schema information for CDM, results, and vocabulary. It also supports specifying scratch schemas, prefixes for temporary tables, and the number of threads for parallel processing. The output folder parameter is used to store logs and SQL files.

```r
launchHeelResultsViewer(
  connectionDetails,
  cdmDatabaseSchema,
  resultsDatabaseSchema,
  scratchDatabaseSchema = resultsDatabaseSchema,
  vocabDatabaseSchema = cdmDatabaseSchema,
  tempAchillesPrefix = "tmpach",
  tempHeelPrefix = "tmpheel",
  numThreads = 1,
  outputFolder
)
```

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

### Run Specific Non-Default Achilles Analyses

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.md

Executes only the non-default analyses. This is achieved by first retrieving all analysis details using getAnalysisDetails(), filtering for non-default analyses, and then passing their IDs to the 'analysisIds' parameter of the achilles() function. Requires connection details, CDM and results schemas, and an output folder.

```r
details     <- Achilles::getAnalysisDetails()
analysisIds <- details[which(details$IS_DEFAULT==0),]$ANALYSIS_ID

Achilles::achilles(
  connectionDetails     = connectionDetails,
  cdmDatabaseSchema     = cdmDatabaseSchema,
  resultsDatabaseSchema = resultsDatabaseSchema,
  analysisIds           = analysisIds,
  outputFolder          = "your output folder"
)
```

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

### Generate Database Summary with R

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/generateDbSummary.html

This R function generates a high-level summary of an OMOP CDM database. It requires connection details, CDM and results schemas, country, and data provenance. The output is a summary table useful for manuscripts.

```r
generateDbSummary(
  connectionDetails,
  cdmDatabaseSchema,
  resultsDatabaseSchema,
  country,
  provenance
)
```

```r
connectionDetails <- DatabaseConnector::createConnectionDetails(dbms = "sql server",
                                                                    server = "yourserver")
dbSummary <- generateDbSummary(connectionDetails,
                                   cdmDatabaseSchema = "cdm_schema",
                                   resultsDatabaseSchema = "results_schema",
                                   country = "Country of Origin",
                                   provenance = "Provenance of data")
```

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

### Post-Processing: Create Indices (R)

Source: https://github.com/ohdsi/achilles/blob/main/docs/articles/RunningAchilles.html

Creates indices on the Achilles results tables to enhance query performance. This function is not supported on Amazon Redshift or IBM Netezza. It requires connection details, the results database schema, and an output folder.

```r
connectionDetails <- createConnectionDetails(dbms = "postgresql", 
                                                 server = "localhost/synpuf", 
                                                 user = "cdm_user", 
                                                 password = "cdm_password")
    
    createIndices(connectionDetails = connectionDetails, 
                  resultsDatabaseSchema = "results", 
                  outputFolder = "output")
```

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

### Add Data Source to AchillesWeb Configuration (R)

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/addDataSource.html

This function adds a new data source to the `datasources.json` file, which is utilized by AchillesWeb. It requires the path to JSON files generated by `exportToJson`, the desired file path for `datasources.json`, and a human-readable name for the data source. If the `datasources.json` file does not exist, it will be created.

```r
addDataSource(jsonFolderPath, dataSourcesFilePath, dataSourceName)
```

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

### Run Missing Analyses with Achilles (R)

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.html

This snippet demonstrates how to run analyses that are identified as missing using the 'runMissingAnalyses' function. This function will execute analyses that have not been previously completed and does not delete prior data.

```r
Achilles::runMissingAnalyses(
  connectionDetails     = connectionDetails,
  cdmDatabaseSchema     = cdmDatabaseSchema,
  resultsDatabaseSchema = resultsDatabaseSchema,
  outputFolder          = "your output folder"
)
```

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

### List Missing Analyses with Achilles (R)

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.html

This snippet shows how to use the 'listMissingAnalyses' function to identify analyses that have not yet been run or have been skipped. It requires connection details and the results database schema.

```r
Achilles::listMissingAnalyses(connectionDetails,resultsDatabaseSchema)
```

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

### Create Indices API

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/createIndices.html

This endpoint allows for the creation of indices on Achilles results tables to enhance query performance. It supports generating SQL only or executing the index creation directly. Note that this functionality is not compatible with Redshift.

```APIDOC
## POST /achilles/createIndices

### Description
Creates indices on specified Achilles results tables to improve query performance. This function can optionally generate only the SQL statements without execution.

### Method
POST

### Endpoint
/achilles/createIndices

### Parameters
#### Request Body
- **connectionDetails** (object) - Required - An R object of type `connectionDetails` created using the function `createConnectionDetails` in the `DatabaseConnector` package.
- **resultsDatabaseSchema** (string) - Required - Fully qualified name of the database schema where results will be stored. For SQL Server, include the database name (e.g., 'cdm_results.dbo').
- **outputFolder** (string) - Required - Path to store logs and SQL files.
- **sqlOnly** (boolean) - Optional - If TRUE, only generate SQL files; if FALSE, execute Achilles. Defaults to FALSE.
- **verboseMode** (boolean) - Optional - If TRUE, show all execution steps in the console. Defaults to TRUE.
- **achillesTables** (array of strings) - Optional - An array of table names to index. Defaults to `["achilles_results", "achilles_results_dist"].

### Request Example
```json
{
  "connectionDetails": {"dbms": "postgresql", "server": "localhost", "user": "user", "password": "password", "schema": "results"},
  "resultsDatabaseSchema": "results",
  "outputFolder": "./achilles_output",
  "sqlOnly": false,
  "verboseMode": true,
  "achillesTables": ["achilles_results", "achilles_results_dist"]
}
```

### Response
#### Success Response (200)
- **queries_executed** (integer) - The number of SQL queries executed.
- **sql** (string) - The generated SQL statements for index creation.

#### Response Example
```json
{
  "queries_executed": 2,
  "sql": "DROP INDEX IF EXISTS idx_ar_concept_id ON results.achilles_results; CREATE INDEX idx_ar_concept_id ON results.achilles_results (concept_id); ..."
}
```

### Errors
- **400 Bad Request**: Invalid input parameters.
- **500 Internal Server Error**: An error occurred during index creation.
```

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

### Run Complete OMOP CDM Database Characterization (R)

Source: https://context7.com/ohdsi/achilles/llms.txt

Executes a comprehensive characterization of an OMOP CDM database using the Achilles R package in single-threaded mode. It requires database connection details, CDM schemas, source name, CDM version, and an output folder. This function generates detailed statistics in `achilles_results` and `achilles_results_dist` tables within the specified results schema.

```r
library(Achilles)

# Create database connection details
connectionDetails <- DatabaseConnector::createConnectionDetails(
  dbms = "postgresql",
  server = "localhost/ohdsi",
  user = "cdm_user",
  password = "secure_password",
  port = 5432
)

# Run Achilles in single-threaded mode with default analyses
achillesResults <- achilles(
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = "cdm_v5",
  resultsDatabaseSchema = "results",
  sourceName = "My Healthcare Database",
  cdmVersion = "5.3",
  outputFolder = "output",
  verboseMode = TRUE,
  createIndices = TRUE,
  smallCellCount = 5,
  defaultAnalysesOnly = TRUE
)

# The function creates achilles_results and achilles_results_dist tables
# in the results schema with detailed statistics
```

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

### Generate Database Summary Report

Source: https://context7.com/ohdsi/achilles/llms.txt

Generates a comprehensive summary of database characteristics, including total person count, observation period statistics, record counts by domain, and data quality metrics. This function requires an active database connection.

```r
library(Achilles)

connectionDetails <- DatabaseConnector::createConnectionDetails(
  dbms = "sql server",
  server = "sqlserver.example.com",
  database = "OHDSI",
  user = "user",
  password = "pass"
)

connection <- DatabaseConnector::connect(connectionDetails)

# Generate database summary
dbSummary <- generateDbSummary(
  connection = connection,
  cdmDatabaseSchema = "dbo.cdm",
  resultsDatabaseSchema = "dbo.results",
  vocabDatabaseSchema = "dbo.vocabulary"
)

# Summary includes:
# - Total person count
# - Observation period statistics
# - Record counts by domain
# - Data quality metrics

DatabaseConnector::disconnect(connection)
```

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

### Cite Achilles R Package

Source: https://github.com/ohdsi/achilles/blob/main/docs/articles/RunningAchilles.html

Provides the citation information for the Achilles R package, including author names, year, and version number, along with a BibTeX entry for LaTeX users.

```r
citation("Achilles")

#> 
#> To cite package 'Achilles' in publications use:
#> 
#>   DeFalco F, Ryan P, Schuemie M, Huser V, Knoll C, Londhe A,
#>   Abdul-Basser T, Molinaro A (2023). _Achilles: Achilles Data Source
#>   Characterization_. R package version 1.7.1.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {Achilles: Achilles Data Source Characterization},
#>     author = {Frank DeFalco and Patrick Ryan and Martijn Schuemie and Vojtech Huser and Chris Knoll and Ajit Londhe and Taha Abdul-Basser and Anthony Molinaro},
#>     year = {2023},
#>     note = {R package version 1.7.1},
#>   }
```

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

### List Achilles Analysis Categories

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.html

Displays the unique categories under which Achilles analyses are grouped. This provides an overview of the different domains covered by the analysis package. Requires the Achilles package and `getAnalysisDetails()`.

```r
details <- Achilles::getAnalysisDetails()
unique(details$CATEGORY)
```

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

### List Non-Default Achilles Analyses

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.html

Retrieves a list of Achilles analyses that are not run by default, showing their IDs and names. This helps in identifying custom analyses that can be enabled. Requires the Achilles package and the `getAnalysisDetails()` function.

```r
details <- Achilles::getAnalysisDetails()
details[details$IS_DEFAULT == 0,c(1,5)]
```

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

### Run Selective Achilles Analyses (R)

Source: https://context7.com/ohdsi/achilles/llms.txt

Allows execution of specific Achilles analyses by providing a vector of `analysisIds` instead of running the complete default set. This function can also be configured to not drop existing results tables (`createTable = FALSE`) and only update the specified analyses (`updateGivenAnalysesOnly = TRUE`). It requires database connection details, CDM and results schemas, and an output folder.

```r
library(Achilles)

# Get list of all available analyses
analysisDetails <- getAnalysisDetails()
head(analysisDetails)
#   analysis_id analysis_name category
#   1           Number of persons Person
#   2           Number of persons by gender Person
#   ...

# Run only person and observation period analyses (IDs 1-199)
connectionDetails <- DatabaseConnector::createConnectionDetails(
  dbms = "postgresql",
  server = "localhost/cdm",
  user = "user",
  password = "pass"
)

achillesResults <- achilles(
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = "cdm",
  resultsDatabaseSchema = "results",
  analysisIds = c(1:20, 101:120),  # Specific analysis IDs
  createTable = FALSE,              # Don't drop existing results
  updateGivenAnalysesOnly = TRUE,   # Only update specified analyses
  outputFolder = "output"
)
```

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

### List and Run Missing Analyses with Achilles R Package

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.md

This section shows how to identify and execute analyses that are either missing or newly added to the Achilles package. The 'listMissingAnalyses' function is used to display which analyses are not yet run, and 'runMissingAnalyses' executes these identified analyses. Note that 'runMissingAnalyses' does not delete previously generated data.

```r
Achilles::listMissingAnalyses(connectionDetails, resultsSchema)
```

```r
Achilles::runMissingAnalyses(
  connectionDetails     = connectionDetails,
  cdmDatabaseSchema     = cdmSchema,
  resultsDatabaseSchema = resultsSchema,
  outputFolder          = "your output folder"
)
```

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

### Export VISIT_DETAIL Report to JSON

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/exportVisitDetailToJson.html

This function exports the VISIT_DETAIL report data from the Achilles analysis results into JSON files. It requires connection details to the database, schema names for the CDM, results, and vocabulary, and a path to save the output JSON files. The function is useful for generating machine-readable reports from Achilles analyses.

```r
exportVisitDetailToJson(
  connectionDetails,
  cdmDatabaseSchema,
  resultsDatabaseSchema,
  outputPath,
  vocabDatabaseSchema = cdmDatabaseSchema
)
```

```r
if (FALSE) {
connectionDetails <- DatabaseConnector::createConnectionDetails(dbms = "sql server",
                                                                    server = "yourserver")
exportVisitDetailToJson(connectionDetails,
                            cdmDatabaseSchema = "cdm4_sim",
                            outputPath = "your/output/path")
}
```

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

### Achilles - Generate Descriptive Statistics

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/achilles.html

The `achilles` function in the Achilles R package generates a descriptive statistics summary for an entire OMOP CDM instance. It allows for customization of database schemas, analysis IDs, and output options.

```APIDOC
## achilles()

### Description
Generates descriptive statistics summary for an entire OMOP CDM instance.

### Method
R function call

### Endpoint
N/A (R function)

### Parameters
#### Arguments
- **connectionDetails** (object) - An R object of type `connectionDetails` created using the function `createConnectionDetails` in the `DatabaseConnector` package.
- **cdmDatabaseSchema** (string) - Fully qualified name of database schema that contains OMOP CDM schema. On SQL Server, this should specify both the database and the schema, e.g., 'cdm_instance.dbo'.
- **resultsDatabaseSchema** (string) - Fully qualified name of database schema where final results can be written. Default is `cdmDatabaseSchema`. On SQL Server, e.g., 'cdm_results.dbo'.
- **scratchDatabaseSchema** (string) - Fully qualified name of the database schema for intermediate scratch tables. Default is `resultsDatabaseSchema`. Must be accessible to/from `cdmDatabaseSchema` and `resultsDatabaseSchema`. Using '#' will run Achilles in single-threaded mode with temporary tables.
- **vocabDatabaseSchema** (string) - String name of database schema containing OMOP Vocabulary. Default is `cdmDatabaseSchema`. On SQL Server, e.g., 'results.dbo'.
- **tempEmulationSchema** (string) - For databases like Oracle, specify the name of the database schema for temporary tables. Requires create/insert permissions.
- **sourceName** (string) - String name of the data source. If blank, CDM_SOURCE table will be queried.
- **analysisIds** (vector, optional) - A vector containing the set of Achilles analysisIds to generate. If not specified, all analyses will be executed. Use `getAnalysisDetails()` to get a list of analyses and their IDs.
- **createTable** (boolean) - If TRUE, new results tables will be created in the results schema. If FALSE, tables are assumed to exist.
- **smallCellCount** (integer) - Cells with counts less than or equal to this value are deleted to avoid patient identification. Set to 0 for complete summary.
- **cdmVersion** (string) - Define the OMOP CDM version used. Currently supports v5 and above (e.g., '5', '5.3').
- **createIndices** (boolean) - Determines if indices should be created on the resulting Achilles tables. Default is TRUE.
- **numThreads** (integer, optional) - The number of threads to use for parallel execution. Default is 1.
- **tempAchillesPrefix** (string, optional) - The prefix for scratch Achilles analyses tables in multi-threaded mode. Default is "tmpach".
- **dropScratchTables** (boolean, optional) - If TRUE, drop scratch tables after execution (may take time). If FALSE, leave them in place. Default is TRUE.
- **sqlOnly** (boolean) - If TRUE, only generate SQL files without execution. If FALSE, run Achilles. Default is FALSE.
- **outputFolder** (string) - Path to store logs and SQL files.
- **verboseMode** (boolean) - Determines if console output shows all execution steps. Default is TRUE.
- **optimizeAtlasCache** (boolean) - Determines if the Atlas cache needs to be optimized. Default is FALSE.
- **defaultAnalysesOnly** (boolean) - If TRUE, only default analyses are run. Including non-default analyses is more resource-intensive. Default is TRUE.
- **updateGivenAnalysesOnly** (boolean) - Updates only the specified analyses.
- **excludeAnalysisIds** (vector, optional) - A vector containing analysis IDs to exclude from execution.
- **sqlDialect** (string, optional) - The SQL dialect to use.

### Request Example
```R
# Example R code (not a direct API request)
achilles(
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = "cdm_5_3.dbo",
  resultsDatabaseSchema = "cdm_5_3_results.dbo",
  analysisIds = c(1, 2, 3)
)
```

### Response
N/A (R function execution results in tables and logs)
```

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

### Export Achilles Visit Report to JSON (R)

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/exportVisitToJson.html

This R function exports the Achilles Visit report into a JSON format. It requires connection details to the database, the CDM schema, the results schema, and an output path for saving the JSON files. Optionally, a vocabulary schema can be specified.

```R
exportVisitToJson(
  connectionDetails,
  cdmDatabaseSchema,
  resultsDatabaseSchema,
  outputPath,
  vocabDatabaseSchema = cdmDatabaseSchema
)
```

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

### Run Multi-Threaded Achilles for Large Databases (R)

Source: https://context7.com/ohdsi/achilles/llms.txt

Optimizes Achilles execution for large OMOP CDM databases on MPP platforms by utilizing parallel processing. This function requires database connection details, CDM and results schemas, a scratch database schema, source name, CDM version, and specifies the number of threads. It may create temporary scratch tables during execution that are merged into the final results.

```r
library(Achilles)

connectionDetails <- DatabaseConnector::createConnectionDetails(
  dbms = "redshift",
  server = "redshift-cluster.amazonaws.com",
  user = "admin",
  password = "password",
  port = 5439
)

# Run Achilles with 10 parallel threads
achillesResults <- achilles(
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = "cdm_schema",
  resultsDatabaseSchema = "results_schema",
  scratchDatabaseSchema = "scratch_schema",
  sourceName = "Large Claims Database",
  cdmVersion = "5.4",
  numThreads = 10,
  tempAchillesPrefix = "tmpach",
  dropScratchTables = TRUE,
  outputFolder = "output",
  createIndices = TRUE,
  smallCellCount = 5
)

# Multi-threaded mode creates permanent scratch tables during execution
# and merges them into final results tables
```

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

### POST /achilles/validateSchema

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/validateSchema.html

Validates the CDM schema against OMOP CDM v5.x standards. This function checks the structure and content of the CDM to ensure it meets the required specifications. It can optionally generate SQL files without execution or run the full validation process.

```APIDOC
## POST /achilles/validateSchema

### Description
Validates the CDM schema against OMOP CDM v5.x standards. This function checks the structure and content of the CDM to ensure it meets the required specifications. It can optionally generate SQL files without execution or run the full validation process.

### Method
POST

### Endpoint
/achilles/validateSchema

### Parameters
#### Request Body
- **connectionDetails** (object) - Required - An R object of type `connectionDetails` created using the function `createConnectionDetails` in the `DatabaseConnector` package.
- **cdmDatabaseSchema** (string) - Required - The name of the database schema that contains the OMOP CDM. On SQL Server, this should specify both the database and the schema (e.g., 'cdm_instance.dbo').
- **resultsDatabaseSchema** (string) - Optional - The fully qualified name of the database schema where the cohort table is written. Defaults to `cdmDatabaseSchema`. On SQL Server, this should specify both the database and the schema (e.g., 'cdm_results.dbo').
- **cdmVersion** (string) - Required - Defines the OMOP CDM version used (e.g., '5', '5.3'). Currently supports v5 and above.
- **runCostAnalysis** (boolean) - Optional - Determines if cost analysis should be run. Note: only works on CDM v5 and v5.1.0+ style cost tables.
- **outputFolder** (string) - Required - Path to store logs and SQL files.
- **sqlOnly** (boolean) - Optional - If TRUE, only generates SQL files; if FALSE, runs Achilles. Defaults to FALSE.
- **verboseMode** (boolean) - Optional - If TRUE, displays all execution steps in the console. Defaults to TRUE.

### Request Example
```json
{
  "connectionDetails": {"some_key": "some_value"}, 
  "cdmDatabaseSchema": "cdm_schema.dbo",
  "resultsDatabaseSchema": "results_schema.dbo",
  "cdmVersion": "5.3",
  "runCostAnalysis": true,
  "outputFolder": "/path/to/output",
  "sqlOnly": false,
  "verboseMode": true
}
```

### Response
#### Success Response (200)
- **validationStatus** (string) - Indicates the status of the schema validation (e.g., 'SUCCESS', 'FAILED').
- **messages** (array) - An array of messages related to the validation process.

#### Response Example
```json
{
  "validationStatus": "SUCCESS",
  "messages": [
    "CDM schema validation completed successfully.",
    "All checks passed for CDM version 5.3."
  ]
}
```
```

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

### Fetch Achilles Heel Results in R

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/fetchAchillesHeelResults.html

This R code snippet demonstrates how to use the fetchAchillesHeelResults function. It requires the DatabaseConnector package to create connection details and the Achilles package for the analysis. The function takes connection details and the results database schema as arguments and returns a table of data quality issues.

```r
if (FALSE) {
  connectionDetails <- DatabaseConnector::createConnectionDetails(dbms="sql server", server="myserver")
  achillesResults <- achilles(connectionDetails, "cdm5_sim", "scratch", "TestDB")
  fetchAchillesHeelResults(connectionDetails, "scratch")
}
```

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

### exportVisitDetailToJson Function

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/exportVisitDetailToJson.html

Exports the VISIT_DETAIL report generated by Achilles into a JSON format, suitable for web-based reporting.

```APIDOC
## exportVisitDetailToJson

### Description
Exports Achilles VISIT_DETAIL report into a JSON form for reports.

### Method
Not Applicable (R Function)

### Endpoint
Not Applicable (R Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```R
exportVisitDetailToJson(
  connectionDetails,
  cdmDatabaseSchema = "cdm4_sim",
  outputPath = "your/output/path"
)
```

### Response
#### Success Response (200)
This function does not return a value (returns `none`). Its primary effect is the creation of JSON files.

#### Response Example
None (file output)
```

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

### Retrieve Monthly Temporal Analysis Data (R)

Source: https://github.com/ohdsi/achilles/blob/main/docs/reference/getTemporalData.html

The getTemporalData function retrieves monthly analysis data for temporal characterization from an OMOP CDM database. It requires connection details, CDM schema, and results schema. Optional arguments include specific analysis IDs or a concept ID. The function returns a data frame of query results, assuming Achilles has already been run. Supported monthly analyses include Visit Occurrence, Condition Occurrence, Procedure Occurrence, Drug Exposure, Observation, Measurement, and Device.

```r
getTemporalData(
  connectionDetails,
  cdmDatabaseSchema,
  resultsDatabaseSchema,
  analysisIds = NULL,
  conceptId = NULL
)
```

```r
if (FALSE) {
  pneumonia <- 255848
  monthlyResults <- getTemporalData(connectionDetails = connectionDetails,
                                    cdmDatabaseSchema = "cdm",

      resultsDatabaseSchema = "results", conceptId = pneumonia)
}
```

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

### Skip All Analyses for a Table with Achilles (R)

Source: https://github.com/ohdsi/achilles/blob/main/extras/notes.html

This snippet demonstrates how to skip all analyses related to a specific table by retrieving the analysis IDs for that table's category and using the 'excludeAnalysisIds' parameter.

```r
details   <- Achilles::getAnalysisDetails()
skipThese <- details[details$CATEGORY == "Drug Exposure",]$ANALYSIS_ID

Achilles::achilles(
  connectionDetails     = connectionDetails,
  cdmDatabaseSchema     = cdmDatabaseSchema,
  resultsDatabaseSchema = resultsDatabaseSchema,
  excludeAnalysisIds    = skipThese,
  outputFolder          = "your output folder"
)
```

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

### Optimize Atlas Cache Tables

Source: https://context7.com/ohdsi/achilles/llms.txt

Creates optimized cache tables that join results with vocabulary data to improve the performance of the Atlas application. This function creates the `achilles_results_concept_count` table specifically for Atlas queries.

```r
library(Achilles)

connectionDetails <- DatabaseConnector::createConnectionDetails(
  dbms = "postgresql",
  server = "localhost/cdm",
  user = "user",
  password = "pass"
)

# Create optimized cache tables joining results with vocabulary
optimizeAtlasCache(
  connectionDetails = connectionDetails,
  resultsDatabaseSchema = "results",
  vocabDatabaseSchema = "vocabulary",
  outputFolder = "output",
  tempAchillesPrefix = "tmpach",
  verboseMode = TRUE
)

# Creates achilles_results_concept_count table optimized for Atlas queries
```