Skip to content

Commit 9a9869e

Browse files
rm1113rm1113
authored
Prepare release (#13)
1 parent 02cf928 commit 9a9869e

35 files changed

Lines changed: 190 additions & 598 deletions

‎.github/workflows/python-app.yml‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,7 @@ jobs:
1717
runs-on: ubuntu-latest
1818
strategy:
1919
matrix:
20-
python-version: ['3.9', '3.10', '3.11']
21-
constrain: ["-c constrain_min.txt", ""]
20+
python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
2221
steps:
2322
- uses: actions/checkout@v4
2423
- name: Set up Python ${{ matrix.python-version }}
@@ -30,7 +29,7 @@ jobs:
3029
python -m pip install --upgrade pip
3130
python -m pip install --upgrade uv
3231
uv pip install --system flake8 pytest
33-
if [ -f requirements.txt ]; then uv pip install --system -U -r requirements.txt; fi
32+
uv pip install --system -r pyproject.toml
3433
- name: Lint with flake8
3534
run: |
3635
# stop the build if there are Python syntax errors or undefined names

‎CHANGELOG.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,18 @@
11
# Changelog
22

3-
## [Unreleased]
3+
## [v1.0.0] - 2025-10-03
4+
5+
### First stable release
6+
7+
- **search_datasets** endpoint
8+
- **search_cells** endpoint
9+
- **download_urls** endpoint
10+
- **dataset_metadata** endpoint
11+
- **embedding_data** endpoint
12+
- **heatmap** endpoint
13+
- **differential_expression** endpoint
14+
- **session management** with token-based authentication
15+
416

517
## [v0.0.1] - 2024-12-12
618

‎README.md‎

Lines changed: 49 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -1,154 +1,59 @@
1-
# Python client for CAP GraphQL API
21

3-
Python client uses Ariadne code generation https://ariadnegraphql.org/blog/2023/02/02/ariadne-codegen to generate pydantic models and graphQL client.
2+
# Python client for Cell-Annotation-Platform GraphQL API
3+
[![PyPI version](https://img.shields.io/pypi/v/cap-sc-client)](https://pypi.org/project/cap-sc-client/)
44

5-
1. Add new queries to `queries.graphql`
6-
2. Run `ariadne-codegen`
5+
The Python package provides a simple interface to interact with the [Cell Annotation Platform](https://celltype.info/) (CAP) GraphQL API. The package allows to search for datasets, cell labels metadata and get molecular profiles of cell types published on CAP.
76

8-
# API calls
7+
## Installation
98

10-
Create CAP object `cap = Cap()` and use it to access public API endpoints.
9+
```bash
10+
pip install -U cap-sc-client
11+
```
1112

12-
If you plan to use CAP API endpoints that require authoriization please set environment variables either `CAP_LOGIN` / `CAP_PWD` or `CAP_TOKEN` with custom token that you can get from CAP UI. CAP will automatically use this information to authenticate you during authorized endpoints requests.
13+
## Basic usage
1314

14-
## Search datasets
15-
```Python
16-
cap.search_datasets(search=None, organism=None, tissue=None, assay=None, limit = 50, offset=0, sort=[])
17-
```
18-
returns CAP published datasets searched by a keyword that could be filtered by `organism`, `tissue` or `assay`.
19-
The result could be paginated using `limit`, `offset` and sorted using `sort` and `ASC`, `DESC` keywords
20-
21-
Example:
22-
```Python
23-
cap.search_datasets(
24-
search="blood"
25-
organism=["Homo sapiens"],
26-
tissue=["stomach","pyloric antrum"],
27-
assay=["10x 3' v1"],
28-
sort=[{'name':'ASC'}]
29-
)
30-
```
31-
Result:
32-
```Python
33-
{
34-
'results': [
35-
{
36-
'id': '420',
37-
'name': 'Charting human development ...',
38-
'description': 'Developing human multi-organ ...',
39-
'cellCount': 155232,
40-
'labelsets': [
41-
{
42-
'id': '3714',
43-
'name': 'assay',
44-
'description': None,
45-
'labels': [
46-
{
47-
'id': '25154',
48-
'name': "10x 3' v2",
49-
'count': 146343,
50-
'typename__': 'Label'
51-
}
52-
...
53-
],
54-
'typename__': 'Labelset'
55-
}
56-
...
57-
],
58-
'project': {
59-
'version': 1.0,
60-
'id': '263',
61-
'name': 'Charting human ...',
62-
'owner': {
63-
'displayName': 'CAP Data Upload'
64-
},
65-
'typename__': 'Project'
66-
}
67-
}
68-
...
69-
]
70-
}
71-
```
72-
## Dataset download URLs
73-
```Python
74-
cap.download_urls(id)
75-
```
76-
returns URLs for published dataset files: annData, Seurat, JSON (zip), JSON (tar)
15+
The main goal of the package is to provide an interface to access CAP datasets and cell label annotations collection via standard python toolings like pandas dataframes.
7716

78-
Example:
79-
```Python
80-
cap.download_urls(678)
8117
```
82-
Result:
83-
```Python
84-
{
85-
'downloadUrls': {
86-
'annDataUrl': 'https://storage.googleapis.com/...h5ad',
87-
'seuratUrl': None,
88-
'capJsonUrlTar': 'https://storage.googleapis.com/...h5ad.json.tar',
89-
'capJsonUrlZip': 'https://storage.googleapis.com/...h5ad.json.zip',
90-
'typename__': 'DatasetDownloadUrlsResponse'
91-
}
92-
}
18+
>>> from cap_sc_client import CapClient
19+
>>> cp = CapClient()
20+
>>> datasets = cp.search_datasets(limit=5, offset=0, organism=["Homo sapiens"])
21+
>>> datasets.head()
22+
id name cell_count project
23+
0 1427 Skin fibroblasts - Pan-d... 337376.0 {'id': '613', 'name': 'Pan...
24+
1 1426 Skin fibroblast scRNA-seq ... 153546.0 {'id': '613', 'name': 'Pan...
25+
2 1157 Single cell atlas of the h... 72788.0 {'id': '544', 'name': 'Sin...
26+
3 1156 snRNA-seq of human retina ... 3177310.0 {'id': '544', 'name': 'Sin...
27+
4 1154 snRNA-seq of human retina ... 691008.0 {'id': '544', 'name': 'Sin...
28+
>>> labels = cp.search_cell_labels(limit=10, offset=0)
29+
>>> labels[["full_name", "ontology_term_exists", "marker_genes"]]
30+
full_name ontology_term_exists marker_genes
31+
0 cycling stromal ... True [MKI67, TOP2A, C...
32+
1 alveolar type 1 ... True [PDPN, HOPX]
33+
2 mesoderm 2 (ZEB2) False [ZEB2]
34+
3 acinar cell True [PRSS1]
35+
4 neuron True [STMN2]
36+
5 smooth muscle cell True [DES, CNN1, ACTA...
37+
6 ciliated cell True [FOXJ1]
38+
7 Schwann cell True [MPZ]
39+
8 pancreatic cells False [PDX1]
40+
9 club cell True [SCGB1A1]
9341
```
9442

95-
## Search cell labels
96-
```Python
97-
cap.search_cell_labels(search=None, organism=None, tissue=None, assay=None, limit = 50, offset=0, sort=[])
98-
```
99-
returns cell labels from CAP published datasets searched by a keyword that could be filtered by `organism`, `tissue` or `assay`.
100-
The result could be paginated using `limit`, `offset` and sorted using `sort` and `ASC`, `DESC` keywords
101-
102-
Example:
103-
```Python
104-
cap.search_cell_labels(
105-
search="blood"
106-
organism=["Homo sapiens"],
107-
tissue=["stomach","pyloric antrum"],
108-
assay=["10x 3' v1"],
109-
sort=[{'name':'ASC'}]
110-
)
111-
```
112-
Result:
113-
```Python
114-
{
115-
'lookupCells': [
116-
{
117-
'id': '51853',
118-
'fullName': 'progenitor cell',
119-
'name': 'progenitor cell',
120-
'ontologyTermExists': True,
121-
'ontologyTermId': 'CL:0011026',
122-
'ontologyTerm': 'progenitor cell',
123-
'synonyms': ['unknown'],
124-
'categoryOntologyTermExists': True,
125-
'categoryOntologyTermId': 'CL:0011115',
126-
'categoryOntologyTerm': 'precursor cell',
127-
'categoryFullName': 'precursor cell',
128-
'markerGenes': ['EOMES'],
129-
'canonicalMarkerGenes': ['unknown'],
130-
'count': 53089,
131-
'ontologyAssessment': None,
132-
'labelset': {
133-
'id': '6387',
134-
'name': 'cell_type',
135-
'description': 'An atlas ...',
136-
'dataset': {
137-
'id': '532',
138-
'name': 'Second Trimester ...',
139-
'project': {
140-
'id': '305',
141-
'name': 'Human developing neocortex by area',
142-
'version': 1,
143-
'typename__': 'Project'
144-
},
145-
'typename__': 'Dataset'
146-
},
147-
'typename__': 'Labelset'
148-
},
149-
'typename__': 'Label'
150-
}
151-
...
152-
]
153-
}
154-
```
43+
There is also a `MDSession` class that allows to interact molecular profile of cell types within specific dataset. However, this class requires user to be familiar with CAP MD page. For more examples please refer to [examples](./examples/) folder and GitHub Wiki for detailed documentation.
44+
45+
## Documentation
46+
47+
Detailed documentation is available on [GitHub Wiki](https://github.com/cellannotation/cap-python-client/wiki).
48+
49+
50+
## Changelog
51+
52+
See [CHANGELOG.md](./CHANGELOG.md).
53+
54+
## Development
55+
56+
This project uses [Ariadne code generation](https://ariadnegraphql.org/blog/2023/02/02/ariadne-codegen) to generate pydantic models and graphQL client. In case of need to update or add new queries please follow the steps below:
57+
58+
1. Add new queries to [queries.graphql](./queries.graphql)
59+
2. Run `ariadne-codegen`

cap_client/__init__.py renamed to cap_sc_client/__init__.py

File renamed without changes.

0 commit comments

Comments
 (0)