ag2kit 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ag2kit-0.1.0/.gitignore +24 -0
- ag2kit-0.1.0/LICENSE +21 -0
- ag2kit-0.1.0/PKG-INFO +211 -0
- ag2kit-0.1.0/README.md +178 -0
- ag2kit-0.1.0/docs/api.md +215 -0
- ag2kit-0.1.0/docs/methods.md +97 -0
- ag2kit-0.1.0/examples/gtex_eqtl_eval.py +98 -0
- ag2kit-0.1.0/pyproject.toml +86 -0
- ag2kit-0.1.0/src/ag2kit/__init__.py +65 -0
- ag2kit-0.1.0/src/ag2kit/client.py +940 -0
- ag2kit-0.1.0/src/ag2kit/evaluate.py +351 -0
- ag2kit-0.1.0/src/ag2kit/gtex.py +275 -0
- ag2kit-0.1.0/src/ag2kit/io.py +248 -0
- ag2kit-0.1.0/src/ag2kit/provenance.py +316 -0
- ag2kit-0.1.0/src/ag2kit/py.typed +0 -0
- ag2kit-0.1.0/src/ag2kit/stats.py +375 -0
- ag2kit-0.1.0/src/ag2kit/variants.py +241 -0
- ag2kit-0.1.0/tests/conftest.py +16 -0
- ag2kit-0.1.0/tests/data/gtex_v10_mx1_whole_blood.json +227 -0
- ag2kit-0.1.0/tests/test_ag2kit.py +297 -0
- ag2kit-0.1.0/tests/test_client.py +587 -0
- ag2kit-0.1.0/tests/test_evaluate.py +326 -0
- ag2kit-0.1.0/tests/test_io.py +298 -0
- ag2kit-0.1.0/tests/test_release.py +154 -0
ag2kit-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Local data, downloads, model responses and run output: never committed.
|
|
2
|
+
cache/
|
|
3
|
+
results/
|
|
4
|
+
.env
|
|
5
|
+
|
|
6
|
+
# Python and tooling
|
|
7
|
+
.venv/
|
|
8
|
+
__pycache__/
|
|
9
|
+
*.pyc
|
|
10
|
+
.pytest_cache/
|
|
11
|
+
.ruff_cache/
|
|
12
|
+
.mypy_cache/
|
|
13
|
+
.hypothesis/
|
|
14
|
+
.coverage
|
|
15
|
+
coverage.xml
|
|
16
|
+
dist/
|
|
17
|
+
build/
|
|
18
|
+
*.egg-info/
|
|
19
|
+
|
|
20
|
+
# Editors and OS
|
|
21
|
+
.claude/
|
|
22
|
+
.idea/
|
|
23
|
+
.vscode/
|
|
24
|
+
.DS_Store
|
ag2kit-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Peter Yao
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
ag2kit-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: ag2kit
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Reproducible AlphaGenome 2 variant-effect analysis: VCF/Parquet input, resumable cached scoring, GTEx eQTL evaluation
|
|
5
|
+
Project-URL: Homepage, https://github.com/zeyuyaoy/alphagenome-research
|
|
6
|
+
Project-URL: Issues, https://github.com/zeyuyaoy/alphagenome-research/issues
|
|
7
|
+
Author: Peter Yao
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: GTEx,VCF,alphagenome,bioinformatics,eQTL,genomics,variant effect prediction
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Requires-Dist: numpy>=1.26
|
|
23
|
+
Requires-Dist: pandas-stubs~=2.3.3
|
|
24
|
+
Requires-Dist: pandas>=2.1
|
|
25
|
+
Requires-Dist: pyarrow>=14
|
|
26
|
+
Requires-Dist: requests>=2.31
|
|
27
|
+
Requires-Dist: scipy>=1.11
|
|
28
|
+
Provides-Extra: model
|
|
29
|
+
Requires-Dist: alphagenome<3,>=2.0.0; extra == 'model'
|
|
30
|
+
Provides-Extra: vcf
|
|
31
|
+
Requires-Dist: pysam>=0.22; extra == 'vcf'
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
|
|
34
|
+
### ag2kit: reproducible variant-effect analysis with the AlphaGenome SDK
|
|
35
|
+
|
|
36
|
+
AlphaGenome predicts how non-coding DNA variants affect gene regulation [1]. AlphaGenome 2 also supports predictions conditioned on a reference cell type, tissue, or single-cell dataset [4]. Its SDK handles individual predictions and batch scoring. Evaluating those predictions against observed effects requires additional steps, including input validation, allele matching, error handling, and uncertainty estimation that accounts for linkage disequilibrium.
|
|
37
|
+
|
|
38
|
+
`ag2kit` brings these steps into a Python workflow. It scores variants with the official [`alphagenome`](https://github.com/google-deepmind/alphagenome) SDK, caches results to resume interrupted runs, and compares predicted gene-expression effects with expression quantitative trait locus (eQTL) data from sources such as the Genotype-Tissue Expression (GTEx) project.
|
|
39
|
+
|
|
40
|
+
The package covers four tasks:
|
|
41
|
+
|
|
42
|
+
| Capability | Description |
|
|
43
|
+
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
44
|
+
| Variant input | `read_variants` loads VCF/BCF (via `pysam`), delimited text, Parquet, and DataFrames into a common GRCh38 schema. It splits multiallelic records, assigns an `input_status` to every row, and optionally checks REF alleles against an indexed FASTA. |
|
|
45
|
+
| Scoring | `AG2Client.score_variants` caches complete SDK results for each unique request. Scoring one variant against multiple genes uses one API call. Runs can resume after interruption, and failed requests receive error records. Output rows retain their input order. |
|
|
46
|
+
| Observed effects | `ag2kit.gtex` retrieves significant single-tissue eQTLs from GTEx Portal API v2 (GTEx v8, v10, and v11) or reads downloaded significant-pairs files [2]. |
|
|
47
|
+
| Evaluation | `evaluate` orients observed effects to the predicted ALT allele and records a `pair_status` for every pair. It reports sign AUROC, signed Spearman correlation, and sign accuracy, with gene-cluster bootstrap intervals and optional tissue weighting. |
|
|
48
|
+
|
|
49
|
+
> [!NOTE]
|
|
50
|
+
> Use the official SDK for single predictions, track plots, in-silico mutagenesis, and gene annotation (`alphagenome.data.gene_annotation`). Use separate tools for liftover and summary-statistic quality control. For indel normalisation, use `bcftools norm` [3].
|
|
51
|
+
|
|
52
|
+
#### Installation
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pip install "ag2kit[model,vcf]"
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Python 3.11 or later is required.
|
|
59
|
+
|
|
60
|
+
Install the `model` extra for the AlphaGenome SDK (2.x) and the `vcf` extra for VCF/BCF and FASTA support through `pysam`.
|
|
61
|
+
|
|
62
|
+
For live scoring, set the `ALPHA_GENOME_API_KEY` environment variable (see [`.env.example`](.env.example)).
|
|
63
|
+
|
|
64
|
+
#### Quick start
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
import pandas as pd
|
|
68
|
+
|
|
69
|
+
import ag2kit
|
|
70
|
+
|
|
71
|
+
variants = ag2kit.read_variants(
|
|
72
|
+
pd.DataFrame(
|
|
73
|
+
{
|
|
74
|
+
"chrom": ["21", "21"],
|
|
75
|
+
"pos": [41422154, 41422154],
|
|
76
|
+
"ref": ["T", "T"],
|
|
77
|
+
"alt": ["C", "<DEL>"],
|
|
78
|
+
"id": ["rs_example", "sv1"],
|
|
79
|
+
}
|
|
80
|
+
)
|
|
81
|
+
)
|
|
82
|
+
print(variants[["variant_id", "source_id", "input_status"]])
|
|
83
|
+
|
|
84
|
+
client = ag2kit.AG2Client()
|
|
85
|
+
plan = client.score_variants(variants, condition="UBERON:0013756", scorer="RNA_SEQ")
|
|
86
|
+
print(plan[["input_variant_id", "status", "error"]])
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
> [!NOTE]
|
|
90
|
+
> By default, `dry_run=True` plans requests without contacting the API. It also shows how input validation rejects a symbolic ALT allele.
|
|
91
|
+
|
|
92
|
+
#### Evaluating predictions against GTEx
|
|
93
|
+
|
|
94
|
+
Using the `ALPHA_GENOME_API_KEY`, the next example scores significant Whole Blood eQTL pairs for `MX1` and `OAS1`, then evaluates the results:
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
import ag2kit
|
|
98
|
+
from ag2kit import gtex
|
|
99
|
+
|
|
100
|
+
observed = gtex.eqtls(["MX1", "OAS1"], tissue="Whole_Blood", dataset="gtex_v10")
|
|
101
|
+
|
|
102
|
+
client = ag2kit.AG2Client(dry_run=False)
|
|
103
|
+
predictions = client.score_variants(
|
|
104
|
+
observed,
|
|
105
|
+
condition="UBERON:0013756", # Whole Blood; gtex.tissues() lists each tissue's UBERON ID
|
|
106
|
+
scorer="RNA_SEQ",
|
|
107
|
+
gene_column="gene_id",
|
|
108
|
+
tracks={"imputation_mode": "observed"},
|
|
109
|
+
)
|
|
110
|
+
predictions.to_parquet("predictions.parquet")
|
|
111
|
+
|
|
112
|
+
evaluation = ag2kit.evaluate(predictions, observed, match={"ontology_id": "condition"})
|
|
113
|
+
evaluation.summary()
|
|
114
|
+
evaluation.save("results/")
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
The `tracks={"imputation_mode": "observed"}` option limits gene-effect calculations to tracks observed during training. See [Gene-level effect estimation](docs/methods.md#gene-level-effect-estimation).
|
|
118
|
+
|
|
119
|
+
For a command-line workflow, use [`examples/gtex_eqtl_eval.py`](examples/gtex_eqtl_eval.py). It also generates a scatter plot with `matplotlib`, which must be installed separately.
|
|
120
|
+
|
|
121
|
+
> [!WARNING]
|
|
122
|
+
> Without an API key, the script downloads GTEx data and estimates the API requests needed for scoring.
|
|
123
|
+
|
|
124
|
+
You can also call `evaluate` on any two tables with the required columns. The following example uses synthetic data:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
import pandas as pd
|
|
128
|
+
|
|
129
|
+
import ag2kit
|
|
130
|
+
|
|
131
|
+
pred = pd.DataFrame(
|
|
132
|
+
{
|
|
133
|
+
"chrom": "chr1",
|
|
134
|
+
"pos": [100, 200, 300, 400],
|
|
135
|
+
"ref": "A",
|
|
136
|
+
"alt": "G",
|
|
137
|
+
"gene_id": ["G1", "G1", "G2", "G2"],
|
|
138
|
+
"raw_effect": [0.4, -0.1, 0.3, -0.5],
|
|
139
|
+
"status": "completed",
|
|
140
|
+
}
|
|
141
|
+
)
|
|
142
|
+
obs = pd.DataFrame(
|
|
143
|
+
{
|
|
144
|
+
"chrom": "1",
|
|
145
|
+
"pos": [100, 200, 300, 400],
|
|
146
|
+
"ref": "A",
|
|
147
|
+
"alt": "G",
|
|
148
|
+
"gene_id": ["G1", "G1", "G2", "G2"],
|
|
149
|
+
"beta": [0.2, 0.1, -0.3, 0.6],
|
|
150
|
+
"effect_allele": ["G", "A", "A", "A"],
|
|
151
|
+
}
|
|
152
|
+
)
|
|
153
|
+
result = ag2kit.evaluate(pred, obs, n_boot=200)
|
|
154
|
+
print(result.metrics[["metric", "estimate", "ci95_low", "ci95_high", "n_clusters"]])
|
|
155
|
+
print(result.pairs[["pos", "beta", "beta_alt", "allele_flipped", "pair_status"]])
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Confidence intervals are `NaN` when fewer than five gene clusters are available.
|
|
159
|
+
|
|
160
|
+
#### Conditioning
|
|
161
|
+
|
|
162
|
+
Each AlphaGenome 2 request uses one conditioning input. You can choose one of two formats:
|
|
163
|
+
|
|
164
|
+
1. **Reference condition:** Set `condition` to an ontology CURIE such as `UBERON:0013756`, or a composite such as `UBERON:0000178_CL:0001054`. Use a scorer such as `RNA_SEQ`.
|
|
165
|
+
2. **Single-cell data:** Set `conditioning` to an `AnnData` object containing raw UMI counts. Use Ensembl IDs for `var_names` and include up to 256 cells. Set `condition_label` and use `SC_GENE_EXPRESSION_DENOISED`.
|
|
166
|
+
|
|
167
|
+
To find valid reference conditions, call `supported_conditions()`. For finer control, build `RequestSpec` objects and use `score` or `score_many`. You can then inspect cached SDK tracks through `AG2Client.raw_scores`.
|
|
168
|
+
|
|
169
|
+
#### Interpretation and limitations
|
|
170
|
+
|
|
171
|
+
- `RNA_SEQ` predicts log fold changes, while GTEx reports slopes for normalised expression. Accordingly, `ag2kit` compares the direction and rank of effects.
|
|
172
|
+
- GTEx significant-pairs files contain selected eQTL associations, and many variants linked to the same gene are in linkage disequilibrium. As a result, sign metrics may be higher than those measured across all tested pairs. By default, bootstrap intervals resample whole genes to account for within-gene dependence.
|
|
173
|
+
- Sign agreement describes performance at the tested loci. It does not establish causality or resolve individual variant effects. In addition, the p-values from `concordance`, `spearman`, and `mcnemar` assume independent pairs, so `evaluate` leaves them out.
|
|
174
|
+
- All coordinates are GRCh38 and 1-based. The package performs no liftover. The API does not expose a model revision, so reproducible reruns depend on cached results ([Reproducibility](docs/api.md#reproducibility)). Tests cover the implementation, but the package has not reproduced a published AlphaGenome benchmark. See [Implementation validation](docs/methods.md#implementation-validation) and [Scope and limitations](docs/methods.md#scope-and-limitations).
|
|
175
|
+
- Finally, AlphaGenome outputs are subject to the SDK's usage restrictions: non-commercial research only, with no use for training other machine-learning models or making clinical decisions. The AlphaGenome terms also govern cached and shared outputs. When using GTEx data, acknowledge the GTEx Project [2].
|
|
176
|
+
|
|
177
|
+
#### Documentation
|
|
178
|
+
|
|
179
|
+
| Page | Content |
|
|
180
|
+
|------------------------------------|---------------------------------------------------------------------------------------------------------------------|
|
|
181
|
+
| [docs/methods.md](docs/methods.md) | Request identity, gene-level reduction, allele orientation, metrics, bootstrap, statistical assumptions, validation |
|
|
182
|
+
| [docs/api.md](docs/api.md) | Public interface, output schemas, environment variables, caches, provenance, reproducibility |
|
|
183
|
+
|
|
184
|
+
#### Development
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
uv sync --extra model --extra vcf
|
|
188
|
+
uv run pytest
|
|
189
|
+
uv run ruff check . && uv run ruff format --check . && uv run mypy
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
By default, tests run offline using a pinned GTEx Portal response. To run the live test, set `ALPHA_GENOME_API_KEY` and execute `uv run pytest -m live`.
|
|
193
|
+
|
|
194
|
+
#### Licence
|
|
195
|
+
|
|
196
|
+
`ag2kit` is licensed under MIT ([LICENSE](LICENSE)); the `alphagenome` SDK is licensed separately under Apache 2.0. AlphaGenome's terms of use govern API access and outputs.
|
|
197
|
+
|
|
198
|
+
#### References
|
|
199
|
+
|
|
200
|
+
> [!NOTE]
|
|
201
|
+
> For GTEx v10 and v11, cite reference 2 and include the Portal release and access date.
|
|
202
|
+
|
|
203
|
+
1. Avsec, Ž. *et al.* Advancing regulatory variant effect prediction with AlphaGenome. *Nature* **649**, 1206–1218 (2026). doi:[10.1038/s41586-025-10014-0](https://doi.org/10.1038/s41586-025-10014-0)
|
|
204
|
+
2. GTEx Consortium. The GTEx Consortium atlas of genetic regulatory effects across human tissues. *Science* **369**, 1318–1330 (2020). doi:[10.1126/science.aaz1776](https://doi.org/10.1126/science.aaz1776)
|
|
205
|
+
3. Danecek, P. *et al.* Twelve years of SAMtools and BCFtools. *GigaScience* **10**, giab008 (2021). doi:[10.1093/gigascience/giab008](https://doi.org/10.1093/gigascience/giab008)
|
|
206
|
+
4. Google DeepMind. AlphaGenome 2: deciphering how cells read DNA to better understand disease (announcement, 11 November 2026). <https://deepmind.google/blog/alphagenome-2-deciphering-how-cells-read-dna-to-better-understand-disease/>
|
|
207
|
+
5. Hanley, J. A. & McNeil, B. J. The meaning and use of the area under a receiver operating characteristic (ROC) curve. *Radiology* **143**, 29–36 (1982). doi:[10.1148/radiology.143.1.7063747](https://doi.org/10.1148/radiology.143.1.7063747)
|
|
208
|
+
6. Davison, A. C. & Hinkley, D. V. *Bootstrap Methods and their Application* (Cambridge University Press, 1997). doi:[10.1017/CBO9780511802843](https://doi.org/10.1017/CBO9780511802843)
|
|
209
|
+
7. Field, C. A. & Welsh, A. H. Bootstrapping clustered data. *J. R. Stat. Soc. B* **69**, 369–390 (2007). doi:[10.1111/j.1467-9868.2007.00593.x](https://doi.org/10.1111/j.1467-9868.2007.00593.x)
|
|
210
|
+
8. McNemar, Q. Note on the sampling error of the difference between correlated proportions or percentages. *Psychometrika* **12**, 153–157 (1947). doi:[10.1007/BF02295996](https://doi.org/10.1007/BF02295996)
|
|
211
|
+
9. Mohammadi, P., Castel, S. E., Brown, A. A. & Lappalainen, T. Quantifying the regulatory effect size of cis-acting genetic variation using allelic fold change. *Genome Res.* **27**, 1872–1884 (2017). doi:[10.1101/gr.216747.116](https://doi.org/10.1101/gr.216747.116)
|
ag2kit-0.1.0/README.md
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
### ag2kit: reproducible variant-effect analysis with the AlphaGenome SDK
|
|
2
|
+
|
|
3
|
+
AlphaGenome predicts how non-coding DNA variants affect gene regulation [1]. AlphaGenome 2 also supports predictions conditioned on a reference cell type, tissue, or single-cell dataset [4]. Its SDK handles individual predictions and batch scoring. Evaluating those predictions against observed effects requires additional steps, including input validation, allele matching, error handling, and uncertainty estimation that accounts for linkage disequilibrium.
|
|
4
|
+
|
|
5
|
+
`ag2kit` brings these steps into a Python workflow. It scores variants with the official [`alphagenome`](https://github.com/google-deepmind/alphagenome) SDK, caches results to resume interrupted runs, and compares predicted gene-expression effects with expression quantitative trait locus (eQTL) data from sources such as the Genotype-Tissue Expression (GTEx) project.
|
|
6
|
+
|
|
7
|
+
The package covers four tasks:
|
|
8
|
+
|
|
9
|
+
| Capability | Description |
|
|
10
|
+
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
11
|
+
| Variant input | `read_variants` loads VCF/BCF (via `pysam`), delimited text, Parquet, and DataFrames into a common GRCh38 schema. It splits multiallelic records, assigns an `input_status` to every row, and optionally checks REF alleles against an indexed FASTA. |
|
|
12
|
+
| Scoring | `AG2Client.score_variants` caches complete SDK results for each unique request. Scoring one variant against multiple genes uses one API call. Runs can resume after interruption, and failed requests receive error records. Output rows retain their input order. |
|
|
13
|
+
| Observed effects | `ag2kit.gtex` retrieves significant single-tissue eQTLs from GTEx Portal API v2 (GTEx v8, v10, and v11) or reads downloaded significant-pairs files [2]. |
|
|
14
|
+
| Evaluation | `evaluate` orients observed effects to the predicted ALT allele and records a `pair_status` for every pair. It reports sign AUROC, signed Spearman correlation, and sign accuracy, with gene-cluster bootstrap intervals and optional tissue weighting. |
|
|
15
|
+
|
|
16
|
+
> [!NOTE]
|
|
17
|
+
> Use the official SDK for single predictions, track plots, in-silico mutagenesis, and gene annotation (`alphagenome.data.gene_annotation`). Use separate tools for liftover and summary-statistic quality control. For indel normalisation, use `bcftools norm` [3].
|
|
18
|
+
|
|
19
|
+
#### Installation
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pip install "ag2kit[model,vcf]"
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Python 3.11 or later is required.
|
|
26
|
+
|
|
27
|
+
Install the `model` extra for the AlphaGenome SDK (2.x) and the `vcf` extra for VCF/BCF and FASTA support through `pysam`.
|
|
28
|
+
|
|
29
|
+
For live scoring, set the `ALPHA_GENOME_API_KEY` environment variable (see [`.env.example`](.env.example)).
|
|
30
|
+
|
|
31
|
+
#### Quick start
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
import pandas as pd
|
|
35
|
+
|
|
36
|
+
import ag2kit
|
|
37
|
+
|
|
38
|
+
variants = ag2kit.read_variants(
|
|
39
|
+
pd.DataFrame(
|
|
40
|
+
{
|
|
41
|
+
"chrom": ["21", "21"],
|
|
42
|
+
"pos": [41422154, 41422154],
|
|
43
|
+
"ref": ["T", "T"],
|
|
44
|
+
"alt": ["C", "<DEL>"],
|
|
45
|
+
"id": ["rs_example", "sv1"],
|
|
46
|
+
}
|
|
47
|
+
)
|
|
48
|
+
)
|
|
49
|
+
print(variants[["variant_id", "source_id", "input_status"]])
|
|
50
|
+
|
|
51
|
+
client = ag2kit.AG2Client()
|
|
52
|
+
plan = client.score_variants(variants, condition="UBERON:0013756", scorer="RNA_SEQ")
|
|
53
|
+
print(plan[["input_variant_id", "status", "error"]])
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
> [!NOTE]
|
|
57
|
+
> By default, `dry_run=True` plans requests without contacting the API. It also shows how input validation rejects a symbolic ALT allele.
|
|
58
|
+
|
|
59
|
+
#### Evaluating predictions against GTEx
|
|
60
|
+
|
|
61
|
+
Using the `ALPHA_GENOME_API_KEY`, the next example scores significant Whole Blood eQTL pairs for `MX1` and `OAS1`, then evaluates the results:
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
import ag2kit
|
|
65
|
+
from ag2kit import gtex
|
|
66
|
+
|
|
67
|
+
observed = gtex.eqtls(["MX1", "OAS1"], tissue="Whole_Blood", dataset="gtex_v10")
|
|
68
|
+
|
|
69
|
+
client = ag2kit.AG2Client(dry_run=False)
|
|
70
|
+
predictions = client.score_variants(
|
|
71
|
+
observed,
|
|
72
|
+
condition="UBERON:0013756", # Whole Blood; gtex.tissues() lists each tissue's UBERON ID
|
|
73
|
+
scorer="RNA_SEQ",
|
|
74
|
+
gene_column="gene_id",
|
|
75
|
+
tracks={"imputation_mode": "observed"},
|
|
76
|
+
)
|
|
77
|
+
predictions.to_parquet("predictions.parquet")
|
|
78
|
+
|
|
79
|
+
evaluation = ag2kit.evaluate(predictions, observed, match={"ontology_id": "condition"})
|
|
80
|
+
evaluation.summary()
|
|
81
|
+
evaluation.save("results/")
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The `tracks={"imputation_mode": "observed"}` option limits gene-effect calculations to tracks observed during training. See [Gene-level effect estimation](docs/methods.md#gene-level-effect-estimation).
|
|
85
|
+
|
|
86
|
+
For a command-line workflow, use [`examples/gtex_eqtl_eval.py`](examples/gtex_eqtl_eval.py). It also generates a scatter plot with `matplotlib`, which must be installed separately.
|
|
87
|
+
|
|
88
|
+
> [!WARNING]
|
|
89
|
+
> Without an API key, the script downloads GTEx data and estimates the API requests needed for scoring.
|
|
90
|
+
|
|
91
|
+
You can also call `evaluate` on any two tables with the required columns. The following example uses synthetic data:
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
import pandas as pd
|
|
95
|
+
|
|
96
|
+
import ag2kit
|
|
97
|
+
|
|
98
|
+
pred = pd.DataFrame(
|
|
99
|
+
{
|
|
100
|
+
"chrom": "chr1",
|
|
101
|
+
"pos": [100, 200, 300, 400],
|
|
102
|
+
"ref": "A",
|
|
103
|
+
"alt": "G",
|
|
104
|
+
"gene_id": ["G1", "G1", "G2", "G2"],
|
|
105
|
+
"raw_effect": [0.4, -0.1, 0.3, -0.5],
|
|
106
|
+
"status": "completed",
|
|
107
|
+
}
|
|
108
|
+
)
|
|
109
|
+
obs = pd.DataFrame(
|
|
110
|
+
{
|
|
111
|
+
"chrom": "1",
|
|
112
|
+
"pos": [100, 200, 300, 400],
|
|
113
|
+
"ref": "A",
|
|
114
|
+
"alt": "G",
|
|
115
|
+
"gene_id": ["G1", "G1", "G2", "G2"],
|
|
116
|
+
"beta": [0.2, 0.1, -0.3, 0.6],
|
|
117
|
+
"effect_allele": ["G", "A", "A", "A"],
|
|
118
|
+
}
|
|
119
|
+
)
|
|
120
|
+
result = ag2kit.evaluate(pred, obs, n_boot=200)
|
|
121
|
+
print(result.metrics[["metric", "estimate", "ci95_low", "ci95_high", "n_clusters"]])
|
|
122
|
+
print(result.pairs[["pos", "beta", "beta_alt", "allele_flipped", "pair_status"]])
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Confidence intervals are `NaN` when fewer than five gene clusters are available.
|
|
126
|
+
|
|
127
|
+
#### Conditioning
|
|
128
|
+
|
|
129
|
+
Each AlphaGenome 2 request uses one conditioning input. You can choose one of two formats:
|
|
130
|
+
|
|
131
|
+
1. **Reference condition:** Set `condition` to an ontology CURIE such as `UBERON:0013756`, or a composite such as `UBERON:0000178_CL:0001054`. Use a scorer such as `RNA_SEQ`.
|
|
132
|
+
2. **Single-cell data:** Set `conditioning` to an `AnnData` object containing raw UMI counts. Use Ensembl IDs for `var_names` and include up to 256 cells. Set `condition_label` and use `SC_GENE_EXPRESSION_DENOISED`.
|
|
133
|
+
|
|
134
|
+
To find valid reference conditions, call `supported_conditions()`. For finer control, build `RequestSpec` objects and use `score` or `score_many`. You can then inspect cached SDK tracks through `AG2Client.raw_scores`.
|
|
135
|
+
|
|
136
|
+
#### Interpretation and limitations
|
|
137
|
+
|
|
138
|
+
- `RNA_SEQ` predicts log fold changes, while GTEx reports slopes for normalised expression. Accordingly, `ag2kit` compares the direction and rank of effects.
|
|
139
|
+
- GTEx significant-pairs files contain selected eQTL associations, and many variants linked to the same gene are in linkage disequilibrium. As a result, sign metrics may be higher than those measured across all tested pairs. By default, bootstrap intervals resample whole genes to account for within-gene dependence.
|
|
140
|
+
- Sign agreement describes performance at the tested loci. It does not establish causality or resolve individual variant effects. In addition, the p-values from `concordance`, `spearman`, and `mcnemar` assume independent pairs, so `evaluate` leaves them out.
|
|
141
|
+
- All coordinates are GRCh38 and 1-based. The package performs no liftover. The API does not expose a model revision, so reproducible reruns depend on cached results ([Reproducibility](docs/api.md#reproducibility)). Tests cover the implementation, but the package has not reproduced a published AlphaGenome benchmark. See [Implementation validation](docs/methods.md#implementation-validation) and [Scope and limitations](docs/methods.md#scope-and-limitations).
|
|
142
|
+
- Finally, AlphaGenome outputs are subject to the SDK's usage restrictions: non-commercial research only, with no use for training other machine-learning models or making clinical decisions. The AlphaGenome terms also govern cached and shared outputs. When using GTEx data, acknowledge the GTEx Project [2].
|
|
143
|
+
|
|
144
|
+
#### Documentation
|
|
145
|
+
|
|
146
|
+
| Page | Content |
|
|
147
|
+
|------------------------------------|---------------------------------------------------------------------------------------------------------------------|
|
|
148
|
+
| [docs/methods.md](docs/methods.md) | Request identity, gene-level reduction, allele orientation, metrics, bootstrap, statistical assumptions, validation |
|
|
149
|
+
| [docs/api.md](docs/api.md) | Public interface, output schemas, environment variables, caches, provenance, reproducibility |
|
|
150
|
+
|
|
151
|
+
#### Development
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
uv sync --extra model --extra vcf
|
|
155
|
+
uv run pytest
|
|
156
|
+
uv run ruff check . && uv run ruff format --check . && uv run mypy
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
By default, tests run offline using a pinned GTEx Portal response. To run the live test, set `ALPHA_GENOME_API_KEY` and execute `uv run pytest -m live`.
|
|
160
|
+
|
|
161
|
+
#### Licence
|
|
162
|
+
|
|
163
|
+
`ag2kit` is licensed under MIT ([LICENSE](LICENSE)); the `alphagenome` SDK is licensed separately under Apache 2.0. AlphaGenome's terms of use govern API access and outputs.
|
|
164
|
+
|
|
165
|
+
#### References
|
|
166
|
+
|
|
167
|
+
> [!NOTE]
|
|
168
|
+
> For GTEx v10 and v11, cite reference 2 and include the Portal release and access date.
|
|
169
|
+
|
|
170
|
+
1. Avsec, Ž. *et al.* Advancing regulatory variant effect prediction with AlphaGenome. *Nature* **649**, 1206–1218 (2026). doi:[10.1038/s41586-025-10014-0](https://doi.org/10.1038/s41586-025-10014-0)
|
|
171
|
+
2. GTEx Consortium. The GTEx Consortium atlas of genetic regulatory effects across human tissues. *Science* **369**, 1318–1330 (2020). doi:[10.1126/science.aaz1776](https://doi.org/10.1126/science.aaz1776)
|
|
172
|
+
3. Danecek, P. *et al.* Twelve years of SAMtools and BCFtools. *GigaScience* **10**, giab008 (2021). doi:[10.1093/gigascience/giab008](https://doi.org/10.1093/gigascience/giab008)
|
|
173
|
+
4. Google DeepMind. AlphaGenome 2: deciphering how cells read DNA to better understand disease (announcement, 11 November 2026). <https://deepmind.google/blog/alphagenome-2-deciphering-how-cells-read-dna-to-better-understand-disease/>
|
|
174
|
+
5. Hanley, J. A. & McNeil, B. J. The meaning and use of the area under a receiver operating characteristic (ROC) curve. *Radiology* **143**, 29–36 (1982). doi:[10.1148/radiology.143.1.7063747](https://doi.org/10.1148/radiology.143.1.7063747)
|
|
175
|
+
6. Davison, A. C. & Hinkley, D. V. *Bootstrap Methods and their Application* (Cambridge University Press, 1997). doi:[10.1017/CBO9780511802843](https://doi.org/10.1017/CBO9780511802843)
|
|
176
|
+
7. Field, C. A. & Welsh, A. H. Bootstrapping clustered data. *J. R. Stat. Soc. B* **69**, 369–390 (2007). doi:[10.1111/j.1467-9868.2007.00593.x](https://doi.org/10.1111/j.1467-9868.2007.00593.x)
|
|
177
|
+
8. McNemar, Q. Note on the sampling error of the difference between correlated proportions or percentages. *Psychometrika* **12**, 153–157 (1947). doi:[10.1007/BF02295996](https://doi.org/10.1007/BF02295996)
|
|
178
|
+
9. Mohammadi, P., Castel, S. E., Brown, A. A. & Lappalainen, T. Quantifying the regulatory effect size of cis-acting genetic variation using allelic fold change. *Genome Res.* **27**, 1872–1884 (2017). doi:[10.1101/gr.216747.116](https://doi.org/10.1101/gr.216747.116)
|