Skip to content

Python Examples

If you are familiar with Python, the following functions may be useful when using the ImmPort Shared Data API. The code below is an example of a small utility package that could be imported into your programs to use when accessing the API.

In the examples following the Python Helper Functions block, we will be using these 2 function to retrieve content from the Shared Data API.

Python Helper Functions

Python Helper Functions

import sys
import requests
import json
import platform
import pandas as pd
from io import StringIO

API_ENDPOINT_BASE_URL = "https://www.immport.org"
DATA_QUERY_URL = API_ENDPOINT_BASE_URL + "/data/query"
ASPERA_TOKEN_URL = API_ENDPOINT_BASE_URL + "/data/download/token"
IMMPORT_TOKEN_URL = "https://www.immport.org/auth/token"


def request_immport_token(immport_token_url, username, password):
    '''Request an ImmPort token

       :param username: ImmPort user name.
       :param password: ImmPort user password.

       return immport_token
    '''
    r = requests.post(immport_token_url,
                  data={'username': username, 'password': password})
    if r.status_code == 200:
        return r.json()['access_token']
    else:
        return None


def api_data_query(username, password, endpoint, immport_token_url, token=True, format="json"):
    '''Use the Data Query API by first checking ImmPort user credentials,
       retrieving an ImmPort token, then call the API endpoint to retrieve the results.

       param user_name: ImmPort username.
       param password: ImmPort password.
       param endpoint: Data Query endpoint
       param token: Indicates if endpoint requires a token
       param format: String (json, tsv)


       return: results or None
    '''
    headers = {}
    results = None

    if token:
        immport_token = request_immport_token(immport_token_url, username, password)
        if immport_token is None:
             print("ERROR: Credentials incorrect for ImmPort, unable to retrieve token", file = sys.stderr)
             return None
        if format == "json":
            headers = {
                'Authorization': "bearer " + immport_token,
                'Content-Type': "application/json"
            }
        else:
            headers = {
                'Authorization': "bearer " + immport_token,
                'Content-Type': "text/plain"
            }

    else:
        if format == "json":
            headers = {
                'Content-Type': "application/json"
            }
        else:
            headers = {
                'Content-Type': "text/plain"
            }

    results = requests.get(endpoint, headers=headers)
    if results.status_code == 200:
        if results is None:
             print("ERROR: API Endpoint failed to return results", file = sys.stderr)
             return None
        if format == "json":
            return results.json()
        else:
            return results.text
    else:
        print("ERROR: API Status Code: " + str(results.status_code), file = sys.stderr)
        return None

Retrieving Study Pubmed Information in JSON format

The example retrieve the Pubmed information for SDY, then using Pandas creates a DataFrame.

Python - Retrieve Pubmed information for SDY1(JSON)

endpoint = DATA_QUERY_URL + "/api/study/pubmed/SDY1?format=json"
results = api_data_query(USERNAME, PASSWORD, endpoint, IMMPORT_TOKEN_URL, True, "json" )
df = pd.read_json(json.dumps(results))
df.head(2)
Results 
[
{
    "pubmedId": "16387596",
    "studyAccession": "SDY1",
    "authors": "Casale TB, Busse WW, Kline JN, Ballas ZK, Moss MH, Townley RG, Mokhtarani M, Seyfert-Margolis V, Asare A, Bateman K, Deniz Y",
    "doi": "10.1016/j.jaci.2005.09.036",
    "issue": "117(1)",
    "journal": "The Journal of allergy and clinical immunology",
    "month": "Jan",
    "pages": "134-40",
    "title": "Omalizumab pretreatment decreases acute reactions after rush immunotherapy for ragweed-induced seasonal allergic rhinitis.",
    "year": "2006"
},
{
    "pubmedId": "17631952",
    "studyAccession": "SDY1",
    "authors": "Klunker S, Saggar LR, Seyfert-Margolis V, Asare AL, Casale TB, Durham SR, Francis JN",
    "doi": "10.1016/j.jaci.2007.05.034",
    "issue": "120(3)",
    "journal": "The Journal of allergy and clinical immunology",
    "month": "Sep",
    "pages": "688-95",
    "title": "Combination treatment with omalizumab and rush immunotherapy for ragweed-induced allergic rhinitis: Inhibition of IgE-facilitated allergen binding.",
    "year": "2007"
}
]

