README.md

GIST v3.0

An OMOP CDM Based Automatic Clinical Trial Generalizability Assessment Framework.

Table of Content

• Installation
• Usage
• Config
• Main Packages Used
• Notes
  • Entities
• Databases
  • Criteria Database
  • EHR Database
• Previous Implementation
• Paper
• Contributing
• License

Installation

1. Clone this repository.

git clone https://github.com/thisisibrahimd/gist.git
cd gist

2. Create a virtual env.

python3 -m venv venv
source venv/bin/activate

3. Use the package manager pip to install dependencies.

pip3 install -r requirements.txt

4. Install gist cli (this will allow you run the gist command instead of python3 gist/cli.py .

pip3 install --editable .

Usage

By default, gist automatically grabs the following environment variables

GIST_DEBUG # boolean
GIST_EHR_CONN_STR # postgresql://username:password@hostname:port/database
GIST_CRIT_CONN_STR # postgresql://username:password@hostname:port/database
GIST_TRIAL_IDS # space delimited trial ids

Run trial NCT02885496 showing debug output

gist --debug --trial_id NCT02885496

Run trial NCT02885496 and NCT00562356 with out debug output

gist -t NCT02885496 -t NCT00562356

Run trial NCT02885496 and NCT00562356 with trial ids and debug env placed in .env. When all options/arguments are placed in the .env, you can just run gist in the terminal.

gist

Config

GIST needs two postgresql connection strings in your environment variables.

An example .env file to place in root

GIST_DEBUG=True
GIST_EHR_CONN_STR=postgresql://username:password@hostname:port/database
GIST_CRIT_CONN_STR=postgresql://username:password@hostname:port/database
GIST_TRIAL_IDS=NCT02885496 NCT00562356

Main Packages used

• Click to create the cli interface
• sqlalchemy as an ORM to simplify query generation
• python-dotenv to automatically grab envs from .env file(s).

Notes

Entities

Entities were generated with sqlacodegen and modifiyed to allowed for subqueryload of ehr data in the person entity.

condition_occurrence = relationship('ConditionOccurrence')
drug_exposure = relationship('DrugExposure')
procedure_occurrence = relationship('ProcedureOccurrence')
measurement = relationship('Measurement')
observation = relationship('Observation')

Databases

Criteria Database

GIST reads criteria in a certain schema. ddl can be found in the repo linked below.

criteria database

EHR Database

GIST currently supports OMOP CDM 5.2.2. It may work with later version but not for certain.

An synpuf database has been made available to test with gist.

Previous Implementation

• MATLAB
• JavaScript version 2
• Javascript version 3
• C# implementation with no interface

Paper

• GIST 2.0: A scalable multi-trait metric for quantifying population representativeness of individual clinical studies
• A knowledge base of clinical trial eligibility criteria

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

Apache 2.0