The changes in this section pertain to additions to the Automated Characterization of Health Information at Large-scale Longitudinal Evidence Systems (ACHILLES) R Package for OMOP CDM v5 databases introduced in the v1.5.0 release. If you are setting up WebAPI/Atlas v2.2.0 or later to work with an OMOP CDM v5, please read this section to ensure all of the dependencies required are established otherwise aspects of WebAPI/Atlas may not work.

Click here for more information on Achilles.

ACHILLES is a platform which enables the characterization, quality assessment and visualization of observational health databases. With the release of V1.5.0, additional methods and resulting tables were added to aid in the performance when querying Achilles results from WebAPI/Atlas. This article will detail the changes and the steps to take to upgrade to WebAPI/Atlas V2.2.0 or later.

If you complete a full run of Achilles v.1.5.0 on your OMOP CDM v5 with the default settings, you will not need to complete any of the steps in this article. If you have an OMOP CDM v5 and you ran Achilles in the past (prior to v.1.5.0) then you will need to read and complete the steps below to work with WebAPI/Atlas V2.2.0. If you'd like to run a command to apply all of the new changes, scroll to the bottom of the article.

Resources:

• Achilles source code and installation instructions: https://github.com/OHDSI/Achilles
• Achilles releases: https://github.com/OHDSI/Achilles/releases

The following sections will describe the additions in Achilles V1.5.0, how to verify if you have the additional dependencies required by WebAPI/Atlas and how to run Achilles R commands to make your Achilles installation compatible with WebAPI/Atlas V2.2.0. Each section will describe the changes and how to make each change individually. If you would like to apply all of the changes in a single step, skip to the bottom as this can be done in a single command.

Achilles will now construct a new table in the results schema labeled concept_hierarchy using the OMOP vocabulary found in the CDM. This one-time operation is used to optimize query performance when by WebAPI against the ACHILLES_results table.

Please Note: If you update the vocabulary in your CDM, you should re-create (and re-index) the concept_hierarchy table.

Connect to your CDM's RDBMS and browse the schema holding your Achilles results. If you do not see the concept_hierarchy table, you will need to execute the following R code:

connectionDetails <- DatabaseConnector::createConnectionDetails(dbms = "postgresql",
                                                           server = "localhost/ohdsi",
                                                           user = "joe",
                                                           password = "supersecret")  
cdmVocabSchema <- "my_cdm_schema"
resultsSchema <- "my_results_schema_goes_here"
hierarchy <- Achilles::conceptHierarchy(connectionDetails,
                                        vocabDatabaseSchema=cdmVocabSchema,
                                        resultsDatabaseSchema=resultsSchema)
                                        

The commands above will allow you to specify the connect to your CDM database, the database schemas that hold the CDM vocabulary and results respectively and the command to construct the concept_hierarchy table.

Achilles will index the results and concept_hierarchy to optimize query performance. While this step is not mandatory to ensure compatibility with WebAPI/Atlas, it is highly recommended.

Connect to your CDM's RDBMS and browse the schema holding your Achilles results. If the ACHILLES_results, ACHILLES_results_dist and concept_hierarchy are missing indicies, you can create them using the following command:

connectionDetails <- DatabaseConnector::createConnectionDetails(dbms = "postgresql",
                                                           server = "localhost/ohdsi",
                                                           user = "joe",
                                                           password = "supersecret")  
resultsSchema <- "my_results_schema_goes_here"
createIndices <- Achilles::createIndices(connectionDetails = connectionDetails,
                                         resultsDatabaseSchema = resultsSchema)
                                                                

While these analyses are not mandatory to run WebAPI/Atlas 2.2, these new analyses will be surfaced in Atlas. These new analyses will compute the distribution of a concept, how often the concept is used and the percentage of people with the count of that concept.

The following command will be used to create these new analyses:

connectionDetails <- DatabaseConnector::createConnectionDetails(dbms = "postgresql",
                                                           server = "localhost/ohdsi",
                                                           user = "joe",
                                                           password = "supersecret")  
cdmDatabaseSchema <- "my_cdm_schema_goes_here"
resultsDatabaseSchema <- "my_results_schema_goes_here"
vocabDatabaseSchema <- "my_vocabulary_schema_goes_here"
db <- "my_cdm_database_name"
achillesResults <- Achilles::achilles(connectionDetails,
                                cdmDatabaseSchema = cdmDatabaseSchema,
                                oracleTempSchema = NULL,
                                resultsDatabaseSchema = resultsDatabaseSchema,
                                sourceName = db,
                                analysisIds = c(691,791,891,1891),
                                createTable = FALSE,
                                smallcellcount = 5,
                                cdmVersion = "5",
                                runHeel = FALSE,
                                validateSchema = FALSE,
                                vocabDatabaseSchema = vocabDatabaseSchema,
                                runCostAnalysis = FALSE,
                                sqlOnly = FALSE, 
                                conceptHierarchy = FALSE,
                                createIndices = FALSE)
                                        

Please note the command above sets both the conceptHierarchy and createIndices parameters to FALSE.

The following command can be used to apply all of the changes above in a single step:

connectionDetails <- DatabaseConnector::createConnectionDetails(dbms = "postgresql",
                                                           server = "localhost/ohdsi",
                                                           user = "joe",
                                                           password = "supersecret")  
cdmDatabaseSchema <- "my_cdm_schema_goes_here"
resultsDatabaseSchema <- "my_results_schema_goes_here"
vocabDatabaseSchema <- "my_vocabulary_schema_goes_here"
db <- "my_cdm_database_name"
achillesResults <- Achilles::achilles(connectionDetails,
                                cdmDatabaseSchema = cdmDatabaseSchema,
                                oracleTempSchema = NULL,
                                resultsDatabaseSchema = resultsDatabaseSchema,
                                sourceName = db,
                                analysisIds = c(691,791,891,1891),
                                createTable = FALSE,
                                smallcellcount = 5,
                                cdmVersion = "5",
                                runHeel = FALSE,
                                validateSchema = FALSE,
                                vocabDatabaseSchema = vocabDatabaseSchema,
                                runCostAnalysis = FALSE,
                                sqlOnly = FALSE, 
                                conceptHierarchy = TRUE,
                                createIndices = TRUE)