CPIC Collection of KOs

GitHub release CircleCI

This is a collection of objects that focus on dosing guidelines as provided by the CPIC pharmacogenomic guidelines. These objects generally take allele pairs as inputs and return the corresponding drug selection or dosing guideline recommendation based on a patient's alleles.


The current release of CPIC collection of knowledge objects is GitHub release

This release contains 37 KOs, including 28 drug recommendation KOs, 7 geno-to-pheno KOs and two look-up table KOs.

The collection of CPIC KOs can be easily deployed through CPIC Kit.

CPIC Knowledge Objects (KO)

CPIC KO Design

CPIC collection consists of three types of KOs:


This type of KO is gene-specific. It will determine the phenotype based on the gene's diplotypes

There are two groups within this type of KO:

  • CYP2D6, CYP2C19 and UGT1A1: Each gene has a spreadsheet mapping the dipltotype directly to the phenotype;

  • CYP2C9, CYP3A5, SLCO1B1 and TPMT: Each gene has a allele-definition spreadsheet for the functional status of the allele. The alleles in the diplotype are checked on the functional status. The likely phenotype is then determined based on the functional status of both alleles.

Endpoint: /phenotype

Input Example:

{ "CYP2D6" : "*1/*1" }

Output Example (Only the result of the response is shown):

  "CYP2D6": {
    "diplotype": "*1/*1",
    "phenotype": "Normal metabolizer"

Drug recommendations

The drug recommendation KO is drug-specific. It will provide the recommendation based on the information of relevant gene(s). The combination of information includes:

  • single gene allele
  • multiple gene allele
  • one gene allele and one gene phenotype
  • single gene phenotype
  • multiple gene phenotypes

The drug recommendation KO will take the phenotype panel as input, extract the needed gene and provide recommendation output.

Endpoint: /dosingrecommendation

Input Example:

  "CYP2C19": {
      "diplotype": "*1/*1",
      "phenotype": "Normal metabolizer"
  "CYP2D6": {
    "diplotype": "*1/*1",
    "phenotype": "normal metabolizer"

Output Example (Only the result of the response is shown):

  "type": "CPIC Recommendation",
  "drug": "Codeine",
  "genes": {
    "CYP2D6": {
      "diplotype": "*1/*1",
      "phenotype": "normal metabolizer"
  "recommendation": {
    "implication": "Normal morphine formation",
    "content": "Use label-recommended age- or weight-specific dosing.",
    "classification": "Strong"

Look-up table

The look-up table KO provides the KO ark ids for either the genes or the drugs of interest.

Endpoint for geno-to-pheno table: /genophenokolist

Input for geno-to-pheno table:


Output for geno-to-pheno table:

 "CYP2D6": "/99999/fk49z9gr7p/v0.0.6",
 "CYP2C19": "/99999/fk4mc97w0h/v0.0.4",
 "UGT1A1": "/99999/fk47h1x090/v0.0.4",

Endpoint for drug list table: /druglist

Input for drug list table:

  "codeine": "",
  "atazanavir": "",

Output for drug list table:

   "codeine": "/99999/fk4mc97w6m/v0.0.5",
   "atazanavir": "/99999/fk4d79nq4z/v0.0.5",

Note: For drug list table, a input of empty object {} will produce the output containing the list of all available KOs.

CPIC KO Descriptions

Genotype to Phenotype

Currently, the following genes' phenotypes can be determined based on their diplotypes by the respective knowledge objects, as included in the cpic-kit.

  1. CYP2C19

  2. CYP2C9

  3. CYP2D6

  4. CYP3A5

  5. SLCO1B1

  6. TPMT

  7. UGT1A1

Drug Recommendation

Currently, the following drug recommendations are available as knowledge objects and included in the CPIC-kit.

  1. Abacavir (based on HLA-B allele information)

  2. Allopurinol (based on HLA-B allele information)

  3. Amitriptyline (based on CYP2C19 and CYP2D6 phenotypes)

  4. Atazanavir (based on UGT1A1 phenotype)

  5. Azathioprine (based on TPMT phenotype)

  6. Carbamazepine (based on HLA-A and HLA-B allele information)

  7. Citalopram (based on CYP2C19 phenotype)

  8. Clomipramine (based on CYP2C19 and CYP2D6 phenotypes)

  9. Clopidogrel (based on CYP2C19 phenotype)

  10. Codeine (based on CYP2D6 phenotype)

  11. Desipramine (based on CYP2D6 phenotype)

  12. Doxepin (based on CYP2C19 and CYP2D6 phenotypes)

  13. Escitalopram (based on CYP2C19 phenotype)

  14. Fluvoxamine (based on CYP2D6 phenotype)

  15. Imipramine (based on CYP2C19 and CYP2D6 phenotypes)

  16. Mercaptopurine (based on TPMT phenotype)

  17. Nortriptyline (based on CYP2D6 phenotype)

  18. Ondansetron (based on CYP2D6 phenotype)

  19. Oxcarbazepine (based on HLA-B allele information)

  20. Paroxetine (based on CYP2D6 phenotype)

  21. Phenytoin (based on CYP2C9 phenotype and HLA-B allele information)

  22. Sertraline (based on CYP2C19 phenotype)

  23. Simvastatin (based on SLCO1B1 phenotype)

  24. Tacrolimus (based on CYP3A5 phenotype)

  25. Thioguanine (based on TPMT phenotype)

  26. Trimipramine (based on CYP2C19 and CYP2D6 phenotypes)

  27. Tropisetron (based on CYP2D6 phenotype)

  28. Voriconazole (based on CYP2C19 phenotype)

Deploying the CPIC KOs

CPIC KOs are individually available for access and deployment.

The collection of CPIC KOs can also be easily deployed through CPIC Kit. The kit packages Activator, Library and CPIC Demo Site. The kit is designed as a personal CPIC Knowledge Grid used to explore the capabilities of KGrid and CPIC Knowledge Objects.

Trying the CPIC KOs

From this guide, you can follow the step-by-step instruction to try these CPIC KOs:

  • Click on the gene or drug from the KO list. The link will open the KO page in the library.
  • Click on 'Live Demo'. The library will deploy the KO to the default activator or your choice and provide the links for trying the KO in Swagger UI
  • Click on the selected link will open the KO's service description in Swagger UI or Swagger Editor. (More information on Swagger UI)

Workflow for using CPIC KOs

Here is an example workflow showing how the CPIC KOs is used:

  1. Start a patient's genetic panel;
  2. Use the genetic panel as input to retrieve the geno-to-pheno KO ids from the geno-to-pheno look-up table KO;
  3. Send an object with drug information as input to retrieve all recommendation KO ids from the recommendation look-up table KO;
  4. Send the genetic panel to each geno-to-pheno KO to determine the phenotype for the respective gene;
  5. Aggregate the results from the geno-to-pheno KOs and send to each recommendation KO;
  6. Each recommendation KO will return the recommendation if required genetic information is available in input.

In Step 3, different inputs can be used for different scenarios, such as:

  • Use an empty object {} as input, to check all relevant drugs' dosing recommendations

  • Use an object containing the patient's current prescription e.g.{"codeine":"", ...} as input, to check the dosing recommendations

  • Use an object containing a specific drug, e.g.{"codeine":""} as input, to check the dosing recommendations for the drug of interest



Unit Tests

The KO Unit Test are located in the /tests directory. These tests utilize Jest and rewire. Jest provides the testing framework and rewire allows the tests to access the javascript function without the convenience of the export modules (KGrid Javascript adapter limitation). You can execute the tests via npm

npm test

Integration Tests

We test the CPIC KO endpoints in a KGrid Activator instance using Postman and Newman. The CPIC integration tests are defined in the /tests/postman/cpic_integration_tests.postman_collection.json.The CI script uses the start server and test library to:

  1. downloads the latest KGrid Activator
  2. runs the activator with the CPIC KOs
  3. runs the Postman collection defined as the CPIC integration tests using Newman
npm run ci

Performance Tests

We have some performance/load testing scripts that utilize k6, a load testing tool. Details on CPIC load/performance testing can be found in the k6 readme


CPIC Knowledge Objects, just as other KOs, can be compressed individually into zip file, and then deposited into a KGrid library, for example, KGRID Sandbox Library

CPIC Knowledge Objects are released in as a collection in the form of a single zip file, such as cpic-all.zip on GitHub release

Last Updated: 2/15/2019, 6:13:36 PM