Retrieving Study Pubmed Information in TSV format

The example retrieve the Pubmed information for SDY, then using Pandas creates a DataFrame.

Python - Retrieve Pubmed information for SDY1(TSV)

endpoint = DATA_QUERY_URL + "/api/study/pubmed/SDY1?format=tsv"
results = api_data_query(USERNAME, PASSWORD, endpoint, IMMPORT_TOKEN_URL, True, "tsv" )
df = pd.read_csv(StringIO(results), sep="\t")
df.head(2)
Results 
pubmedId    studyAccession  authors doi issue   journal month   pages   title   year
0   16387596    SDY1    Casale TB, Busse WW, Kline JN, Ballas ZK, Moss...   10.1016/j.jaci.2005.09.036  117(1)  The Journal of allergy and clinical immunology  Jan 134-40  Omalizumab pretreatment decreases acute reacti...   2006
1   17631952    SDY1    Klunker S, Saggar LR, Seyfert-Margolis V, Asar...   10.1016/j.jaci.2007.05.034  120(3)  The Journal of allergy and clinical immunology  Sep 688-95  Combination treatment with omalizumab and rush...   2007

Retrieving ELISA results in JSON format

The example retrieves the ELISA results for SDY1, then prints one record to show the JSON output, then using Pandas creates a DataFrame.

Python - Retrieve ELISA Results for SDY1 (JSON)

endpoint = DATA_QUERY_URL + "/result/elisa?studyAccession=SDY1&format=json"
results = api_data_query(USERNAME, PASSWORD, endpoint, IMMPORT_TOKEN_URL, True, "json" )
print(json.dumps(results[0],indent=4))
df = pd.read_json(json.dumps(results))
df.head(2)
Results 
{
    "resultId": 1,
    "ageEvent": "Age at enrollment",
    "ageEventSpecify": null,
    "ageUnit": "Years",
    "ancestralPopulation": null,
    "analyteAccession": null,
    "analytePreferred": null,
    "analyteReported": "IgG-a Amb a",
    "armAccession": "ARM2",
    "armName": "Immunotherapy with placebo anti-IgE",
    "biosampleAccession": "BS121576",
    "biosampleType": "Whole blood",
    "biosampleSubtype": "Whole Blood",
    "clinical": "Y",
    "comments": null,
    "ethnicity": "Not Hispanic or Latino",
    "experimentAccession": "EXP14863",
    "expsampleAccession": "ES96611",
    "gender": "Male",
    "maxSubjectAge": 26.0,
    "measurementTechnique": "ELISA",
    "minSubjectAge": 26.0,
    "plannedVisitAccession": "PV66",
    "race": "White",
    "raceSpecify": null,
    "repositoryAccession": null,
    "repositoryName": null,
    "species": "Homo sapiens",
    "strain": null,
    "studyAccession": "SDY1",
    "studyTitle": "Efficacy and Safety Evaluation of Allergen Immunotherapy Co-Administered with Omalizumab (an anti-IgE Monoclonal Antibody) (ITN019AD)",
    "studyTimeCollected": -7.0,
    "studyTimeCollectedUnit": "Days",
    "subjectAccession": "SUB73370",
    "subjectPhenotype": "Ragweed-induced seasonal allergic rhinitis",
    "unitPreferred": null,
    "unitReported": "U/ml",
    "valuePreferred": 114.8,
    "valueReported": "114.8",
    "treatmentAccession": null,
    "studyTimeT0EventSpecify": null,
    "studyTimeT0Event": "Not Specified"
}

Retrieving ELISA results in TSV format

