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'}