Skip to content

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:

uvx uv@0.12.17 run marimo edit examples/tutorials/01_score_with_cherimoya.py -- --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