eutils -- a simplified interface to NCBI E-Utilities
====================================================
|pypi_badge| |build_status| |issues_badge| |contributors| |license| |docs| |changelog|
eutils is a Python package to simplify searching, fetching, and
parsing records from NCBI using their E-utilities_ interface.
News
----
* 0.5.0 was released on 2018-11-20. See `0.5 Change Log
<https://eutils.readthedocs.io/en/stable/changelog/0.5.html>`_.
Features
--------
* simple Pythonic interface for searching and fetching
* automatic query rate throttling per NCBI guidelines
* optional sqlite-based caching of compressed replies
* "façades" that facilitate access to essential attributes in replies
A Quick Example
---------------
As of May 1, 2018, NCBI throttles requests based on whether a client
is registered. Unregistered clients are limited to 3 requests/second;
registered clients are granted 10 requests/second, and may request
more. See the `NCBI Announcement
<https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/>`_
for more information.
The eutils package will automatically throttle requests according to
NCBI guidelines (3 or 10 requests/second without or with an API key,
respectively).
::
$ pip install eutils
$ ipython
>>> from eutils import Client
# Initialize a client. This client handles all caching and query
# throttling. For example:
>>> ec = Client(api_key=os.environ.get("NCBI_API_KEY", None))
# search for tumor necrosis factor genes
# any valid NCBI query may be used
>>> esr = ec.esearch(db='gene',term='tumor necrosis factor')
# fetch one of those (gene id 7157 is human TNF)
>>> egs = ec.efetch(db='gene', id=7157)
# One may fetch multiple genes at a time. These are returned as an
# EntrezgeneSet. We'll grab the first (and only) child, which returns
# an instance of the Entrezgene class.
>>> eg = egs.entrezgenes[0]
# Easily access some basic information about the gene
>>> eg.hgnc, eg.maploc, eg.description, eg.type, eg.genus_species
('TP53', '17p13.1', 'tumor protein p53', 'protein-coding', 'Homo sapiens')
# get a list of genomic references
>>> sorted([(r.acv, r.label) for r in eg.references])
[('NC_000017.11', 'Chromosome 17 Reference GRCh38...'),
('NC_018928.2', 'Chromosome 17 Alternate ...'),
('NG_017013.2', 'RefSeqGene')]
# Get the first three products defined on GRCh38
#>>> [p.acv for p in eg.references[0].products][:3]
#['NM_001126112.2', 'NM_001276761.1', 'NM_000546.5']
# As a sample, grab the first product defined on this reference (order is arbitrary)
>>> mrna = eg.references[0].products[0]
>>> str(mrna)
'GeneCommentary(acv=NM_001126112.2,type=mRNA,heading=Reference,label=transcript variant 2)'
# mrna.genomic_coords provides access to the exon definitions on this reference
>>> mrna.genomic_coords.gi, mrna.genomic_coords.strand
('568815581', -1)
>>> mrna.genomic_coords.intervals
[(7687376, 7687549), (7676520, 7676618), (7676381, 7676402),
(7675993, 7676271), (7675052, 7675235), (7674858, 7674970),
(7674180, 7674289), (7673700, 7673836), (7673534, 7673607),
(7670608, 7670714), (7668401, 7669689)]
# and the mrna has a product, the resulting protein:
>>> str(mrna.products[0])
'GeneCommentary(acv=NP_001119584.1,type=peptide,heading=Reference,label=isoform a)'
Important Notes
---------------
* **You are encouraged to** `browse issues
<https://github.com/biocommons/eutils/issues>`_. Please report any
issues you find.
* **Use a pip package specification to ensure stay within minor
releases for API stability.** For example, ``eutils >=0.6,<0.7``.
Developing and Contributing
---------------------------
Contributions of bug reports, code patches, and documentation are
welcome!
Development occurs in the default branch. Please work in feature
branches or bookmarks from the default branch. Feature branches should
be named for the eutils issue they fix, as in
`121-update-xml-facades`. When merging, use a commit message like
"closes #121: update xml facades to new-style interface". ("closes #n"
is recognized automatically and closes the ticket upon pushing.)
The included Makefile automates many tasks. In particular, `make
develop` prepares a development environment and `make test` runs
unittests. (Please run tests before committing!)
Again, thanks for your contributions.
.. _E-utilities: http://www.ncbi.nlm.nih.gov/books/NBK25499/
.. |build_status| image:: https://travis-ci.org/biocommons/eutils.svg?branch=master
:target: https://travis-ci.org/biocommons/eutils
.. |changelog| image:: https://img.shields.io/badge/docs-changelog-green.svg
:target: https://eutils.readthedocs.io/en/stable/changelog/
.. |contributors| image:: https://img.shields.io/github/contributors/biocommons/eutils.svg
:target: https://github.com/biocommons/eutils
.. |docs| image:: https://img.shields.io/badge/docs-readthedocs-green.svg
:target: http://eutils.readthedocs.io/
.. |issues_badge| image:: https://img.shields.io/github/issues/biocommons/eutils.png
:target: https://github.com/biocommons/eutils/issues
:align: middle
.. |license| image:: https://img.shields.io/github/license/biocommons/eutils.svg
:target: https://github.com/biocommons/eutils/blob/master/LICENSE
.. |pypi_badge| image:: https://img.shields.io/pypi/v/eutils.svg
:target: https://pypi.org/project/eutils/
Raw data
{
"_id": null,
"home_page": "https://github.com/biocommons/eutils",
"name": "eutils",
"maintainer": "",
"docs_url": "https://pythonhosted.org/eutils/",
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "bioinformatics,eutilities,ncbi",
"author": "Source Code Contributors",
"author_email": "biocommons-dev@googlegroups.com",
"download_url": "https://files.pythonhosted.org/packages/e9/ab/75a1cc7b0f24a568bffb2588f9a783d3d4385102c1910dfb8c9ff7bb3498/eutils-0.6.0.tar.gz",
"platform": "any",
"description": "eutils -- a simplified interface to NCBI E-Utilities\n====================================================\n\n|pypi_badge| |build_status| |issues_badge| |contributors| |license| |docs| |changelog|\n\neutils is a Python package to simplify searching, fetching, and\nparsing records from NCBI using their E-utilities_ interface.\n\n\nNews\n----\n\n* 0.5.0 was released on 2018-11-20. See `0.5 Change Log\n <https://eutils.readthedocs.io/en/stable/changelog/0.5.html>`_.\n\n\n\nFeatures\n--------\n* simple Pythonic interface for searching and fetching\n* automatic query rate throttling per NCBI guidelines\n* optional sqlite-based caching of compressed replies\n* \"fa\u00e7ades\" that facilitate access to essential attributes in replies\n\n\n\nA Quick Example\n---------------\n\nAs of May 1, 2018, NCBI throttles requests based on whether a client\nis registered. Unregistered clients are limited to 3 requests/second;\nregistered clients are granted 10 requests/second, and may request\nmore. See the `NCBI Announcement\n<https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/>`_\nfor more information. \n\nThe eutils package will automatically throttle requests according to\nNCBI guidelines (3 or 10 requests/second without or with an API key,\nrespectively).\n\n::\n\n $ pip install eutils\n $ ipython\n\n >>> from eutils import Client\n\n # Initialize a client. This client handles all caching and query\n # throttling. For example:\n >>> ec = Client(api_key=os.environ.get(\"NCBI_API_KEY\", None))\n\n # search for tumor necrosis factor genes\n # any valid NCBI query may be used\n >>> esr = ec.esearch(db='gene',term='tumor necrosis factor')\n\n # fetch one of those (gene id 7157 is human TNF)\n >>> egs = ec.efetch(db='gene', id=7157)\n\n # One may fetch multiple genes at a time. These are returned as an\n # EntrezgeneSet. We'll grab the first (and only) child, which returns\n # an instance of the Entrezgene class.\n >>> eg = egs.entrezgenes[0]\n\n # Easily access some basic information about the gene\n >>> eg.hgnc, eg.maploc, eg.description, eg.type, eg.genus_species\n ('TP53', '17p13.1', 'tumor protein p53', 'protein-coding', 'Homo sapiens')\n\n # get a list of genomic references\n >>> sorted([(r.acv, r.label) for r in eg.references])\n [('NC_000017.11', 'Chromosome 17 Reference GRCh38...'),\n ('NC_018928.2', 'Chromosome 17 Alternate ...'),\n ('NG_017013.2', 'RefSeqGene')]\n\n # Get the first three products defined on GRCh38\n #>>> [p.acv for p in eg.references[0].products][:3]\n #['NM_001126112.2', 'NM_001276761.1', 'NM_000546.5'] \n\n # As a sample, grab the first product defined on this reference (order is arbitrary)\n >>> mrna = eg.references[0].products[0]\n >>> str(mrna)\n 'GeneCommentary(acv=NM_001126112.2,type=mRNA,heading=Reference,label=transcript variant 2)'\n\n # mrna.genomic_coords provides access to the exon definitions on this reference\n\n >>> mrna.genomic_coords.gi, mrna.genomic_coords.strand\n ('568815581', -1)\n\n >>> mrna.genomic_coords.intervals\n [(7687376, 7687549), (7676520, 7676618), (7676381, 7676402),\n (7675993, 7676271), (7675052, 7675235), (7674858, 7674970),\n (7674180, 7674289), (7673700, 7673836), (7673534, 7673607),\n (7670608, 7670714), (7668401, 7669689)]\n\n # and the mrna has a product, the resulting protein:\n >>> str(mrna.products[0])\n 'GeneCommentary(acv=NP_001119584.1,type=peptide,heading=Reference,label=isoform a)'\n\n\n\nImportant Notes\n---------------\n\n* **You are encouraged to** `browse issues\n <https://github.com/biocommons/eutils/issues>`_. Please report any\n issues you find.\n* **Use a pip package specification to ensure stay within minor\n releases for API stability.** For example, ``eutils >=0.6,<0.7``.\n\n\nDeveloping and Contributing\n---------------------------\n\nContributions of bug reports, code patches, and documentation are\nwelcome!\n\nDevelopment occurs in the default branch. Please work in feature\nbranches or bookmarks from the default branch. Feature branches should\nbe named for the eutils issue they fix, as in\n`121-update-xml-facades`. When merging, use a commit message like\n\"closes #121: update xml facades to new-style interface\". (\"closes #n\"\nis recognized automatically and closes the ticket upon pushing.)\n\nThe included Makefile automates many tasks. In particular, `make\ndevelop` prepares a development environment and `make test` runs\nunittests. (Please run tests before committing!)\n\nAgain, thanks for your contributions.\n\n\n.. _E-utilities: http://www.ncbi.nlm.nih.gov/books/NBK25499/\n\n\n.. |build_status| image:: https://travis-ci.org/biocommons/eutils.svg?branch=master\n :target: https://travis-ci.org/biocommons/eutils\n\n.. |changelog| image:: https://img.shields.io/badge/docs-changelog-green.svg\n :target: https://eutils.readthedocs.io/en/stable/changelog/\n\n.. |contributors| image:: https://img.shields.io/github/contributors/biocommons/eutils.svg\n :target: https://github.com/biocommons/eutils\n\n.. |docs| image:: https://img.shields.io/badge/docs-readthedocs-green.svg\n :target: http://eutils.readthedocs.io/\n\n.. |issues_badge| image:: https://img.shields.io/github/issues/biocommons/eutils.png\n :target: https://github.com/biocommons/eutils/issues\n :align: middle\n\n.. |license| image:: https://img.shields.io/github/license/biocommons/eutils.svg\n :target: https://github.com/biocommons/eutils/blob/master/LICENSE\n\n.. |pypi_badge| image:: https://img.shields.io/pypi/v/eutils.svg\n :target: https://pypi.org/project/eutils/\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "\"Python interface to NCBI's eutilities API\"",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/biocommons/eutils"
},
"split_keywords": [
"bioinformatics",
"eutilities",
"ncbi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae05292de2bc244d0f5cc900bd9d63d9c3cf16dd57684859873f1c6eba4771b1",
"md5": "c1af8b37f0ff71e5565ffc9188f82db4",
"sha256": "4938c4baff6ca52141204ff3eff3a91ec1e83e52a6c5d92e7163585117b96566"
},
"downloads": -1,
"filename": "eutils-0.6.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c1af8b37f0ff71e5565ffc9188f82db4",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 41853,
"upload_time": "2019-12-17T19:19:17",
"upload_time_iso_8601": "2019-12-17T19:19:17.374836Z",
"url": "https://files.pythonhosted.org/packages/ae/05/292de2bc244d0f5cc900bd9d63d9c3cf16dd57684859873f1c6eba4771b1/eutils-0.6.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e9ab75a1cc7b0f24a568bffb2588f9a783d3d4385102c1910dfb8c9ff7bb3498",
"md5": "dbc120c7533d6ecb09a9bd82cd56e4f1",
"sha256": "3515178c0aadb836206a3eee2bc9f340f3213c13b53632e058eb58a9219d03cf"
},
"downloads": -1,
"filename": "eutils-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "dbc120c7533d6ecb09a9bd82cd56e4f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 304608,
"upload_time": "2019-12-17T19:19:18",
"upload_time_iso_8601": "2019-12-17T19:19:18.852872Z",
"url": "https://files.pythonhosted.org/packages/e9/ab/75a1cc7b0f24a568bffb2588f9a783d3d4385102c1910dfb8c9ff7bb3498/eutils-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-12-17 19:19:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "biocommons",
"github_project": "eutils",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "eutils"
}
JSON
