| Name | uniprot-id-mapper JSON |
| Version |
1.1.1
JSON |
| download |
| home_page | |
| Summary | A Python wrapper for the UniProt Mapping RESTful API. |
| upload_time | 2024-01-03 09:37:41 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2023 David Araripe Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
uniprot
database
protein id
gene id
parser
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/ruff)
[](https://github.com/psf/black)
[](https://pycqa.github.io/isort/)
[](https://actions-badge.atrox.dev/David-Araripe/UniProtMapper/goto?ref=master)
[](https://pypi.org/project/uniprot-id-mapper/)
# UniProtMapper
A Python wrapper for UniProt's [Retrieve/ID Mapping](https://www.uniprot.org/id-mapping) RESTful API. This package supports the following functionalities:
1. Map (almost) any UniProt [cross-referenced IDs](https://github.com/David-Araripe/UniProtMapper/blob/master/src/UniProtMapper/resources/uniprot_mapping_dbs.json) to other identifiers & vice-versa;
2. Programmatically retrieve any of the supported [return fields](https://www.uniprot.org/help/return_fields) from both UniProt-SwissProt and UniProt-TrEMBL (unreviewed) databases;
For these, check [Example 1](#example-1-mapping-ids) and [Example 2](#example-2-retrieving-information) below. Both functionalities can also be accessed through the CLI. For more information, check [CLI](#cli).
## Installation
From PyPI:
``` Shell
python -m pip install uniprot-id-mapper
```
Directly from GitHub:
``` Shell
python -m pip install git+https://github.com/David-Araripe/UniProtMapper.git
```
From source:
``` Shell
git clone https://github.com/David-Araripe/UniProtMapper
cd UniProtMapper
python -m pip install .
```
# Usage
## Example 1: Mapping IDs
To map IDs, the user can either call the object directly or use the `get` method to obtain the response. The different identifiers that are used by the API are designated by the `from_db` and `to_db` parameters. For example:
``` python
from UniProtMapper import ProtMapper
mapper = ProtMapper()
result, failed = mapper.get(
ids=["P30542", "Q16678", "Q02880"], from_db="UniProtKB_AC-ID", to_db="Ensembl"
)
result, failed = mapper(
ids=["P30542", "Q16678", "Q02880"], from_db="UniProtKB_AC-ID", to_db="Ensembl"
)
```
Where failed corresponds to a list of the identifiers that failed to be mapped and result is the following pandas DataFrame:
| | UniProtKB_AC-ID | Ensembl |
|---:|:------------------|:-------------------|
| 0 | P30542 | ENSG00000163485.17 |
| 1 | Q16678 | ENSG00000138061.12 |
| 2 | Q02880 | ENSG00000077097.17 |
## Example 2: Retrieving information
The supported [return fields](https://www.uniprot.org/help/return_fields) are both accessible through UniProt's website or by the property `.fields_table`. For example:
```Python
from UniProtMapper import ProtMapper
mapper = ProtMapper()
df = mapper.fields_table
df.head()
```
| | Label | Legacy Returned Field | Returned Field | Field Type |
|---:|:---------------------|:------------------------|:-----------------|:-----------------|
| 0 | Entry | id | accession | Names & Taxonomy |
| 1 | Entry Name | entry name | id | Names & Taxonomy |
| 2 | Gene Names | genes | gene_names | Names & Taxonomy |
| 3 | Gene Names (primary) | genes(PREFERRED) | gene_primary | Names & Taxonomy |
| 4 | Gene Names (synonym) | genes(ALTERNATIVE) | gene_synonym | Names & Taxonomy |
To retrieve information, the user can either call the object directly or use the `get` method to obtain the response. For example:
```Python
result, failed = mapper.get(["Q02880"])
>>> Fetched: 1 / 1
result, failed = mapper(["Q02880"])
>>> Fetched: 1 / 1
```
Custom returned fields can be retrieved by passing a list of fields to the `fields` parameter. These fields need to be within `UniProtRetriever.fields_table["Returned_Field"]` and will be returned with columns named as their respective `Label`.
The object already has a list of default fields under `self.default_fields`, but these are ignored if the parameter `fields` is passed.
```Python
fields = ["accession", "organism_name", "structure_3d"]
result, failed = mapper.get(["Q02880"], fields=fields)
```
# CLI
The package also comes with a CLI that can be used to map IDs and retrieve information. To map IDs, the user can use the `protmap` command, accessible after installation. Here is a list of the available arguments, shown by `protmap -h`:
```text
usage: UniProtMapper [-h] -i [IDS ...] [-r [RETURN_FIELDS ...]] [--default-fields] [-o OUTPUT]
[-from FROM_DB] [-to TO_DB] [-over] [-pf]
Retrieve data from UniProt using UniProt's RESTful API. For a list of all available fields, see: https://www.uniprot.org/help/return_fields
Alternatively, use the --print-fields argument to print the available fields and exit the program.
optional arguments:
-h, --help show this help message and exit
-i [IDS ...], --ids [IDS ...]
List of UniProt IDs to retrieve information from. Values must be
separated by spaces.
-r [RETURN_FIELDS ...], --return-fields [RETURN_FIELDS ...]
If not defined, will pass `None`, returning all available fields.
Else, values should be fields to be returned separated by spaces. See
--print-fields for available options.
--default-fields, -def
This option will override the --return-fields option. Returns only the
default fields stored in: <pkg_path>/resources/cli_return_fields.txt
-o OUTPUT, --output OUTPUT
Path to the output file to write the returned fields. If not provided,
will write to stdout.
-from FROM_DB, --from-db FROM_DB
The database from which the IDs are. For the available cross
references, see: <pkg_path>/resources/uniprot_mapping_dbs.json
-to TO_DB, --to-db TO_DB
The database to which the IDs will be mapped. For the available cross
references, see: <pkg_path>/resources/uniprot_mapping_dbs.json
-over, --overwrite If desired to overwrite an existing file when using -o/--output
-pf, --print-fields Prints the available return fields and exits the program.
```
Usage example, retrieving default fields from `<pkg_path>/resources/cli_return_fields.txt`:
<p align="center">
<img src="https://github.com/David-Araripe/UniProtMapper/blob/master/figures/cli_example_fig.png?raw=true" alt="Image displaying the output of UniProtMapper's CLI, protmap"/>
</p>
Raw data
{
"_id": null,
"home_page": "",
"name": "uniprot-id-mapper",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "David Araripe <david.araripe17@gmail.com>",
"keywords": "uniprot,database,protein ID,gene ID,parser",
"author": "",
"author_email": "David Araripe <david.araripe17@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/cc/61/4b50fce5da35092c6a06ac2f345fab0ab3eecd2777201f9a7f8d08771bd2/uniprot-id-mapper-1.1.1.tar.gz",
"platform": null,
"description": "[](https://opensource.org/licenses/MIT)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/psf/black)\n[](https://pycqa.github.io/isort/)\n[](https://actions-badge.atrox.dev/David-Araripe/UniProtMapper/goto?ref=master)\n[](https://pypi.org/project/uniprot-id-mapper/)\n\n# UniProtMapper\n\nA Python wrapper for UniProt's [Retrieve/ID Mapping](https://www.uniprot.org/id-mapping) RESTful API. This package supports the following functionalities:\n\n1. Map (almost) any UniProt [cross-referenced IDs](https://github.com/David-Araripe/UniProtMapper/blob/master/src/UniProtMapper/resources/uniprot_mapping_dbs.json) to other identifiers & vice-versa;\n2. Programmatically retrieve any of the supported [return fields](https://www.uniprot.org/help/return_fields) from both UniProt-SwissProt and UniProt-TrEMBL (unreviewed) databases;\n\nFor these, check [Example 1](#example-1-mapping-ids) and [Example 2](#example-2-retrieving-information) below. Both functionalities can also be accessed through the CLI. For more information, check [CLI](#cli).\n\n## Installation\n\nFrom PyPI:\n``` Shell\npython -m pip install uniprot-id-mapper\n```\n\nDirectly from GitHub:\n``` Shell\npython -m pip install git+https://github.com/David-Araripe/UniProtMapper.git\n```\n\nFrom source:\n``` Shell\ngit clone https://github.com/David-Araripe/UniProtMapper\ncd UniProtMapper\npython -m pip install .\n```\n# Usage\n## Example 1: Mapping IDs\nTo map IDs, the user can either call the object directly or use the `get` method to obtain the response. The different identifiers that are used by the API are designated by the `from_db` and `to_db` parameters. For example:\n\n``` python\nfrom UniProtMapper import ProtMapper\n\nmapper = ProtMapper()\n\nresult, failed = mapper.get(\n ids=[\"P30542\", \"Q16678\", \"Q02880\"], from_db=\"UniProtKB_AC-ID\", to_db=\"Ensembl\"\n)\n\nresult, failed = mapper(\n ids=[\"P30542\", \"Q16678\", \"Q02880\"], from_db=\"UniProtKB_AC-ID\", to_db=\"Ensembl\"\n)\n```\nWhere failed corresponds to a list of the identifiers that failed to be mapped and result is the following pandas DataFrame:\n\n| | UniProtKB_AC-ID | Ensembl |\n|---:|:------------------|:-------------------|\n| 0 | P30542 | ENSG00000163485.17 |\n| 1 | Q16678 | ENSG00000138061.12 |\n| 2 | Q02880 | ENSG00000077097.17 |\n\n## Example 2: Retrieving information\n\nThe supported [return fields](https://www.uniprot.org/help/return_fields) are both accessible through UniProt's website or by the property `.fields_table`. For example:\n\n```Python\nfrom UniProtMapper import ProtMapper\n\nmapper = ProtMapper()\ndf = mapper.fields_table\ndf.head()\n```\n| | Label | Legacy Returned Field | Returned Field | Field Type |\n|---:|:---------------------|:------------------------|:-----------------|:-----------------|\n| 0 | Entry | id | accession | Names & Taxonomy |\n| 1 | Entry Name | entry name | id | Names & Taxonomy |\n| 2 | Gene Names | genes | gene_names | Names & Taxonomy |\n| 3 | Gene Names (primary) | genes(PREFERRED) | gene_primary | Names & Taxonomy |\n| 4 | Gene Names (synonym) | genes(ALTERNATIVE) | gene_synonym | Names & Taxonomy |\n\nTo retrieve information, the user can either call the object directly or use the `get` method to obtain the response. For example:\n\n```Python\nresult, failed = mapper.get([\"Q02880\"])\n>>> Fetched: 1 / 1\n\nresult, failed = mapper([\"Q02880\"])\n>>> Fetched: 1 / 1\n```\n\nCustom returned fields can be retrieved by passing a list of fields to the `fields` parameter. These fields need to be within `UniProtRetriever.fields_table[\"Returned_Field\"]` and will be returned with columns named as their respective `Label`.\n\nThe object already has a list of default fields under `self.default_fields`, but these are ignored if the parameter `fields` is passed.\n\n```Python\nfields = [\"accession\", \"organism_name\", \"structure_3d\"]\nresult, failed = mapper.get([\"Q02880\"], fields=fields)\n```\n\n# CLI\n\nThe package also comes with a CLI that can be used to map IDs and retrieve information. To map IDs, the user can use the `protmap` command, accessible after installation. Here is a list of the available arguments, shown by `protmap -h`:\n\n```text\nusage: UniProtMapper [-h] -i [IDS ...] [-r [RETURN_FIELDS ...]] [--default-fields] [-o OUTPUT]\n [-from FROM_DB] [-to TO_DB] [-over] [-pf]\n\nRetrieve data from UniProt using UniProt's RESTful API. For a list of all available fields, see: https://www.uniprot.org/help/return_fields \n\nAlternatively, use the --print-fields argument to print the available fields and exit the program.\n\noptional arguments:\n -h, --help show this help message and exit\n -i [IDS ...], --ids [IDS ...]\n List of UniProt IDs to retrieve information from. Values must be\n separated by spaces.\n -r [RETURN_FIELDS ...], --return-fields [RETURN_FIELDS ...]\n If not defined, will pass `None`, returning all available fields.\n Else, values should be fields to be returned separated by spaces. See\n --print-fields for available options.\n --default-fields, -def\n This option will override the --return-fields option. Returns only the\n default fields stored in: <pkg_path>/resources/cli_return_fields.txt\n -o OUTPUT, --output OUTPUT\n Path to the output file to write the returned fields. If not provided,\n will write to stdout.\n -from FROM_DB, --from-db FROM_DB\n The database from which the IDs are. For the available cross\n references, see: <pkg_path>/resources/uniprot_mapping_dbs.json\n -to TO_DB, --to-db TO_DB\n The database to which the IDs will be mapped. For the available cross\n references, see: <pkg_path>/resources/uniprot_mapping_dbs.json\n -over, --overwrite If desired to overwrite an existing file when using -o/--output\n -pf, --print-fields Prints the available return fields and exits the program.\n ```\n\nUsage example, retrieving default fields from `<pkg_path>/resources/cli_return_fields.txt`:\n<p align=\"center\">\n <img src=\"https://github.com/David-Araripe/UniProtMapper/blob/master/figures/cli_example_fig.png?raw=true\" alt=\"Image displaying the output of UniProtMapper's CLI, protmap\"/>\n</p>\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 David Araripe Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "A Python wrapper for the UniProt Mapping RESTful API.",
"version": "1.1.1",
"project_urls": {
"homepage": "https://github.com/David-Araripe/UniProtMapper",
"repository": "https://github.com/David-Araripe/UniProtMapper"
},
"split_keywords": [
"uniprot",
"database",
"protein id",
"gene id",
"parser"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bb7b222bd1e37e9119619df77c389154da4a575a85c837e9e309ec2afa46b62e",
"md5": "255f1020aceb62387d4944fd4ddc57b6",
"sha256": "8d3789f65054ea6a4a8d575e12bfe6d1ef016d77a1b945de6d8975dbd206787f"
},
"downloads": -1,
"filename": "uniprot_id_mapper-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "255f1020aceb62387d4944fd4ddc57b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 35934,
"upload_time": "2024-01-03T09:37:39",
"upload_time_iso_8601": "2024-01-03T09:37:39.676293Z",
"url": "https://files.pythonhosted.org/packages/bb/7b/222bd1e37e9119619df77c389154da4a575a85c837e9e309ec2afa46b62e/uniprot_id_mapper-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cc614b50fce5da35092c6a06ac2f345fab0ab3eecd2777201f9a7f8d08771bd2",
"md5": "170f17bb4a060c4d661bb514c6a266f2",
"sha256": "d73bc222939f12658cd159d5b9391c1d73d1ccd0d31e5c61bcd961efa2a517a9"
},
"downloads": -1,
"filename": "uniprot-id-mapper-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "170f17bb4a060c4d661bb514c6a266f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 36429,
"upload_time": "2024-01-03T09:37:41",
"upload_time_iso_8601": "2024-01-03T09:37:41.152748Z",
"url": "https://files.pythonhosted.org/packages/cc/61/4b50fce5da35092c6a06ac2f345fab0ab3eecd2777201f9a7f8d08771bd2/uniprot-id-mapper-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-03 09:37:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "David-Araripe",
"github_project": "UniProtMapper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "uniprot-id-mapper"
}