The example retrieves the ELISA results for SDY1, then using Pandas creates a DataFrame.

Python - Retrieve ELISA Results for SDY1 (TSV)

endpoint = DATA_QUERY_URL + "/result/elisa?studyAccession=SDY1&format=tsv"
results = api_data_query(USERNAME, PASSWORD, endpoint, IMMPORT_TOKEN_URL, True, "tsv" )
df = pd.read_csv(StringIO(results), sep="\t")
df.head(2)
Results 
ageEvent    ageEventSpecify ageUnit analyteAccession    analytePreferred    analyteReported ancestralPopulation armAccession    armName biosampleAccession  ... studyTimeT0Event    studyTimeT0EventSpecify studyTitle  subjectAccession    subjectPhenotype    treatmentAccession  unitPreferred   unitReported    valuePreferred  valueReported
0   Age at enrollment   NaN Years   NaN NaN IgG-a Amb a NaN ARM2    Immunotherapy with placebo anti-IgE BS121576    ... Not Specified   NaN Efficacy and Safety Evaluation of Allergen Imm...   SUB73370    Ragweed-induced seasonal allergic rhinitis  NaN NaN U/ml    114.8   114.8
1   Age at enrollment   NaN Years   NaN NaN IgG-a Ragweed   NaN ARM2    Immunotherapy with placebo anti-IgE BS121576    ... Not Specified   NaN Efficacy and Safety Evaluation of Allergen Imm...   SUB73370    Ragweed-induced seasonal allergic rhinitis  NaN ng/ml   ng/ml   100.0   100.0
2 rows × 42 columns

Retrieving Study Design Information

This endpoint is used by UI to retrieve study design information and may not be useful for general users. This endpoint does not require and access token.

Python - Retrieve Study Design Information

endpoint = DATA_QUERY_URL + "/ui/study/summary/SDY1680"
results = api_data_query(USERNAME, PASSWORD, endpoint, IMMPORT_TOKEN_URL, False, "json" )
print(json.dumps(results, indent=4))
Results 
{
    "studyAccession": "SDY1680",
    "doi": "10.21430/M3OCS4VQWY",
    "title": "Comorbid illnesses are associated with altered adaptive immune responses to SARS-CoV-2",
    "pi": "Chetan Seshadri - University of Washington",
    "conditionStudied": "COVID-19",
    "briefDescription": "FCS and workspace files from ICS and Surface Marker Staining Experiments",
    "startDate": "2020-03-01",
    "detailedDescription": "Intracellular Cytokine Staining data and Surface Marker Phenotyping data from convalescent COVID-19 infected individuals who were previously either hospitalized or not hospitalized. Both the magnitude and functional breadth of antigen-specific CD4 T cell responses were consistently higher among hospitalized subjects, particularly those with medical comorbidities. CD4 T cell responses to all antigens were driven by IFN-g-independent poyfunctional profiles that are not typically the focus of vaccine studies.",
    "objectives": "Characterize T cell responses and immune subpopulations which are enriched or decreased in hospitalized convalescent individuals",
    "endpoints": "Flow Cytometry data characterizing immune subpopulations",
    "genderIncluded": "Female, Male, Not Specified",
    "subjectsNumber": 68,
    "downloadPackages": null,
    "contractGrant": "Qualification Of Assays To Measure Human T-Cell Responses Against Mycobacterial Lipid Antigens",
    "program": "NIH Program",
    "dataCompleteness": "0 - Descriptive data and results as originally received from the data provider.",
    "hypothesis": "Hospitalized and Non-hospitalized convalescent COVID-19 infected  individuals exhibit unique T cell responses",
    "studyLinks": [
        {
            "studyLinkId": 1345,
            "name": "Github",
            "type": null,
            "value": "https://github.com/seshadrilab"
        },
        {
            "studyLinkId": 1423,
            "name": "Correlates Severe COVID19 Surface Markers",
            "type": null,
            "value": "https://github.com/seshadrilab/Correlates_Severe_COVID19_Surface_Markers"
        },
        {
            "studyLinkId": 1424,
            "name": "Correlates Severe COVID19 ICS",
            "type": null,
            "value": "https://github.com/seshadrilab/Correlates_Severe_COVID19_ICS"
        }
    ],
    "studyPubmeds": [
        {
            "id": {
                "studyAccession": "SDY1680",
                "pubmedId": "33621211"
            },
            "authors": "Yu KK, Fischinger S, Smith MT, Atyeo C, Cizmeci D, Wolf CR, Layton ED, Logue JK, Aguilar MS, Shuey K, Loos C, Yu J, Franko NM, Choi RY, Wald A, Barouch DH, Koelle DM, Lauffenburger D, Chu HY, Alter G, Seshadri C",
            "doi": "10.1172/jci.insight.146242",
            "issue": null,
            "journal": "JCI insight",
            "month": "Feb",
            "pages": null,
            "title": "Comorbid illnesses are associated with altered adaptive immune responses to SARS-CoV-2.",
            "year": "2021"
        },
        {
            "id": {
                "studyAccession": "SDY1680",
                "pubmedId": "TBD"
            },
            "authors": null,
            "doi": null,
            "issue": null,
            "journal": null,
            "month": null,
            "pages": null,
            "title": null,
            "year": null
        }
    ],
    "studyGlossarys": []
}

