Package: ensembl-rest
Ensembl-RESTA Python interface to the Ensembl REST APIs. A whole world of biological dataat your fingertips.TheEnsembl databasecontainsreference biological data on almost any organism. Now it is easy toaccess this data programatically through their REST API.The full list of endpoints for the Ensembl REST API endpoints along withendpoint-specific documentation can be found ontheir website.This library also includes some utilities built on top of the APIs designed toease working with them, including anAssemblyMapperclass that helps in the conversion between different genome assemblies.This project uses code fromRESTEasywhich made my life much easier. Thanks!InstallationYou can install fromPyPI$ pip install ensembl_restExamplesThe library exports methods that point to each endpoint of theAPI, such as:>>>importensembl_rest>>>ensembl_rest.symbol_lookup(species='homo sapiens',symbol='BRCA2'){ 'species': 'human',

  'object_type': 'Gene',

  'description': 'BRCA2, DNA repair associated [Source:HGNC Symbol;Acc:HGNC:1101]',

  'assembly_name': 'GRCh38',

  'end': 32400266,

  ...

  ...

  ...

  'seq_region_name': '13',

  'strand': 1,

  'id': 'ENSG00000139618',

  'start': 32315474}All the endpoints are listed on theAPI website.A quick lookup of the methods can be obtained by calling help on the module:>>>help(ensembl_rest)If you want to use an endpoint from the ones enlisted in theAPI website,sayGETlookup/symbol/:species/:symbol,then the name of the corresponding method is in the endpoint documentation URL,in this case, the documentation links tohttp://rest.ensembl.org/documentation/info/symbol_lookupso thecorresponding method name issymbol_lookup.>>>help(ensembl_rest.symbol_lookup)Help on function symbol_lookup in module ensembl_rest:



symbol_lookup(*args, **kwargs)

        Lookup ``GET lookup/symbol/:species/:symbol``



    Find the species and database for a symbol in a linked external database





    **Parameters**



    - Required:

            + **Name**:  species

            + *Type*:  String

            + *Description*:  Species name/alias

            + *Default*:  -

            + *Example Values*:  homo_sapiens, human

    ...

    ...



    - Optional:



            + **Name**:  expand

            + *Type*:  Boolean(0,1)

            + *Description*:  Expands the search to include any connected features. e.g. If the object is a gene, its transcripts, translations and exons will be returned as well.

    ...

    ...



    **Resource info**



    - **Methods**:  GET

    - **Response formats**: json, xml, jsonp





    **More info**



    https://rest.ensembl.org/documentation/info/symbol_lookupWe can see from the resource stringGETlookup/symbol/:species/:symbolthatthis method contains 2 parameters called species and symbol, so we can call themethod in the following way:>>>ensembl_rest.symbol_lookup(species='homo sapiens',symbol='TP53')# Or like this...>>>ensembl_rest.symbol_lookup('homo sapiens','TP53'){'source': 'ensembl_havana',

  'object_type': 'Gene',

  'logic_name': 'ensembl_havana_gene',

 ...

 ...

 ...

  'start': 32315474}One can provide optional parameters with theparamskeyword (the specific parameters to pass depend on the specific endpoint,the official endpoints documentation can be foundhere)_:# Fetch also exons, transcripts, etc...>>>ensembl_rest.symbol_lookup('human','BRCA2',params={'expand':True}){'source': 'ensembl_havana',

 'seq_region_name': '13',

 'Transcript': [{'source': 'ensembl_havana',

   'object_type': 'Transcript',

   'logic_name': 'ensembl_havana_transcript',

   'Exon': [{'object_type': 'Exon',

     'version': 4,

     'species': 'human',

     'assembly_name': 'GRCh38',

     ...

     ...

     ...

 'biotype': 'protein_coding',

 'start': 32315474}The parameters for the POST endpoints are also provided via theparamskeyword  , such as in the next example:>>>ensembl_rest.symbol_post(species='human',params={'symbols':["BRCA2","TP53","BRAF"]}){

    "BRCA2": {

        "source": "ensembl_havana",

        "object_type": "Gene",

        "logic_name": "ensembl_havana_gene",

        "description": "BRCA2, DNA repair associated [Source:HGNC Symbol;Acc:HGNC:1101]",

        ...

        ...

    },

    "TP53": {

        ...

        ...

    }.

    "BRAF": {

        ...

        ...

        "strand": -1,

        "id": "ENSG00000157764",

        "start": 140719327

    }

}Another common usage is to fetch sequences of known genes:>>>ensembl_rest.sequence_id('ENSG00000157764'){'desc': 'chromosome:GRCh38:7:140719327:140924928:-1',

 'query': 'ENSG00000157764',

 'version': 13,

 'id': 'ENSG00000157764',

 'seq': 'TTCCCCCAATCCCCTCAGGCTCGG...ATTGACTGCATGGAGAAGTCTTCA',

 'molecule': 'dna'}if you want it in FASTA, you can modify theheaders:>>>ensembl_rest.sequence_id('ENSG00000157764',headers={'content-type':'text/x-fasta'})>ENSG00000157764.13 chromosome:GRCh38:7:140719327:140924928:-1

TTCCCCCAATCCCCTCAGGCTCGGCTGCGCCCGGGGCCGCGGGCCGGTACCTGAGGTGGC

CCAGGCGCCCTCCGCCCGCGGCGCCGCCCGGGCCGCTCCTCCCCGCGCCCCCCGCGCCCC

CCGCTCCTCCGCCTCCGCCTCCGCCTCCGCCTCCCCCAGCTCTCCGCCTCCCTTCCCCCT

...Notice that, if left unchanged, the methods ask for data in dictionary (JSON)format so that they are easy to use. If the response cannot be decoded as such,then it is returned as plain text, such as the above.You can also map betweeen assemblies…>>>ensembl_rest.assembly_map(species='human',asm_one='GRCh37',region='X:1000000..1000100:1',asm_two='GRCh38')# Or...>>>region_str=ensembl_rest.region_str(chrom='X',start=1000000,end=1000100)>>>ensembl_rest.assembly_map(species='human',asm_one='GRCh37',region=region_str,asm_two='GRCh38'){'mappings': [{'original': {'seq_region_name': 'X',

    'strand': 1,

    'coord_system': 'chromosome',

    'end': 1000100,

    'start': 1000000,

    'assembly': 'GRCh37'},

   'mapped': {'seq_region_name': 'X',

    'strand': 1,

    'coord_system': 'chromosome',

    'end': 1039365,

    'start': 1039265,

    'assembly': 'GRCh38'}}]}The above problem (mapping from one assembly to another) is so frequent thatthe library provides a specialized classAssemblyMapperto efficientlymapping large amounts of regions between assemblies. This class avoids thetime-consuming task of making a web request every time a mapping is needed byfetching the mapping of the whole assembly right from the instantiation. Thisis a time-consuming operation by itself, but it pays off when one has totransform repeatedly betweeen assemblies.:>>> mapper = ensembl_rest.AssemblyMapper(

                species='human',

                from_assembly='GRCh37',

                to_assembly='GRCh38'

            )



