Quick Start

biothings_client was made to allow easy programmatic access to any BioThings API backend. We do this by generating configuration parameters (and documentation) that define a particular API on-the-fly. This is done using the get_client function. To use the get_client function, you only need to specify the entity type you want a client for as a string. Consider the following code:

In [1]: from biothings_client import get_client

In [2]: gene_client = get_client('gene')

In [3]: type(gene_client)
Out[3]: biothings_client.MyGeneInfo

The gene_client variable in the code above is a MyGeneInfo object (exactly as obtained through the MyGene.py package). As such, all of the methods available in the MyGene.py client are available in the biothings_client generated gene client. So the above code block is equivalent to the way you use MyGene.py client package before:

In [1]: import mygene

In [2]: gene_client = mygene.MyGeneInfo()get_client('gene')

In [3]: type(gene_client)
Out[3]: mygene.MyGeneInfo

Use the client for MyGene.info API - Genes

Once you get the gene_client instance from biothings_client, the rest is exactly the same:

In [4]: gene_client.getgene('1017', fields='symbol,name')
Out[4]:
{'_id': '1017',
 '_score': 13.166854,
 'name': 'cyclin dependent kinase 2',
 'symbol': 'CDK2'}

In [5]: gene_client.getgenes(['1017', '1018'], species='human', fields='symbol,name')
querying 1-2...done.
Out[5]:
[{'_id': '1017',
  '_score': 20.773563,
  'name': 'cyclin dependent kinase 2',
  'query': '1017',
  'symbol': 'CDK2'},
 {'_id': '1018',
  '_score': 21.309164,
  'name': 'cyclin dependent kinase 3',
  'query': '1018',
  'symbol': 'CDK3'}]

In [6]: gene_client.query('uniprot:P24941', fields='symbol,name')
Out[6]:
{'hits': [{'_id': '1017',
 '_score': 14.752583,
 'name': 'cyclin dependent kinase 2',
 'symbol': 'CDK2'}],
 'max_score': 14.752583,
 'took': 3,
 'total': 1}

In [7]: gene_client.querymany(['P24941', 'O14727'], scopes='uniprot', fields='symbol,name')
querying 1-2...done.
Finished.
Out[7]:
[{'_id': '1017',
  '_score': 14.176394,
  'name': 'cyclin dependent kinase 2',
  'query': 'P24941',
  'symbol': 'CDK2'},
{'_id': '317',
 '_score': 14.75709,
 'name': 'apoptotic peptidase activating factor 1',
 'query': 'O14727',
 'symbol': 'APAF1'}]