Retrieve LK_DISEASE

Python - Retrieve LK_DISEASE Information

pd.set_option('max_colwidth', 200)
endpoint = DATA_QUERY_URL + "/api/lookup/lk_disease"
results = api_data_query(USERNAME, PASSWORD, endpoint, IMMPORT_TOKEN_URL, True, "json")
df = pd.read_json(json.dumps(results['content']), orient="columns")[['name','description','link']]
df.head(10)
Results 
name    description link
0   acquired immunodeficiency syndrome  A Human immunodeficiency virus infectious disease that results_in reduction in the numbers of CD4-bearing helper T cells below 200 per microliter of blood or 14% of all lymphocytes thereby renderi... http://purl.obolibrary.org/obo/DOID_635
1   acute disseminated encephalomyelitis    An encephalomyelitis characterized by inflammation located in brain and located in spinal cord that damages myelin. It usually occurs after viral infection, but also following vaccination, bacteri... http://purl.obolibrary.org/obo/DOID_639
2   Addison's disease   An adrenal cortical hypofunction that is characterized by insufficient steroid hormone production by the adrenal glands.    http://purl.obolibrary.org/obo/DOID_13774
3   Aging   The process of change in the structure and function of an organism that occurs with the passage of time.    http://purl.obolibrary.org/obo/NCIT_C16269
4   alcohol use disorder    A substance abuse that involves the recurring use of alcoholic beverages despite negative consequences. http://purl.obolibrary.org/obo/DOID_1574
5   allergic hypersensitivity disease   An immune system disease that is an exaggerated immune response to allergens, such as insect venom, dust mites, pollen, pet dander, drugs or some foods.    http://purl.obolibrary.org/obo/DOID_1205
6   allergic rhinitis   A rhinitis that is an allergic inflammation and irritation of the nasal airways involving sneezing, runny nose, nasal congestion, itching and tearing of the eyes caused by exposure to an allergen ... http://purl.obolibrary.org/obo/DOID_4481
7   alopecia areata An autoimmune disease resulting in the loss of hair on the scalp and elsewhere on the body initially causing bald spots.    http://purl.obolibrary.org/obo/DOID_986
8   Alzheimer's disease A tauopathy that is characterized by memory lapses, confusion, emotional instability and progressive loss of mental ability and results in progressive memory loss, impaired thinking, disorientatio... http://purl.obolibrary.org/obo/DOID_10652
9   anemia  A hematopoietic system disease that is characterized by a decrease in the normal number of red blood cells. http://purl.obolibrary.org/obo/DOID_2355