# hubmap-api-py-client
[](https://pypi.org/project/hubmap-api-py-client/)
Python client for the [HuBMAP Cells API](https://github.com/hubmapconsortium/cross_modality_query);
See also: [`hubmap-api-js-client`](https://github.com/hubmapconsortium/hubmap-api-js-client#readme).
Contributors start [here](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/README-contrib.md#readme).
## Usage
Install from pypi:
```
pip install hubmap-api-py-client
```
Find cells with different criteria, and intersect resulting sets:
```python
>>> from os import environ
>>> from hubmap_api_py_client import Client
>>> client = Client(environ['API_ENDPOINT'])
>>> [m for m in dir(client) if m.startswith('select_')]
['select_cells', 'select_celltypes', 'select_clusters', 'select_datasets', 'select_genes', 'select_organs', 'select_proteins']
>>> gene_symbol = client.select_genes(where="modality", has=["rna"]).get_list()[0]['gene_symbol']
>>> cells_with_gene = client.select_cells(where='gene', has=[f'{gene_symbol} > 0.5'], genomic_modality='rna')
>>> assert len(cells_with_gene) > 0
# Select cells from the datasets with the following UUIDs:
>>> dataset_a_uuid = client.select_datasets(where="gene", has=[f'{gene_symbol} > 1'], genomic_modality="rna", min_cell_percentage=0.0).get_list()[0]['uuid']
>>> dataset_b_uuid = client.select_datasets(where="gene", has=[f'{gene_symbol} > 1'], genomic_modality="rna", min_cell_percentage=0.0).get_list()[1]['uuid']
>>> cells_in_a_len = len(client.select_cells(where='dataset', has=[dataset_a_uuid]))
>>> cells_in_b_len = len(client.select_cells(where='dataset', has=[dataset_b_uuid]))
>>> cells_in_datasets = client.select_cells(where='dataset', has=[dataset_a_uuid, dataset_b_uuid])
>>> cells_in_datasets_len = len(cells_in_datasets)
>>> assert cells_in_datasets_len > 0
>>> assert cells_in_datasets_len == cells_in_a_len + cells_in_b_len
# Combine criteria with intersection:
>>> cells_with_gene_in_datasets = cells_with_gene & cells_in_datasets
# Get a list; should run quickly:
>>> cell_list = cells_with_gene.get_list()
>>> cells = cell_list[0:10]
>>> assert len(cells) > 0
>>> assert cells[0].keys() == {'cell_id', 'modality', 'dataset', 'organ', 'cell_type' ,'clusters'}
```
More documentation:
- [Examples](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/)
- [`Client` pydoc](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/README-Client.txt)
- [`ResultsSet` pydoc](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/README-external.ResultsSet.txt)
- [`ResultsList` pydoc](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/README-external.ResultsList.txt)
Only some types of objects can be retrieved from other types of objects:
| `where=...` | None | `cell` | `cluster` | `dataset` | `gene` | `organ` | `protein` | `modality` | `celltype` |
|-------------------------------------------------------------------------------------------------------------------------| --------- | --------- | -------- | -------- | --------- | -------- | --------- | --------- | --------- |
| [`select_cells()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_cells.md) | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [`select_clusters()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_clusters.md) | ✓ | | ✓ | ✓ | ✓ ✩ | ✩ | ✩ | | ✓ |
| [`select_datasets()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_datasets.md) | ✓ | ✓ | ✓ | ✓ | |✶ | | ✓ | ✓ |
| [`select_genes()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_genes.md) | ✓ | | ✓ ✩ | | ✓ | ✓ ✩ | ✩ | | |
| [`select_organs()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_organs.md) | ✓ | ✓ | ✩ | ✶ | ✓ ✩ | ✓ | ✩ | | ✓ |
| [`select_proteins()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_organs.md) | ✓ | | ✩ | | ✩ | ✩ | | | |
| [`select_celltypes()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_celltypes.md) | ✓ | ✓ | ✓ | ✓ | ✩ | ✓ | | | ✓ |
- "✓" = Supported by Cells API, and this client.
- "✶" = Supported by Entities API; support in this client is [on the roadmap](https://github.com/hubmapconsortium/hubmap-api-py-client/issues/25).
- "✩" = Possible connection to [ASCT-B](https://hubmapconsortium.github.io/ccf-asct-reporter/vis?sheet=all&dataVersion=latest) (Anatomical Structures / Cell Types / Biomarkers)
Raw data
{
"_id": null,
"home_page": "https://github.com/hubmapconsortium/hubmap-api-py-client",
"name": "hubmap-api-py-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Chuck McCallum",
"author_email": "mccallucc+cells_client@gmail.com",
"download_url": null,
"platform": null,
"description": "# hubmap-api-py-client\n[](https://pypi.org/project/hubmap-api-py-client/)\n\nPython client for the [HuBMAP Cells API](https://github.com/hubmapconsortium/cross_modality_query);\nSee also: [`hubmap-api-js-client`](https://github.com/hubmapconsortium/hubmap-api-js-client#readme).\n\nContributors start [here](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/README-contrib.md#readme).\n\n## Usage\n\nInstall from pypi:\n```\npip install hubmap-api-py-client\n```\n\nFind cells with different criteria, and intersect resulting sets:\n\n```python\n>>> from os import environ\n>>> from hubmap_api_py_client import Client\n>>> client = Client(environ['API_ENDPOINT'])\n\n>>> [m for m in dir(client) if m.startswith('select_')]\n['select_cells', 'select_celltypes', 'select_clusters', 'select_datasets', 'select_genes', 'select_organs', 'select_proteins']\n\n>>> gene_symbol = client.select_genes(where=\"modality\", has=[\"rna\"]).get_list()[0]['gene_symbol']\n>>> cells_with_gene = client.select_cells(where='gene', has=[f'{gene_symbol} > 0.5'], genomic_modality='rna')\n>>> assert len(cells_with_gene) > 0\n\n# Select cells from the datasets with the following UUIDs:\n>>> dataset_a_uuid = client.select_datasets(where=\"gene\", has=[f'{gene_symbol} > 1'], genomic_modality=\"rna\", min_cell_percentage=0.0).get_list()[0]['uuid']\n>>> dataset_b_uuid = client.select_datasets(where=\"gene\", has=[f'{gene_symbol} > 1'], genomic_modality=\"rna\", min_cell_percentage=0.0).get_list()[1]['uuid']\n>>> cells_in_a_len = len(client.select_cells(where='dataset', has=[dataset_a_uuid]))\n>>> cells_in_b_len = len(client.select_cells(where='dataset', has=[dataset_b_uuid]))\n>>> cells_in_datasets = client.select_cells(where='dataset', has=[dataset_a_uuid, dataset_b_uuid])\n>>> cells_in_datasets_len = len(cells_in_datasets)\n>>> assert cells_in_datasets_len > 0\n>>> assert cells_in_datasets_len == cells_in_a_len + cells_in_b_len\n\n# Combine criteria with intersection:\n>>> cells_with_gene_in_datasets = cells_with_gene & cells_in_datasets\n\n# Get a list; should run quickly:\n>>> cell_list = cells_with_gene.get_list()\n\n>>> cells = cell_list[0:10]\n>>> assert len(cells) > 0\n>>> assert cells[0].keys() == {'cell_id', 'modality', 'dataset', 'organ', 'cell_type' ,'clusters'}\n\n```\n\nMore documentation:\n- [Examples](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/)\n- [`Client` pydoc](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/README-Client.txt)\n- [`ResultsSet` pydoc](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/README-external.ResultsSet.txt)\n- [`ResultsList` pydoc](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/README-external.ResultsList.txt)\n\n\nOnly some types of objects can be retrieved from other types of objects:\n\n| `where=...` | None | `cell` | `cluster` | `dataset` | `gene` | `organ` | `protein` | `modality` | `celltype` |\n|-------------------------------------------------------------------------------------------------------------------------| --------- | --------- | -------- | -------- | --------- | -------- | --------- | --------- | --------- |\n| [`select_cells()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_cells.md) | \u2713 | \u2713 | | \u2713 | \u2713 | \u2713 | \u2713 | \u2713 | \u2713 |\n| [`select_clusters()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_clusters.md) | \u2713 | | \u2713 | \u2713 | \u2713 \u2729 | \u2729 | \u2729 | | \u2713 |\n| [`select_datasets()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_datasets.md) | \u2713 | \u2713 | \u2713 | \u2713 | |\u2736 | | \u2713 | \u2713 |\n| [`select_genes()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_genes.md) | \u2713 | | \u2713 \u2729 | | \u2713 | \u2713 \u2729 | \u2729 | | |\n| [`select_organs()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_organs.md) | \u2713 | \u2713 | \u2729 | \u2736 | \u2713 \u2729 | \u2713 | \u2729 | | \u2713 |\n| [`select_proteins()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_organs.md) | \u2713 | | \u2729 | | \u2729 | \u2729 | | | |\n| [`select_celltypes()`](https://github.com/hubmapconsortium/hubmap-api-py-client/blob/main/examples/select_celltypes.md) | \u2713 | \u2713 | \u2713 | \u2713 | \u2729 | \u2713 | | | \u2713 |\n\n\n- \"\u2713\" = Supported by Cells API, and this client.\n- \"\u2736\" = Supported by Entities API; support in this client is [on the roadmap](https://github.com/hubmapconsortium/hubmap-api-py-client/issues/25).\n- \"\u2729\" = Possible connection to [ASCT-B](https://hubmapconsortium.github.io/ccf-asct-reporter/vis?sheet=all&dataVersion=latest) (Anatomical Structures / Cell Types / Biomarkers)\n",
"bugtrack_url": null,
"license": null,
"summary": "Client for the HuBMAP Cells API",
"version": "0.0.11",
"project_urls": {
"Homepage": "https://github.com/hubmapconsortium/hubmap-api-py-client"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "64d392e8ff84f95b3a800a54f985139ce8e40ca5b19dccb2dbad79d8c5540504",
"md5": "47805ad10e9af5b7078b46859e804590",
"sha256": "65576f80fb449688027cabd43cd7f130e52fa8f43c4e823a579b6111085203e1"
},
"downloads": -1,
"filename": "hubmap_api_py_client-0.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "47805ad10e9af5b7078b46859e804590",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8274,
"upload_time": "2024-05-01T19:15:50",
"upload_time_iso_8601": "2024-05-01T19:15:50.447452Z",
"url": "https://files.pythonhosted.org/packages/64/d3/92e8ff84f95b3a800a54f985139ce8e40ca5b19dccb2dbad79d8c5540504/hubmap_api_py_client-0.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-01 19:15:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hubmapconsortium",
"github_project": "hubmap-api-py-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
"==",
"2.25.1"
]
]
},
{
"name": null,
"specs": []
}
],
"lcname": "hubmap-api-py-client"
}
JSON