In [8]: gene_client.metadata()
Out[8]:
{'app_revision': 'c2a3aaa5fdac7b05fe243c1de62e6b3a3cf2b773',
 'available_fields': 'http://mygene.info/metadata/fields',
 'build_date': '2018-11-26T08:11:23.790634',
 'build_version': '20181126',
 'genome_assembly': {'frog': 'xenTro3',
  'fruitfly': 'dm3',
  'human': 'hg38',
  'mouse': 'mm10',
  'nematode': 'ce10',
  'pig': 'susScr2',
  'rat': 'rn4',
  'zebrafish': 'zv9'},
 'source': None,
 'src': {'PantherDB': {'stats': {'PantherDB': 156054},
   'version': '2017-12-11'},
  'cpdb': {'stats': {'cpdb': 21141}, 'version': '33'},
  'ensembl': {'stats': {'ensembl_acc': 3228635,
    'ensembl_gene': 3187005,
    'ensembl_genomic_pos': 3183045,
    'ensembl_interpro': 2307500,
    'ensembl_pfam': 2100435,
    'ensembl_prosite': 1266847},
   'version': '94'},
  'ensembl_genomic_pos_hg19': {'stats': {'ensembl_genomic_pos_hg19': 55966},
   'version': None},
  'ensembl_genomic_pos_mm9': {'stats': {'ensembl_genomic_pos_mm9': 38646},
   'version': None},
  'entrez': {'stats': {'entrez_accession': 22406332,
    'entrez_gene': 22521690,
    'entrez_genomic_pos': 2632698,
    'entrez_go': 204359,
    'entrez_refseq': 22370423,
    'entrez_retired': 243656,
    'entrez_unigene': 543053},
   'version': '20181126'},
  'exac': {'stats': {'broadinstitute_exac': 18240}, 'version': '0.3.1'},
  'generif': {'stats': {'generif': 96431}, 'version': '20181126'},
  'homologene': {'stats': {'homologene': 269019}, 'version': '68'},
  'pharmgkb': {'stats': {'pharmgkb': 26833}, 'version': '2018-11-05'},
  'pharos': {'stats': {'pharos': 19828}, 'version': '5.2.0'},
  'reactome': {'stats': {'reactome': 71935}, 'version': '2018-09-24'},
  'reagent': {'stats': {'reagent': 38621}, 'version': None},
  'refseq': {'stats': {'entrez_ec': 19773, 'entrez_genesummary': 27713},
   'version': '91'},
  'reporter': {'stats': {'reporter': 426561}, 'version': None},
  'ucsc': {'stats': {'ucsc_exons': 208266}, 'version': '20181115'},
  'umls': {'stats': {'umls': 39665}, 'version': '2017-05-08'},
  'uniprot': {'stats': {'uniprot': 9411447}, 'version': '20181107'},
  'uniprot_ipi': {'stats': {'uniprot_ipi': 157025}, 'version': None},
  'uniprot_pdb': {'stats': {'uniprot_pdb': 30379}, 'version': '20181107'},
  'uniprot_pir': {'stats': {'uniprot_pir': 153446}, 'version': '20181107'},
  'wikipedia': {'stats': {'wikipedia': 11075}, 'version': None}},
 'src_version': {'PantherDB': '2017-12-11',
  'cpdb': '33',
  'ensembl': '94',
  'ensembl_genomic_pos_hg19': None,
  'ensembl_genomic_pos_mm9': None,
  'entrez': '20181126',
  'exac': '0.3.1',
  'generif': '20181126',
  'homologene': '68',
  'pharmgkb': '2018-11-05',
  'pharos': '5.2.0',
  'reactome': '2018-09-24',
  'reagent': None,
  'refseq': '91',
  'reporter': None,
  'ucsc': '20181115',
  'umls': '2017-05-08',
  'uniprot': '20181107',
  'uniprot_ipi': None,
  'uniprot_pdb': '20181107',
  'uniprot_pir': '20181107',
  'wikipedia': None},
 'stats': {'total_ensembl_genes': 24436578,
  'total_ensembl_genes_mapped_to_entrez': 1355996,
  'total_ensembl_only_genes': 1873808,
  'total_entrez_genes': 22521690,
  'total_genes': 24395498,
  'total_species': 23801},
 'taxonomy': {'frog': 8364,
  'fruitfly': 7227,
  'human': 9606,
  'mouse': 10090,
  'nematode': 6239,
  'pig': 9823,
  'rat': 10116,
  'thale-cress': 3702,
  'zebrafish': 7955}}

In addition to the gene_client, you can generate a client to any of the other BioThings API services we offer. See the following code snippet:

Use the client for MyVariant.info API - Variants

In [10]: variant_client = get_client('variant')

In [11]: variant_client.query('dbnsfp.genename:BTK', fields='_id')
Out[11]:
{'hits': [{'_id': 'chrX:g.100614336C>T', '_score': 10.192645},
  {'_id': 'chrX:g.100608911G>A', '_score': 10.192645},
  {'_id': 'chrX:g.100608917G>C', '_score': 10.192645},
  {'_id': 'chrX:g.100608872T>A', '_score': 10.192645},
  {'_id': 'chrX:g.100608887A>T', '_score': 10.192645},
  {'_id': 'chrX:g.100608891T>C', '_score': 10.192645},
  {'_id': 'chrX:g.100608282T>C', '_score': 10.192645},
  {'_id': 'chrX:g.100608230A>T', '_score': 10.192645},
  {'_id': 'chrX:g.100604881C>T', '_score': 10.192645},
  {'_id': 'chrX:g.100608204A>G', '_score': 10.192645}],
 'max_score': 10.192645,
 'took': 10,
 'total': 5143}

Use the client for MyChem.info API - Chemicals/Drugs

In [12]: chem_client = get_client('chem')

In [13]: chem_client.getchem('DB00551', fields='drugbank.name')
Out[13]:
{'_id': 'RRUDCFGSUDOHDG-UHFFFAOYSA-N',
 'drugbank': {'_license': 'https://goo.gl/kvVASD',
  'name': 'Acetohydroxamic Acid'}}

Use the client for MyDisease.info API - Disease

In [13]: disease_client = get_client('disease')

