Skip to content

Instantly share code, notes, and snippets.

@kantale

kantale/EPGA_API.md

Created February 6, 2016 13:18
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save kantale/91c111d28925af640be6 to your computer and use it in GitHub Desktop.
Save kantale/91c111d28925af640be6 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
EPGA_API.md

Introduction

This is the API documentation of the www.epga.gr service.

fetch_init_json

URL: http://www.epga.gr/explore/fetch_init_json/ Return type: JSON

Returns a JSON string with all available genes - drugs interactions. This is a small sample from the returned JSON file:

{
    "HSPA5": {
        "Platinum compounds": {
            "alleles": [
                "rs430397"
            ], 
            "MSP": [
                "Unknown"
            ]
        }
    }, 
    "UGT1A": {
        "atazanavir, ritonavir": {
            "alleles": [
                "rs1042640", 
                "rs8330"
            ], 
            "MSP": [
                "Unknown", 
                "Unknown"
            ]
        }, 
        "acetaminophen": {
            "alleles": [
                "rs1042640", 
                "rs10929303", 
                "rs8330"
            ], 
            "MSP": [
                "Unknown", 
                "Unknown", 
                "Unknown"
            ]
        }
    },

This is a dictionary where the keys are gene names. Each entry contains sub-dictionaries. The keys of these dictionaries are drugs for which known gene-drug interactions exist. Each gene-drug interaction contains two lists. The first contains the "alleles" that are associated with this interaction. The second contains the Metabolizer Status (MSP) (P is for processed) for each interaction. Available values are:

  • Intermediate Metabolizer
  • Ultrarapid Metabolizer
  • Extended Metabolizer
  • Intermediate Metabolizer
  • Unknown

These two lists are in concordance. The first value of the "alleles" list referes to the first value of the "MSP" list etc. For example from the example above we have the following interactions:

Gene Drug Alleles Metabolizer Status
HSPA5 Platinum compounds rs430397 Unknown
UGT1A atazanavir, ritonavir rs1042640 Unknown
UGT1A atazanavir, ritonavir rs8330 Unknown
UGT1A acetaminophen rs1042640 Unknown
UGT1A acetaminophen rs10929303 Unknown
UGT1A acetaminophen rs8330 Unknown

Use this call to acquire all available gene-drug interactions. The use the "recommendations" call (explained below) to acquire detailed recomendations.

recommendations

URL:

id1, id2, id3, id4 can be one of the following values: genes, drugs, ms, alleles

Return Type: JSON

Examples:

In general there are two kinds of recommendations:

Although the structure of the returned JSON is the same, the filled fields are different. We provide two examples, one for each type of recommendation.

Dosing Guidelines

Example after running: http://www.epga.gr/explore/recommendations/ms/Poor%20Metabolizer/alleles/*38_*44 :

{
    "gdr": [
        {
            "summaryHTML": "The CPIC Dosing Guideline for nortriptyline recommends a 25% dose reduction for CYP2D6 intermediate metabolizers. For CYP2D6 ultrarapid or poor metabolizers, an alternative drug may be considered.", 
            "url": "https://www.pharmgkb.org/guideline/PA166104998", 
            "alleles": [
                [
                    "*38/*44", 
                    "Poor Metabolizer", 
                    "Poor metabolizer (~5-10% of patients)", 
                    "Avoid tricyclics use due to potential for side effects. Consider alternative drug not metabolized by CYP2D6.If a tricyclic is warranted, consider 50% reduction of recommended starting dose. Utilize therapeutic drug monitoring to guide dose adjustments.At the time of the development of this recommendation, there is a lack of strong evidence available on the possible role of CYP2D6 in nortriptyline response in pediatric patient populations; however, there is no reason to suspect that CYP2D6 variant alleles would affect nortriptyline metabolism differently in children compared to adults. Please see below for full details of these guidelines, with supporting evidence and disclaimers.", 
                    "Greatly reduced metabolism of tricyclics to less active compounds when compared to extensive metabolizersHigher plasma concentrations will increase the probability of side effects", 
                    "An individual carrying only non-functional alleles", 
                    "0", 
                    "https://www.pharmgkb.org/views/annotationsForDiplotype.action?allele1=%2A38&allele2=%2A44&location=CYP2D6&guidelineId=PA166104998", 
                    []
                ]
            ], 
            "symbol": "CYP2D6", 
            "source": "CPIC", 
            "textHTML": "<p class=\"more\">There's more of this guideline. <a href=\"/guideline/PA166104998\">Read more.</a></p>", 
            "relatedDrug": "nortriptyline"
        }, 
        {
            "summaryHTML": "The CPIC Dosing Guideline for amitriptyline recommends an alternative drug for CYP2D6 or CYP2C19 ultrarapid metabolizers and for CYP2D6 poor metabolizers. Consider a 50% dose reduction for CYP2C19 poor metabolizers and a 25% dose reduction for CYP2D6 intermediate metabolizers.", 
            "url": "https://www.pharmgkb.org/guideline/PA166105006", 
            "alleles": [
                [
                    "*38/*44", 
                    "Poor Metabolizer", 
                    "Poor metabolizers (~5-10% of patients)", 
                    "Avoid tricyclic use due to potential for side effects. Consider alternative drug not metabolized by CYP2D6.If a tricyclic is warranted, consider 50% reduction of recommended starting dose. Utilize therapeutic drug monitoring to guide dose adjustments.At the time of the development of this recommendation, there is a lack of strong evidence available on the possible role of CYP2D6 in amitriptyline response in pediatric patient populations; however, there is no reason to suspect that CYP2D6 variant alleles would affect amitriptyline metabolism differently in children compared to adults. Please see below for full details of these guidelines, with supporting evidence and disclaimers.", 
                    "Greatly reduced metabolism of tricyclics to less active compounds when compared to extensive metabolizersHigher plasma concentrations will increase the probability of side effects", 
                    "An individual carrying only non-functional alleles", 
                    "0", 
                    "https://www.pharmgkb.org/views/annotationsForDiplotype.action?allele1=%2A38&allele2=%2A44&location=CYP2D6&guidelineId=PA166105006", 
                    []
                ]
            ], 
            "symbol": "CYP2D6", 
            "source": "CPIC", 
            "textHTML": "<p class=\"more\">There's more of this guideline. <a href=\"/guideline/PA166105006\">Read more.</a></p>", 
            "relatedDrug": "amitriptyline"
        }, 
        {
            "summaryHTML": "Alternate analgesics are recommended for CYP2D6 ultrarapid and poor metabolizers. A label recommended age- or weight-specific codeine dose is warranted for CYP2D6 extensive and intermediate metabolizers.", 
            "url": "https://www.pharmgkb.org/guideline/PA166104996", 
            "alleles": [
                [
                    "*38/*44", 
                    "Poor Metabolizer", 
                    "Poor Metabolizer (~5-10% of patients)", 
                    "Avoid codeine use due to lack of efficacy.Alternatives that are not affected by this CYP2D6 phenotype include morphine and non-opioid analgesics. Tramadol, and to a lesser extent hydrocodone and oxycodone, are not good alternatives because their metabolism is affected by CYP2D6 activity; these agents should be avoided.", 
                    "Greatly reduced morphine formation following codeine administration, leading to insufficient pain relief.", 
                    "An individual carrying no functional alleles.", 
                    "0", 
                    "https://www.pharmgkb.org/views/annotationsForDiplotype.action?allele1=%2A38&allele2=%2A44&location=CYP2D6&guidelineId=PA166104996", 
                    []
                ]
            ], 
            "symbol": "CYP2D6", 
            "source": "CPIC", 
            "textHTML": "<p class=\"more\">There's more of this guideline. <a href=\"/guideline/PA166104996\">Read more.</a></p>", 
            "relatedDrug": "codeine"
        }
    ], 
    "counter": 3, 
    "success": true
}

The description of this format is the following. Under gdr (Genes Drug Recommendations), there is a list of recommendations. Each recommendation has the following fields:

  • summaryHTML : The summary of this recommendation as it appears in pharmGKB
  • url : The URL of the recommendation in pharmGKB
  • alleles : This is a list of all alleles or diplotypes for the submitted query. Available fields are:
    • field 1: The alleles or diplotype name
    • field 2: The Metabolizer status Processed. This is so that the metabolizer status is one of the 5 values (Intermediate, Extensive, Poor, Ultrarapid, Unknown)
    • field 3: The raw Metabolizer Status un-processed as it appears in pharmGKB
    • field 4: The recommendation
    • field 5: The implications of the recommendation
    • field 6: The phenotype of the recommendation
    • field 7: The activity score of the recommendation
    • field 8: The URL. This is obsolete. PharmGKB removed direct access to Dosage Guidelines through URLs recently, so this link most likely will not work.
    • field 9: Possible Clinical Interactions (if available)
  • symbol : The Gene included in this recommendation
  • source : The source of the Guideline (CPIC, DPWG, PRO (Manualy curated by PharmGKB)).
  • textHTML : Additional HTML text for this guideline
  • relatedDrug : The drug included in this recommendation

Other fields returned in the top structure are:

  • counter : The number of returned recommendations
  • success: true/false . The success status of the performed query.

Clinical Annotations

Example after running: http://www.epga.gr/explore/recommendations/drugs/Enzymes/genes/A2M

{
    "gdr": [
        {
            "summaryHTML": "", 
            "url": "", 
            "alleles": [
                [
                    "rs669", 
                    "Unknown", 
                    "Unknown", 
                    "", 
                    "", 
                    "", 
                    "", 
                    "https://www.pharmgkb.org/clinicalAnnotation/1183615587", 
                    [
                        [
                            "3", 
                            "Efficacy", 
                            "", 
                            "White", 
                            "", 
                            "Patients with the CC genotype who have had a stroke may be at decreased risk for hemorrhagic transformation when treated with tissue plasminogen activator as compared to patients with the TT genotype. Other genetic and clinical factors may also influence risk for hemorrhagic transformation.", 
                            "CC"
                        ], 
                        [
                            "3", 
                            "Efficacy", 
                            "", 
                            "White", 
                            "", 
                            "Patients with the CT genotype who have had a stroke may be at decreased risk for hemorrhagic transformation when treated with tissue plasminogen activator as compared to patients with the TT genotype. Other genetic and clinical factors may also influence risk for hemorrhagic transformation.", 
                            "CT"
                        ], 
                        [
                            "3", 
                            "Efficacy", 
                            "", 
                            "White", 
                            "", 
                            "Patients with the TT genotype who have had a stroke may be at increased risk for hemorrhagic transformation when treated with tissue plasminogen activator as compared to patients with the CC or CT genotype. Other genetic and clinical factors may also influence risk for hemorrhagic transformation.", 
                            "TT"
                        ]
                    ]
                ]
            ], 
            "symbol": "A2M", 
            "source": "Clinical Annotation", 
            "textHTML": "", 
            "relatedDrug": "Enzymes"
        }
    ], 
    "counter": 4, 
    "success": true
}

The structure is similar to the Dosage Guidelines returned format. The difference is that the 9th field contains a list of tuples with clinical annotations. Each tuple has the following fields:

  • Field 1: Level Of Evidence
  • Field 2: Type
  • Field 3: Disease
  • Field 4: OMB Race
  • Field 5: Race notes
  • Field 6: The Clinical Annotation text
  • Field 7: The diplotype

Recommended usage

We suggest users to first use the fetch_init_json call to acquire a full list of recommendations. This list is not big (well.. for today standards) and can save many calls to the service. Subsequently users can check this list for genes,drugs,alleles or specific metabolizer statuses that are interested. After locating an interesting combination they should use the recommendations call to acquire a detailed set of recommendations.

python example

This is a snippet of code of how to use the API through python.

import requests # http://docs.python-requests.org/en/latest/index.html 
import json

req = requests.get('http://www.epga.gr/explore/recommendations/genes/A2M')
json_text = req.text
data = json.loads(json_text)
print data['gdr'][0]['alleles'][0][0]

u'rs669'

Contact

For more information and error reports please contact Alexandros Kanterakis

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment