Tutorials and examples¶
Five marimo notebooks build one analysis of five GRCh38 variants, from published evidence to model scores to a prioritization rule of your own. They read real variants, genomes and datasets, and every score comes from running the model. Each notebook opens here as a page with the outputs of one run, so you can read it before you install anything.
Choose where to start¶
The notebooks share one cohort, the five Open Targets variants near SORT1, GCKR, TCF7L2 and APOE, and one work directory. Tutorial 0 stands alone. Tutorials 1, 3 and 4 run in that order. Tutorial 2 is optional: when it has stored AlphaGenome's scores, Tutorials 3 and 4 add its columns.
| Tutorial | What it teaches | Requirements | Open |
|---|---|---|---|
| 0 · Look up what is known about five variants | Write a run spec that names gnomAD, ClinVar and phyloP, run it, and read the export and why a variant is prioritized | Python and network access. Reads a few MB of the published datasets in place. No Docker, GPU, API key or genome | With outputs · Source |
| 1 · Score variants locally with Cherimoya | Prepare a model's resources, find the variants that need scoring, inspect the work Altar will submit, run it in Docker and store the scores | Docker, and an NVIDIA GPU or the CPU. Fetches hg38 from Altar's genome registry (984 MB) and downloads five checkpoints of 2.5 MB each (CC BY 4.0), and pulls a 3.4 GB image | With outputs · Source |
| 2 · Add hosted predictions from AlphaGenome | Give a hosted model a credential, call it once per variant, and read its per-track table beside Cherimoya | An AlphaGenome API key for Steps 7 to 9, free for non-commercial research. Each variant is one call against your quota. Without a key, it stops at Step 6. No Docker, GPU or download | With outputs · Source |
| 3 · Put model scores beside evidence | Assemble stored scores with gnomAD, ClinVar, phyloP and Open Targets E2G, tell whether a model or a source flagged each variant, and get the same table from a run spec | Tutorial 1's work directory, network access and Docker; no task runs. The SpliceAI step needs a copy you build from Illumina's files, for academic and not-for-profit use only, and is skipped without one | With outputs · Source |
| 4 · Write your own prioritization rule | Write a model rule and an evidence rule, see how a missing value is treated, render the rule as SQL, and save it as a policy file | Tutorial 3's export. Nothing is downloaded, scored or looked up | With outputs · Source |
Each page shows one run of the series in an empty work directory. Tutorial 2's page ran without an API key, so it stops at Step 6. Tutorial 3's page had no SpliceAI copy, so it skips that step.
The notebook README lists every input, where it comes from and its terms of use. Check that your use is allowed by each one.
Run the notebooks¶
The notebooks run from a source checkout, with Python 3.12 or later:
git clone https://github.com/kundajelab/altar.git
cd altar
uvx uv@0.12.17 sync --all-packages --group tutorials
uvx uv@0.12.17 run marimo edit examples/tutorials/00_look_up_evidence.py
Every notebook reads and writes one work directory, ~/.cache/altar/tutorials/series by default, laid out as
altar run lays out the directory it starts in: the cache, .altar/, holds the genome Tutorial 1 fetches and the
stored scores, and the run directory, altar-tutorials/, holds Tutorial 3's export. Tutorial 1 records what it scored
in series.json there, and the later notebooks read it. To use another directory, change it in each notebook's
series settings, or start every notebook with -- --work-dir DIR. The Cherimoya checkpoints are cached under
~/.cache/altar, and -- --download-cache DIR moves them.
Tutorial 1 runs its model on an NVIDIA GPU by default. On a machine whose GPUs others use, list the free ones in
its Step 6. On a machine without one, choose the CPU in Step 6, or start it with --cpu:
The five tutorial variants took about a minute on the CPU of a 64-core server. A large cohort is much slower than on a GPU.
A notebook runs on its defaults up to each step that downloads, scores or calls an API, and waits there for you to
press that step's button. A second run of a scoring notebook reuses the scores already in the store, and scores only
the variants the store lacks. To open a notebook as a read-only app, use marimo run in place of marimo edit.
Smaller example programs¶
Each directory under examples/ is a short program with
its own README. Each shows one piece of Altar, from the command line or from Python:
| Directory | Shows |
|---|---|
scoring/ |
LegNet on the CPU with altar run; ChromBPNet and Cherimoya scoring on local Docker or Modal; hosted AlphaGenome scoring from Python |
interpretation/ |
altar interpret with ChromBPNet on the CPU: contribution scores and motif hits for three variants |
analysis/ |
Model scores, evidence and variant–gene links for five variants in one result, including variants with no evidence |
annotation_sources/ |
AlphaMissense, SpliceAI and GPN-Star sources read from Parquet and from SQLite, with the same results |
variant_gene_links/ |
ENCODE-rE2G, scE2G and Open Targets E2G links in an in-memory store and in SQLite, with the same results |
Some of these programs use small fixtures or placeholder tasks to check the interface. Their values are not model predictions. Each README says which programs run a real model.
Next¶
- Give a run its variants: run Altar on your own VCF or TSV.
- The catalog lists every model and annotation source, with what each needs.
- From variants to evidence explains what the scores, annotations and links mean.