ensembl-rest


Nameensembl-rest JSON
Version 0.3.4 PyPI version JSON
download
home_pagehttps://github.com/Ad115/EnsemblRest
SummaryAn interface to the Ensembl REST APIs, biological data at your fingertips.
upload_time2023-10-14 02:31:18
maintainer
docs_urlNone
authorAd115
requires_python
license
keywords ensembl rest api client genomes
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            

Ensembl-REST

============



A Python interface to the Ensembl REST APIs. A whole world of biological data 

at your fingertips.



The `Ensembl database <https://www.ensembl.org/index.html>`__ contains

reference biological data on almost any organism. Now it is easy to

access this data programatically through their REST API.



The full list of endpoints for the Ensembl REST API endpoints along with 

endpoint-specific documentation can be found on `their website <https://rest.ensembl.org/>`__.



This library also includes some utilities built on top of the APIs designed to

ease working with them, including an `AssemblyMapper <https://ad115.github.io/EnsemblRest/#ensembl_rest.AssemblyMapper>`__ 

class that helps in the conversion between different genome assemblies.





This project uses code from `RESTEasy <https://github.com/rapidstack/RESTEasy>`__

which made my life much easier. Thanks!







Installation

------------



You can install from `PyPI <https://pypi.org/project/ensembl-rest/>`_ ::



    $ pip install ensembl_rest





Examples

========



The library exports methods that point to each endpoint of the

API, such as:



.. code-block:: python



    >>> import ensembl_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 the `API website <http://rest.ensembl.org/>`__. 

A quick lookup of the methods can be obtained by calling help on the module:



.. code-block:: python



    >>> help(ensembl_rest)





If you want to use an endpoint from the ones enlisted in the `API website <http://rest.ensembl.org/>`__, 

say ``GET lookup/symbol/:species/:symbol`` , 

then the name of the corresponding method is in the endpoint documentation URL, 

in this case, the documentation links to 

http://rest.ensembl.org/documentation/info/symbol\_lookup so the 

corresponding method name is ``symbol_lookup``.



.. code-block:: python



    >>> 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_lookup





We can see from the resource string ``GET lookup/symbol/:species/:symbol`` that

this method contains 2 parameters called species and symbol, so we can call the

method in the following way:



.. code-block:: python



    >>> 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 the ``params`` 

keyword (the specific parameters to pass depend on the specific endpoint, 

the official endpoints documentation can be found `here <http://rest.ensembl.org/>`_)_:



.. code-block:: python



        # 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 the ``params`` 

keyword  , such as in the next example:



.. code-block:: python



    >>> 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:



.. code-block:: python



    >>> 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 the ``headers``:



.. code-block:: python



    >>> 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...



.. code-block:: python



    >>> 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 that 

the library provides a specialized class ``AssemblyMapper`` to efficiently

mapping large amounts of regions between assemblies. This class avoids the 

time-consuming task of making a web request every time a mapping is needed by 

fetching the mapping of the whole assembly right from the instantiation. This 

is a time-consuming operation by itself, but it pays off when one has to 

transform repeatedly betweeen assemblies.::





        >>> mapper = ensembl_rest.AssemblyMapper(

                        species='human', 

                        from_assembly='GRCh37',

                        to_assembly='GRCh38'

                    )

        

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

        1064620



You can also find orthologs, paralogs and gene tree information, along with 

variation data and basically everything `Ensembl <http://rest.ensembl.org/>`__ 

has to offer.



If you want to instantiate your own client, you can do it by using the 

``ensembl_rest.EnsemblClient`` class, this class is the one that contains all 

the endpoint methods.



.. code-block:: python



    >>> 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 class ``ensembl_rest.HTTPError`` that allows to 

handle errors in the requests. An example of it's utility is when using the 

``GET genetree/member/symbol/:species/:symbol`` endpoint to query for gene trees 

in order to find ortholog and paralog proteins and genes. This endpoint returns 

an HTTP error when a gene tree is not found with code 400 and the error message 

``Lookup found nothing``. We can use this information to detect the error 

and handle it, or to simply ignore it if we expected it:





.. code-block:: python



    for gene in ['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 paralogs

            paralogs = extract_paralogs(gene_tree['tree'])

            print(paralogs)



        # Handle the case when there's no gene tree

        except ensembl_rest.HTTPError as err:

            error_code = err.response.status_code

            error_message = err.response.json()['error']

            if (error_code == 400) \

               and ('Lookup found nothing' in error_message):

                # Skip the gene with no data

                pass

            else:

                # The exception was caused by another problem

                # Raise the exception again

                raise







Meta

====



**Author**: `Ad115 <https://agargar.wordpress.com/>`_ -

`Github <https://github.com/Ad115/>`_ – a.garcia230395@gmail.com



**Project pages**: 

`Docs <https://ensemblrest.readthedocs.io>`__ - `@GitHub <https://github.com/Ad115/EnsemblRest/>`__ - `@PyPI <https://pypi.org/project/ensembl-rest/>`__



Distributed under the MIT license. See

`LICENSE <https://github.com/Ad115/EnsemblRest/blob/master/LICENSE>`_

for more information.



Contributing

============



1. Check for open issues or open a fresh issue to start a discussion

   around a feature idea or a bug.

2. Fork `the repository <https://github.com/Ad115/EnsemblRest/>`_

   on GitHub to start making your changes to a feature branch, derived

   from the **master** branch.

3. Write a test which shows that the bug was fixed or that the feature

   works as expected.

4. Send a pull request and bug the maintainer until it gets merged and

   published.


            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/Ad115/EnsemblRest",
    "name": "ensembl-rest",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "ensembl rest api client genomes",
    "author": "Ad115",
    "author_email": "a.garcia230395@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/33/6f/090470711301b02ded0bcc29f1b70a5e55ca4a1d65d63b3f81c4b21da6e9/ensembl_rest-0.3.4.tar.gz",
    "platform": null,
    "description": "\r\n\r\nEnsembl-REST\r\n\r\n============\r\n\r\n\r\n\r\nA Python interface to the Ensembl REST APIs. A whole world of biological data \r\n\r\nat your fingertips.\r\n\r\n\r\n\r\nThe `Ensembl database <https://www.ensembl.org/index.html>`__ contains\r\n\r\nreference biological data on almost any organism. Now it is easy to\r\n\r\naccess this data programatically through their REST API.\r\n\r\n\r\n\r\nThe full list of endpoints for the Ensembl REST API endpoints along with \r\n\r\nendpoint-specific documentation can be found on `their website <https://rest.ensembl.org/>`__.\r\n\r\n\r\n\r\nThis library also includes some utilities built on top of the APIs designed to\r\n\r\nease working with them, including an `AssemblyMapper <https://ad115.github.io/EnsemblRest/#ensembl_rest.AssemblyMapper>`__ \r\n\r\nclass that helps in the conversion between different genome assemblies.\r\n\r\n\r\n\r\n\r\n\r\nThis project uses code from `RESTEasy <https://github.com/rapidstack/RESTEasy>`__\r\n\r\nwhich made my life much easier. Thanks!\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\nInstallation\r\n\r\n------------\r\n\r\n\r\n\r\nYou can install from `PyPI <https://pypi.org/project/ensembl-rest/>`_ ::\r\n\r\n\r\n\r\n    $ pip install ensembl_rest\r\n\r\n\r\n\r\n\r\n\r\nExamples\r\n\r\n========\r\n\r\n\r\n\r\nThe library exports methods that point to each endpoint of the\r\n\r\nAPI, such as:\r\n\r\n\r\n\r\n.. code-block:: python\r\n\r\n\r\n\r\n    >>> import ensembl_rest\r\n\r\n\r\n\r\n    >>> ensembl_rest.symbol_lookup(\r\n\r\n            species='homo sapiens',\r\n\r\n            symbol='BRCA2'\r\n\r\n        )\r\n\r\n\r\n\r\n::\r\n\r\n\r\n\r\n   { 'species': 'human',\r\n\r\n     'object_type': 'Gene',\r\n\r\n     'description': 'BRCA2, DNA repair associated [Source:HGNC Symbol;Acc:HGNC:1101]',\r\n\r\n     'assembly_name': 'GRCh38',\r\n\r\n     'end': 32400266,\r\n\r\n     ...\r\n\r\n     ...\r\n\r\n     ...\r\n\r\n     'seq_region_name': '13',\r\n\r\n     'strand': 1,\r\n\r\n     'id': 'ENSG00000139618',\r\n\r\n     'start': 32315474}\r\n\r\n\r\n\r\nAll the endpoints are listed on the `API website <http://rest.ensembl.org/>`__. \r\n\r\nA quick lookup of the methods can be obtained by calling help on the module:\r\n\r\n\r\n\r\n.. code-block:: python\r\n\r\n\r\n\r\n    >>> help(ensembl_rest)\r\n\r\n\r\n\r\n\r\n\r\nIf you want to use an endpoint from the ones enlisted in the `API website <http://rest.ensembl.org/>`__, \r\n\r\nsay ``GET lookup/symbol/:species/:symbol`` , \r\n\r\nthen the name of the corresponding method is in the endpoint documentation URL, \r\n\r\nin this case, the documentation links to \r\n\r\nhttp://rest.ensembl.org/documentation/info/symbol\\_lookup so the \r\n\r\ncorresponding method name is ``symbol_lookup``.\r\n\r\n\r\n\r\n.. code-block:: python\r\n\r\n\r\n\r\n    >>> help(ensembl_rest.symbol_lookup)\r\n\r\n\r\n\r\n::\r\n\r\n\r\n\r\n    Help on function symbol_lookup in module ensembl_rest:\r\n\r\n\r\n\r\n    symbol_lookup(*args, **kwargs)\r\n\r\n            Lookup ``GET lookup/symbol/:species/:symbol``\r\n\r\n        \r\n\r\n        Find the species and database for a symbol in a linked external database\r\n\r\n        \r\n\r\n        \r\n\r\n        **Parameters**\r\n\r\n        \r\n\r\n        - Required:\r\n\r\n                + **Name**:  species\r\n\r\n                + *Type*:  String\r\n\r\n                + *Description*:  Species name/alias\r\n\r\n                + *Default*:  -\r\n\r\n                + *Example Values*:  homo_sapiens, human\r\n\r\n        ...\r\n\r\n        ...\r\n\r\n        \r\n\r\n        - Optional:\r\n\r\n        \r\n\r\n                + **Name**:  expand\r\n\r\n                + *Type*:  Boolean(0,1)\r\n\r\n                + *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.\r\n\r\n        ...\r\n\r\n        ...\r\n\r\n        \r\n\r\n        **Resource info**\r\n\r\n        \r\n\r\n        - **Methods**:  GET\r\n\r\n        - **Response formats**: json, xml, jsonp\r\n\r\n        \r\n\r\n        \r\n\r\n        **More info**\r\n\r\n        \r\n\r\n        https://rest.ensembl.org/documentation/info/symbol_lookup\r\n\r\n\r\n\r\n\r\n\r\nWe can see from the resource string ``GET lookup/symbol/:species/:symbol`` that\r\n\r\nthis method contains 2 parameters called species and symbol, so we can call the\r\n\r\nmethod in the following way:\r\n\r\n\r\n\r\n.. code-block:: python\r\n\r\n\r\n\r\n    >>> ensembl_rest.symbol_lookup(\r\n\r\n            species='homo sapiens',\r\n\r\n            symbol='TP53'\r\n\r\n        )\r\n\r\n    \r\n\r\n    # Or like this...\r\n\r\n    >>> ensembl_rest.symbol_lookup('homo sapiens', 'TP53')\r\n\r\n\r\n\r\n::\r\n\r\n\r\n\r\n   {'source': 'ensembl_havana',\r\n\r\n     'object_type': 'Gene',\r\n\r\n     'logic_name': 'ensembl_havana_gene',\r\n\r\n    ...\r\n\r\n    ...\r\n\r\n    ...\r\n\r\n     'start': 32315474}\r\n\r\n\r\n\r\nOne can provide optional parameters with the ``params`` \r\n\r\nkeyword (the specific parameters to pass depend on the specific endpoint, \r\n\r\nthe official endpoints documentation can be found `here <http://rest.ensembl.org/>`_)_:\r\n\r\n\r\n\r\n.. code-block:: python\r\n\r\n\r\n\r\n        # Fetch also exons, transcripts, etc...\r\n\r\n        >>> ensembl_rest.symbol_lookup('human', 'BRCA2', \r\n\r\n                                       params={'expand':True})\r\n\r\n\r\n\r\n::\r\n\r\n\r\n\r\n    {'source': 'ensembl_havana',\r\n\r\n     'seq_region_name': '13',\r\n\r\n     'Transcript': [{'source': 'ensembl_havana',\r\n\r\n       'object_type': 'Transcript',\r\n\r\n       'logic_name': 'ensembl_havana_transcript',\r\n\r\n       'Exon': [{'object_type': 'Exon',\r\n\r\n         'version': 4,\r\n\r\n         'species': 'human',\r\n\r\n         'assembly_name': 'GRCh38',\r\n\r\n         ...\r\n\r\n         ...\r\n\r\n         ...\r\n\r\n     'biotype': 'protein_coding',\r\n\r\n     'start': 32315474}\r\n\r\n         \r\n\r\n\r\n\r\nThe parameters for the POST endpoints are also provided via the ``params`` \r\n\r\nkeyword  , such as in the next example:\r\n\r\n\r\n\r\n.. code-block:: python\r\n\r\n\r\n\r\n    >>> ensembl_rest.symbol_post(species='human',\r\n\r\n                                 params={'symbols': [\"BRCA2\", \r\n\r\n                                                     \"TP53\", \r\n\r\n                                                     \"BRAF\" ]})\r\n\r\n\r\n\r\n::\r\n\r\n\r\n\r\n    {\r\n\r\n        \"BRCA2\": {\r\n\r\n            \"source\": \"ensembl_havana\",\r\n\r\n            \"object_type\": \"Gene\",\r\n\r\n            \"logic_name\": \"ensembl_havana_gene\",\r\n\r\n            \"description\": \"BRCA2, DNA repair associated [Source:HGNC Symbol;Acc:HGNC:1101]\",\r\n\r\n            ...\r\n\r\n            ...\r\n\r\n        },\r\n\r\n        \"TP53\": {\r\n\r\n            ...\r\n\r\n            ...\r\n\r\n        }.\r\n\r\n        \"BRAF\": {\r\n\r\n            ...\r\n\r\n            ...\r\n\r\n            \"strand\": -1,\r\n\r\n            \"id\": \"ENSG00000157764\",\r\n\r\n            \"start\": 140719327\r\n\r\n        }\r\n\r\n    }\r\n\r\n\r\n\r\nAnother common usage is to fetch sequences of known genes:\r\n\r\n\r\n\r\n.. code-block:: python\r\n\r\n\r\n\r\n    >>> ensembl_rest.sequence_id('ENSG00000157764')\r\n\r\n\r\n\r\n\r\n\r\n::\r\n\r\n\r\n\r\n    {'desc': 'chromosome:GRCh38:7:140719327:140924928:-1',\r\n\r\n     'query': 'ENSG00000157764',\r\n\r\n     'version': 13,\r\n\r\n     'id': 'ENSG00000157764',\r\n\r\n     'seq': 'TTCCCCCAATCCCCTCAGGCTCGG...ATTGACTGCATGGAGAAGTCTTCA',\r\n\r\n     'molecule': 'dna'}\r\n\r\n\r\n\r\nif you want it in FASTA, you can modify the ``headers``:\r\n\r\n\r\n\r\n.. code-block:: python\r\n\r\n\r\n\r\n    >>> ensembl_rest.sequence_id(\r\n\r\n            'ENSG00000157764', \r\n\r\n            headers={'content-type': 'text/x-fasta'})\r\n\r\n\r\n\r\n\r\n\r\n::\r\n\r\n\r\n\r\n    >ENSG00000157764.13 chromosome:GRCh38:7:140719327:140924928:-1\r\n\r\n    TTCCCCCAATCCCCTCAGGCTCGGCTGCGCCCGGGGCCGCGGGCCGGTACCTGAGGTGGC\r\n\r\n    CCAGGCGCCCTCCGCCCGCGGCGCCGCCCGGGCCGCTCCTCCCCGCGCCCCCCGCGCCCC\r\n\r\n    CCGCTCCTCCGCCTCCGCCTCCGCCTCCGCCTCCCCCAGCTCTCCGCCTCCCTTCCCCCT\r\n\r\n    ...\r\n\r\n\r\n\r\nNotice that, if left unchanged, the methods ask for data in dictionary (JSON) \r\n\r\nformat so that they are easy to use. If the response cannot be decoded as such,\r\n\r\nthen it is returned as plain text, such as the above.\r\n\r\n\r\n\r\nYou can also map betweeen assemblies...\r\n\r\n\r\n\r\n.. code-block:: python\r\n\r\n\r\n\r\n    >>> ensembl_rest.assembly_map(species='human',\r\n\r\n                                  asm_one='GRCh37',\r\n\r\n                                  region='X:1000000..1000100:1',\r\n\r\n                                  asm_two='GRCh38')\r\n\r\n    \r\n\r\n    \r\n\r\n    # Or...\r\n\r\n    >>> region_str = ensembl_rest.region_str(chrom='X',\r\n\r\n                                             start=1000000,\r\n\r\n                                             end=1000100)\r\n\r\n    \r\n\r\n    >>> ensembl_rest.assembly_map(species='human',\r\n\r\n                                  asm_one='GRCh37',\r\n\r\n                                  region=region_str,\r\n\r\n                                  asm_two='GRCh38')\r\n\r\n\r\n\r\n::\r\n\r\n\r\n\r\n    {'mappings': [{'original': {'seq_region_name': 'X',\r\n\r\n        'strand': 1,\r\n\r\n        'coord_system': 'chromosome',\r\n\r\n        'end': 1000100,\r\n\r\n        'start': 1000000,\r\n\r\n        'assembly': 'GRCh37'},\r\n\r\n       'mapped': {'seq_region_name': 'X',\r\n\r\n        'strand': 1,\r\n\r\n        'coord_system': 'chromosome',\r\n\r\n        'end': 1039365,\r\n\r\n        'start': 1039265,\r\n\r\n        'assembly': 'GRCh38'}}]}\r\n\r\n\r\n\r\n\r\n\r\nThe above problem (mapping from one assembly to another) is so frequent that \r\n\r\nthe library provides a specialized class ``AssemblyMapper`` to efficiently\r\n\r\nmapping large amounts of regions between assemblies. This class avoids the \r\n\r\ntime-consuming task of making a web request every time a mapping is needed by \r\n\r\nfetching the mapping of the whole assembly right from the instantiation. This \r\n\r\nis a time-consuming operation by itself, but it pays off when one has to \r\n\r\ntransform repeatedly betweeen assemblies.::\r\n\r\n\r\n\r\n\r\n\r\n        >>> mapper = ensembl_rest.AssemblyMapper(\r\n\r\n                        species='human', \r\n\r\n                        from_assembly='GRCh37',\r\n\r\n                        to_assembly='GRCh38'\r\n\r\n                    )\r\n\r\n        \r\n\r\n        >>> mapper.map(chrom='1', pos=1000000)\r\n\r\n        1064620\r\n\r\n\r\n\r\nYou can also find orthologs, paralogs and gene tree information, along with \r\n\r\nvariation data and basically everything `Ensembl <http://rest.ensembl.org/>`__ \r\n\r\nhas to offer.\r\n\r\n\r\n\r\nIf you want to instantiate your own client, you can do it by using the \r\n\r\n``ensembl_rest.EnsemblClient`` class, this class is the one that contains all \r\n\r\nthe endpoint methods.\r\n\r\n\r\n\r\n.. code-block:: python\r\n\r\n\r\n\r\n    >>> client = ensembl_rest.EnsemblClient()\r\n\r\n\r\n\r\n    >>> client.symbol_lookup('homo sapiens', 'TP53')\r\n\r\n\r\n\r\n\r\n\r\n::\r\n\r\n\r\n\r\n   {'source': 'ensembl_havana',\r\n\r\n     'object_type': 'Gene',\r\n\r\n     'logic_name': 'ensembl_havana_gene',\r\n\r\n     'version': 14,\r\n\r\n     'species': 'human',\r\n\r\n     ...\r\n\r\n     ...\r\n\r\n     ...}\r\n\r\n        \r\n\r\n\r\n\r\nFinally, the library exposes the class ``ensembl_rest.HTTPError`` that allows to \r\n\r\nhandle errors in the requests. An example of it's utility is when using the \r\n\r\n``GET genetree/member/symbol/:species/:symbol`` endpoint to query for gene trees \r\n\r\nin order to find ortholog and paralog proteins and genes. This endpoint returns \r\n\r\nan HTTP error when a gene tree is not found with code 400 and the error message \r\n\r\n``Lookup found nothing``. We can use this information to detect the error \r\n\r\nand handle it, or to simply ignore it if we expected it:\r\n\r\n\r\n\r\n\r\n\r\n.. code-block:: python\r\n\r\n\r\n\r\n    for gene in ['TP53', 'rare-new-gene', 'BRCA2']:\r\n\r\n        try:\r\n\r\n            gene_tree = ensembl_rest.genetree_member_symbol(\r\n\r\n                            species='human',\r\n\r\n                            symbol=gene,\r\n\r\n                            params={'prune_species': 'human'}\r\n\r\n                        )\r\n\r\n            # Assuming we have a function to extract the paralogs\r\n\r\n            paralogs = extract_paralogs(gene_tree['tree'])\r\n\r\n            print(paralogs)\r\n\r\n\r\n\r\n        # Handle the case when there's no gene tree\r\n\r\n        except ensembl_rest.HTTPError as err:\r\n\r\n            error_code = err.response.status_code\r\n\r\n            error_message = err.response.json()['error']\r\n\r\n            if (error_code == 400) \\\r\n\r\n               and ('Lookup found nothing' in error_message):\r\n\r\n                # Skip the gene with no data\r\n\r\n                pass\r\n\r\n            else:\r\n\r\n                # The exception was caused by another problem\r\n\r\n                # Raise the exception again\r\n\r\n                raise\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\nMeta\r\n\r\n====\r\n\r\n\r\n\r\n**Author**: `Ad115 <https://agargar.wordpress.com/>`_ -\r\n\r\n`Github <https://github.com/Ad115/>`_ \u2013 a.garcia230395@gmail.com\r\n\r\n\r\n\r\n**Project pages**: \r\n\r\n`Docs <https://ensemblrest.readthedocs.io>`__ - `@GitHub <https://github.com/Ad115/EnsemblRest/>`__ - `@PyPI <https://pypi.org/project/ensembl-rest/>`__\r\n\r\n\r\n\r\nDistributed under the MIT license. See\r\n\r\n`LICENSE <https://github.com/Ad115/EnsemblRest/blob/master/LICENSE>`_\r\n\r\nfor more information.\r\n\r\n\r\n\r\nContributing\r\n\r\n============\r\n\r\n\r\n\r\n1. Check for open issues or open a fresh issue to start a discussion\r\n\r\n   around a feature idea or a bug.\r\n\r\n2. Fork `the repository <https://github.com/Ad115/EnsemblRest/>`_\r\n\r\n   on GitHub to start making your changes to a feature branch, derived\r\n\r\n   from the **master** branch.\r\n\r\n3. Write a test which shows that the bug was fixed or that the feature\r\n\r\n   works as expected.\r\n\r\n4. Send a pull request and bug the maintainer until it gets merged and\r\n\r\n   published.\r\n\r\n",
    "bugtrack_url": null,
    "license": "",
    "summary": "An interface to the Ensembl REST APIs, biological data at your fingertips.",
    "version": "0.3.4",
    "project_urls": {
        "Author": "https://agargar.wordpress.com/",
        "Documentation": "https://ensemblrest.readthedocs.io",
        "Homepage": "https://github.com/Ad115/EnsemblRest",
        "Say Thanks!": "https://saythanks.io/to/Ad115"
    },
    "split_keywords": [
        "ensembl",
        "rest",
        "api",
        "client",
        "genomes"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "7afe2711b061bd4aaf84f20ea14c2353bbe1736b983efcb1f12652bbff997ea9",
                "md5": "8af341e718a0e10beb1249afee6c665e",
                "sha256": "7e48acf8e01cff42adf36765eb4a266e61f0e7a861f58e7ef3164a46fff9002e"
            },
            "downloads": -1,
            "filename": "ensembl_rest-0.3.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "8af341e718a0e10beb1249afee6c665e",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 30316,
            "upload_time": "2023-10-14T02:31:16",
            "upload_time_iso_8601": "2023-10-14T02:31:16.865970Z",
            "url": "https://files.pythonhosted.org/packages/7a/fe/2711b061bd4aaf84f20ea14c2353bbe1736b983efcb1f12652bbff997ea9/ensembl_rest-0.3.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "336f090470711301b02ded0bcc29f1b70a5e55ca4a1d65d63b3f81c4b21da6e9",
                "md5": "f6994a9a4d5a3dc8edc67fb557a8c396",
                "sha256": "67b6c5b033583c531caba062646e1e93d2728a3fcc0731265c421184ab30acb3"
            },
            "downloads": -1,
            "filename": "ensembl_rest-0.3.4.tar.gz",
            "has_sig": false,
            "md5_digest": "f6994a9a4d5a3dc8edc67fb557a8c396",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 34710,
            "upload_time": "2023-10-14T02:31:18",
            "upload_time_iso_8601": "2023-10-14T02:31:18.950041Z",
            "url": "https://files.pythonhosted.org/packages/33/6f/090470711301b02ded0bcc29f1b70a5e55ca4a1d65d63b3f81c4b21da6e9/ensembl_rest-0.3.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-10-14 02:31:18",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Ad115",
    "github_project": "EnsemblRest",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "ensembl-rest"
}
        
Elapsed time: 0.16489s