In [14]: disease_client.query('diabetes')
Out[14]:
{'hits': [{'_id': 'MONDO:0005443',
   '_score': 3.466746,
   'mondo': {'label': 'type 2 diabetes nephropathy',
    'xrefs': {'efo': '0004997'}}},
  {'_id': 'MONDO:0023227',
   '_score': 3.466746,
   'mondo': {'definition': 'A form of diabetes insipidus that manifests during pregnancy (or in some cases, after pregnancy). It is characterized by theappearance of a polyuric-polydipsic syndrome that resultsin fluid intake ranging from 3 to 20 L/day. It is also charac-terized by excretion of abnormally high volumes of dilutedurine. This polyuria is insipid, i.e., the urine concentrationof dissolved substances is very low.',
    'label': 'gestational diabetes insipidus',
    'xrefs': {'gard': '0010702', 'mesh': 'C548014', 'umls': 'C2932666'}}},
  {'_id': 'MONDO:0001344',
   '_score': 3.466746,
   'mondo': {'label': 'obsolete neonatal diabetes mellitus'}},
  {'_id': 'MONDO:0019846',
   '_score': 3.4068294,
   'hpo': {'disease_name': 'Acquired central diabetes insipidus',
    'orphanet': '95626',
    'phenotype_related_to_disease': [{'aspect': 'P',
      'assigned_by': 'ORPHA:orphadata',
      'evidence': 'TAS',
      'frequency': 'HP:0040281',
      'hpo_id': 'HP:0000873'},
     {'aspect': 'P',
      'assigned_by': 'ORPHA:orphadata',
      'evidence': 'TAS',
      'frequency': 'HP:0040281',
      'hpo_id': 'HP:0001824'},
     {'aspect': 'P',
      'assigned_by': 'ORPHA:orphadata',
      'evidence': 'TAS',
      'frequency': 'HP:0040281',
      'hpo_id': 'HP:0001959'},
     {'aspect': 'P',
      'assigned_by': 'ORPHA:orphadata',
      'evidence': 'TAS',
      'frequency': 'HP:0040281',
      'hpo_id': 'HP:0100515'}]},
   'mondo': {'definition': 'Acquired central diabetes insipidus (acquired CDI) is a subtype of central diabetes insipidus (CDI, see this term), characterized by polyuria and polydipsia, due to an idiopathic or secondary decrease in vasopressin (AVP) production.',
    'label': 'acquired central diabetes insipidus',
    'xrefs': {'icd10': 'E23.2', 'orphanet': '95626'}}},
  {'_id': 'MONDO:0022650',
   '_score': 3.2161584,
   'mondo': {'label': 'cardiomyopathy diabetes deafness',
    'xrefs': {'gard': '0001103'}}},
  {'_id': 'MONDO:0005442',
   '_score': 3.1703691,
   'mondo': {'label': 'type 1 diabetes nephropathy',
    'xrefs': {'efo': '0004996'}}},
  {'_id': 'MONDO:0015967',
   '_score': 3.1703691,
   'mondo': {'definition': 'Rare genetic diabetes mellitus.',
    'label': 'rare genetic diabetes mellitus',
    'xrefs': {'orphanet': '183625'}}},
  {'_id': 'MONDO:0022971',
   '_score': 3.1703691,
   'mondo': {'label': 'diabetes persistent mullerian ducts',
    'xrefs': {'gard': '0001840'}}},
  {'_id': 'MONDO:0022993',
   '_score': 3.1703691,
   'mondo': {'definition': 'Diabetes insipidus caused by excessive intake of water due to psychological factors or damage to the thirst-regulating mechanism.',
    'label': 'dipsogenic diabetes insipidus',
    'xrefs': {'gard': '0010703',
     'mesh': 'C548013',
     'ncit': 'C129735',
     'sctid': '82800008',
     'umls': 'C0268813'}}},
  {'_id': 'MONDO:0015888',
   '_score': 3.1530147,
   'mondo': {'label': 'other rare diabetes mellitus',
    'xrefs': {'orphanet': '181381'}}}],
 'max_score': 3.466746,
 'took': 17,
 'total': 120}

Use the client for t.biothings.io API - Taxnomy

In [15]: taxon_client = get_client('taxon')

In [16]: taxon_client.gettaxon(9606)
Out[16]:
{'_id': '9606',
 '_version': 1,
 'authority': ['homo sapiens linnaeus, 1758'],
 'common_name': 'man',
 'genbank_common_name': 'human',
 'has_gene': True,
 'lineage': [9606,
  9605,
  207598,
  9604,
  314295,
  9526,
  314293,
  376913,
  9443,
  314146,
  1437010,
  9347,
  32525,
  40674,
  32524,
  32523,
  1338369,
  8287,
  117571,
  117570,
  7776,
  7742,
  89593,
  7711,
  33511,
  33213,
  6072,
  33208,
  33154,
  2759,
  131567,
  1],
 'parent_taxid': 9605,
 'rank': 'species',
 'scientific_name': 'homo sapiens',
 'taxid': 9606,
 'uniprot_name': 'homo sapiens'}