ARES Documentation

Background

ARES is A Research Exploration System designed for use in the study of patient level observational data that has been converted into the Observational Medical Outcomes Partnership (OMOP) Common Data Model (CDM). ARES was developed by Frank DeFalco, a member of the Observational Health Data Sciences & Informatics (OHDSI) community.

OHDSI

The Observational Health Data Sciences and Informatics (or OHDSI, pronounced "Odyssey") program is a multi-stakeholder, interdisciplinary collaborative to bring out the value of health data through large-scale analytics. All our solutions are open-source. Learn more about OHDSI.

Installation

Requirements

git client (GitHub Desktop recommended). On macOS git comes preinstalled and can be accessed via the Terminal app. On linux systems might require installation using the appropriate package manager.
Node.js v18 or higher is required. Download link
NPM (node package manager) - installed by default with Node.js

Installation Steps

Using pre-built files

Open the Ares releases page and download the latest available release (Ares.x.x-beta.zip), unpack the zip archive and serve using your favourite web server.

Here's an example running Ares using the "http-server" web server:

    npm install -g http-server #download and install the http-server web server
    
    http-server aresFolder #replace with the name of the folder containing Ares files

The link to the app will be available within the terminal once the http-server is launched.

Building manually

Begin by downloading the source code for the ARES web application, which can be obtained by cloning the repository found on Github.

   git clone https://github.com/ohdsi/ares

Once the repository is cloned locally the application can be built by using npm. These steps should be run from a bash shell or command prompt and are as follows:

   cd aresDirectory #navigate to the directory Ares was cloned into
   npm install #install Ares dependencies
   npm run build -- --base=/ # Build the app. Replace "/" if you wish to run Ares within a subdirectory

The "--base" option is used to specify the base public path of the app. The default value is " /ares/" in case this option is not indicated.

The npm build process will create an output directory named "/dist" which will contain all files required for the ARES web application. These files should be placed in a directory that is served by any web server (like http-server), typically deployed in an "/ares" subdirectory (you can override that with the " --base" option as shown above.

Running in dev mode

The app could also be launched in dev mode and served by the built-in web server instantly. Run the following after cloning the repo and running "npm install"

   npm run serve

Once the server is running, the app will be available at http://localhost:8080/ares (port 8080 is the default value and might be different if it's already being used by another app).

After completing the deployment of the web application the data files for ARES must be placed in the "/data" subfolder within the "/yourAresDirectory/public/" directory. The ARES data files are generated from your existing OMOP CDM database and require both Achilles and DataQualityDashboard.

Here's an example script to generate Ares files (replace connectionDetails with your own)

# DatabaseConnector::downloadJdbcDrivers("postgresql","./") - use it to download the JDBC driver
options(connectionObserver = NULL)

cdmDatabaseSchema = "cdm"
resultsDatabaseSchema = "results" # used to store Achilles output
vocabDatabaseSchema = "cdm" #usually located within the cdm schema
numThreads = 1
cdmSourceName = 'synthea'
cdmVersion = "5.4"

aresDataDirectory = "./data" #Achilles output directory

#connectionDetails <- Eunomia::getEunomiaConnectionDetails() #Provides a sample dataset

connectionDetails <- DatabaseConnector::createConnectionDetails(
  dbms     = "postgresql",
  server   = "localhost/synthea",
  user     = "postgres",
  password = "12345",
  port     = 5432,
  pathToDriver = "./" #indicate path to your chosen dbms JDBC driver
) #Used to connect to your existing CDM

# Run Achilles
Achilles::achilles(
  connectionDetails,
  cdmDatabaseSchema = cdmDatabaseSchema ,
  resultsDatabaseSchema= resultsDatabaseSchema,
  vocabDatabaseSchema = vocabDatabaseSchema,
  numThreads = 1,
  cdmVersion = cdmVersion,
  createIndices = F,
  createTable = T,
  smallCellCount = 0,
)

# Export Achilles results to Ares supported format
Achilles::exportToAres(
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = cdmDatabaseSchema,
  resultsDatabaseSchema = resultsDatabaseSchema,
  vocabDatabaseSchema = vocabDatabaseSchema,
  outputPath = aresDataDirectory,
)

sourceReleaseKey = AresIndexer::getSourceReleaseKey(connectionDetails, cdmDatabaseSchema)
datasourceReleaseOutputFolder <- file.path(aresDataDirectory, sourceReleaseKey)

#Run data quality checks
DataQualityDashboard::executeDqChecks(
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = cdmDatabaseSchema,
  resultsDatabaseSchema = resultsDatabaseSchema,
  vocabDatabaseSchema = vocabDatabaseSchema,
  cdmSourceName = cdmSourceName,
  numThreads = numThreads,
  outputFolder = datasourceReleaseOutputFolder,
  outputFile = "dq-result.json",
  verboseMode = T,
  writeToTable = F,
  cdmVersion = cdmVersion

)
# Run Achilles temporal characterization
outputFile <- file.path(datasourceReleaseOutputFolder, "temporal-characterization.csv")
Achilles::performTemporalCharacterization(
  connectionDetails = connectionDetails,
  cdmDatabaseSchema = cdmDatabaseSchema,
  resultsDatabaseSchema = resultsDatabaseSchema,
  outputFile = outputFile,
)

# Get a list of sources generated by the exportToAres function
list <- list.dirs(aresDataDirectory, recursive = FALSE)

# Augment concept files with data quality details
AresIndexer::augmentConceptFiles(releaseFolder = file.path(aresDataDirectory, cdmSourceName, sourceReleaseKey))
# Export index of all sql functions used in data processing
AresIndexer::buildExportQueryIndex(aresDataDirectory)
# Compare data quality issues with previous source releases (used to display the issue delta)
AresIndexer::augmentDataQualityFiles(sourceFolders = list)
# Create index of quality issues across releases (used to render data quality delta chart)
AresIndexer::buildSourceDataQualityDelta(sourceFolders = list)
# Create index of all available sources and releases
AresIndexer::buildNetworkIndex(list, outputFolder = aresDataDirectory)
# Create quality index across network
AresIndexer::buildDataQualityIndex(list, outputFolder = aresDataDirectory)
# Create index of unmapped source codes across the network
AresIndexer::buildNetworkUnmappedSourceCodeIndex(list, outputFolder = aresDataDirectory)

Visiting the ARES website will now show the data results for your current network. Each individual CDM needs to be processed in order for it to be available in ARES. CDM data sources with the same source name will be versioned using the release key allowing analysis across multiple versions of the same data source. An example of generating a complete network of different data sources and loading them into ARES can be found here.

A - Lowest value
B - Lower Quartile (25%)
C - Median (50%)
D - Upper Quartile (75%)
E - Highest Value

Achilles
Data Quality Dashboard
Database Connector
Sql Render
Castor

Open Source Ecosystem

ARES leverages many open source libraries and tools to achieve its goals without which the task would be entirely insurmountable.

Vue
PrimeVue
axios
Vega
Vega-lite
vega-embed
codemirror
d3
markdown-it
markdown-it-vue
npm
lodash
Material Design

Acknowledgements

Many people have provided valuable feedback in the development of ARES.

Clair Blacketer
Alan Andryc
Patrick Ryan