>>> mapper.map(chrom='1', pos=1000000)

1064620You can also find orthologs, paralogs and gene tree information, along withvariation data and basically everythingEnsemblhas to offer.If you want to instantiate your own client, you can do it by using theensembl_rest.EnsemblClientclass, this class is the one that contains allthe endpoint methods.>>>client=ensembl_rest.EnsemblClient()>>>client.symbol_lookup('homo sapiens','TP53'){'source': 'ensembl_havana',

  'object_type': 'Gene',

  'logic_name': 'ensembl_havana_gene',

  'version': 14,

  'species': 'human',

  ...

  ...

  ...}Finally, the library exposes the classensembl_rest.HTTPErrorthat allows tohandle errors in the requests. An example of it’s utility is when using theGETgenetree/member/symbol/:species/:symbolendpoint to query for gene treesin order to find ortholog and paralog proteins and genes. This endpoint returnsan HTTP error when a gene tree is not found with code 400 and the error messageLookup found nothing. We can use this information to detect the errorand handle it, or to simply ignore it if we expected it:forgenein['TP53','rare-new-gene','BRCA2']:try:gene_tree=ensembl_rest.genetree_member_symbol(species='human',symbol=gene,params={'prune_species':'human'})# Assuming we have a function to extract the paralogsparalogs=extract_paralogs(gene_tree['tree'])print(paralogs)# Handle the case when there's no gene treeexceptensembl_rest.HTTPErroraserr:error_code=err.response.status_codeerror_message=err.response.json()['error']if(error_code==400)\and('Lookup found nothing'inerror_message):# Skip the gene with no datapasselse:# The exception was caused by another problem# Raise the exception againraiseMetaAuthor:Ad115-Github–a.garcia230395@gmail.comProject pages:Docs-@GitHub-@PyPIDistributed under the MIT license. SeeLICENSEfor more information.ContributingCheck for open issues or open a fresh issue to start a discussionaround a feature idea or a bug.Forkthe repositoryon GitHub to start making your changes to a feature branch, derivedfrom themasterbranch.Write a test which shows that the bug was fixed or that the featureworks as expected.Send a pull request and bug the maintainer until it gets merged andpublished.