Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions results/partis/1.0.0.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
tool: partis
version: 1.0.0
image: ghcr.io/brineylab/toolshed/partis@sha256:4bb6c0be2d10fb0fd25d978fe213ae4f2c399fabefcaaf162fff3a143c53dea4
digest: sha256:4bb6c0be2d10fb0fd25d978fe213ae4f2c399fabefcaaf162fff3a143c53dea4
runner: podman
host: strix
started: 2026-11-20T19:59:32Z
exit: 0
---
node: c0f8586adb03
gpu: none
annotate: 86 sequences, 82 with the true V gene, 82 mutated in V
partition: 86 IGH sequences, purity 1.000, completeness 0.965
paired partition igh: 486 of 494 sequences, purity 1.000 (alone 1.000), completeness 0.981
paired partition igk: 390 of 390 sequences, purity 0.987 (alone 0.787), completeness 0.982
paired partition igl: 101 of 104 sequences, purity 1.000 (alone 0.808), completeness 0.980
selection metrics for 17 families; parse-output wrote 486 FASTA and 486 AIRR rows of 486 IGH sequences
ok
27 changes: 27 additions & 0 deletions tools/partis/Containerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# partis v1.0.30 run from its source tree at the tag's commit, as upstream's own image does, so it finds bcrham, ig-sw,
# and the bpp-newlik bppseqgen that its default per-base simulation needs where it expects them. R and its CRAN packages
# come from rocker's image of R 4.5.3, whose CRAN is frozen at a dated snapshot; TreeSim/TreeSimGM generate trees.
FROM docker.io/rocker/r-ver:4.5.3@sha256:f5a72ffeea7ed592b2a5990f87101beef8ef3cae0e4ff7327088e80368f0aef9
RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-venv python3-dev build-essential cmake \
scons git ca-certificates mafft libgsl-dev libyaml-cpp-dev libncurses-dev zlib1g-dev \
libglpk40 libblas-dev liblapack-dev libboost-dev libeigen3-dev libsuitesparse-dev libfftw3-dev \
&& rm -rf /var/lib/apt/lists/*
RUN Rscript -e 'install.packages(c("TreeSim", "TreeSimGM", "geiger", "MASS")); for (p in c("TreeSim", "TreeSimGM", "geiger", "MASS")) library(p, character.only = TRUE)'
# colored_traceback only colors tracebacks, and its curses call kills every partis program under a TERM the image has no
# terminfo for (pyxis passes the caller's in), so an empty module stands in for it
RUN python3 -m venv /opt/venv && /opt/venv/bin/pip install --no-cache-dir biopython==1.88 \
dendropy==5.1.3 fire==0.7.1 matplotlib==3.11.2 numpy==2.5.5 pandas==3.1.1 psutil==7.2.2 pot==0.9.7.post1 \
pysam==0.24.1 PyYAML==6.0.3 scikit-learn==1.9.1 scipy==1.18.1 seaborn==0.13.2 six==1.17.0 \
&& mkdir /opt/venv/lib/python3.12/site-packages/colored_traceback \
&& touch /opt/venv/lib/python3.12/site-packages/colored_traceback/__init__.py /opt/venv/lib/python3.12/site-packages/colored_traceback/always.py
RUN git clone https://github.com/psathyrella/partis.git /opt/partis && cd /opt/partis \
&& git checkout 40ff8e3c9b07309193aa76c29652ca4a2531f101 \
&& git submodule update --init packages/ham packages/ig-sw packages/bpp-newlik/eigen3 packages/bpp-newlik/bpp-core \
packages/bpp-newlik/bpp-seq packages/bpp-newlik/bpp-phyl packages/bpp-newlik/bpp-popgen packages/bpp-newlik/bppsuite \
&& ./bin/build.sh with-simulation \
&& rm -rf .git packages/*/.git packages/bpp-newlik/*/.git packages/bpp-newlik/_build/*/CMakeFiles
# pyxis passes the caller's environment in: run partis's programs under the image's python, isolated, with partis importable
RUN sed -i '1s|.*|#!/opt/venv/bin/python3 -I|' /opt/partis/bin/partis /opt/partis/bin/parse-output.py \
&& echo /opt/partis > /opt/venv/lib/python3.12/site-packages/partis.pth
ENV PATH=/opt/partis/bin:/opt/venv/bin:$PATH PYTHONNOUSERSITE=1
COPY test /toolshed/test
82 changes: 82 additions & 0 deletions tools/partis/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
name: partis
description: "partis, the BCR/TCR repertoire toolkit: annotates sequences (AIRR output), infers germline and repertoire parameters, partitions sequences into clonal families with heavy/light pairing, computes selection metrics, and simulates realistic repertoires with per-base mutation along TreeSim trees. Reach for it to annotate or cluster a repertoire, or to simulate one with a known truth."
metadata:
version: 1.0.0
---
# partis

Image: `ghcr.io/brineylab/toolshed/partis:1.0.0`

partis v1.0.30 (Ralph & Matsen; github.com/psathyrella/partis), run from its source tree at the tag's commit `40ff8e3`, the way upstream's own image runs it: `bcrham` and `ig-sw` compiled in place, and the simulation stack built too, which the pip package leaves out: bpp-newlik's `bppseqgen` (Bio++, built with `bin/build.sh with-simulation`) for the default per-base mutation model, and R 4.5.3 with TreeSim, TreeSimGM, geiger and MASS (from CRAN's snapshot of 2026-04-23) for trees. Its germline sets (human, macaque, mouse strains and more, IG and TR loci, from IMGT and, for macaque, OGRDB) and its pooled mutation tables for simulating from scratch ship in `/opt/partis/data`. It needs no network. CPU only.

## Commands

Annotate sequences, inferring parameters (germline set, deletions, insertions, mutation) from them first; `--airr-output` writes an AIRR TSV beside the YAML:

```bash
partis annotate --infname /work/seqs.fa --parameter-dir /work/params --outfname /work/ann.yaml --airr-output --n-procs 8
```

Partition a single-chain sample into clonal families, or a heavy/light sample using its pairing (from 10x droplet ids in the sequence names, or `paired-uids` in `--input-metafnames`):

```bash
partis partition --infname /work/seqs.fa --parameter-dir /work/params --outfname /work/partition.yaml --n-procs 8
partis partition --paired-loci --infname /work/all-seqs.fa --input-metafnames /work/meta.yaml --paired-outdir /work/ppart --n-procs 8
```

A paired run writes `partition-igh.yaml`, `partition-igk.yaml` and `partition-igl.yaml` (joint partitions) and the per-locus parameters under `--paired-outdir`. A directory laid out that way, such as a paired simulation's, is read with `--paired-indir` in place of `--infname`.

Selection metrics (aa-cdist, lbi, lbr) on a partition, then parse partis output into FASTA, CSV, or AIRR:

```bash
partis get-selection-metrics --paired-loci --paired-outdir /work/ppart --n-procs 8
parse-output.py /work/ppart/partition-igh.yaml /work/igh.fa
parse-output.py /work/ppart/partition-igh.yaml /work/igh.tsv --airr-output
```

Simulate. From scratch, with realistic per-position, per-base mutation from partis's pooled public-data tables; mimicking a sample, from the parameter directory inferred from it; or paired heavy/light:

```bash
partis simulate --rearrange-from-scratch --outfname /work/simu.yaml --n-sim-events 1000 --seed 1 --n-procs 8
partis simulate --parameter-dir /work/params --outfname /work/simu.yaml --n-sim-events 1000 --seed 1 --n-procs 8
partis simulate --paired-loci --rearrange-from-scratch --paired-outdir /work/psimu --n-sim-events 1000 --seed 1 --n-procs 8
```

Each event is a clonal family: a rearrangement, a tree from TreeSim, and mutation along it by `bppseqgen`. `--mutation-multiplier`, `--n-leaf-distribution`, `--n-leaves`, and `--light-chain-fractions` shape it; `--no-per-base-mutation` swaps in the older, ten times faster, per-position-only model. The output YAML carries the truth (`reco_id` per family, the true annotation per sequence); run inference on it with `--is-simu` and partis prints its accuracy, purity and completeness for a partition. `partis <action> --help` lists every option; the documentation is partis's `docs/` on GitHub.

## Inputs and outputs

- **In:** FASTA (or partis YAML, or AIRR TSV with `--airr-input`) of positive-sense sequences of one locus, `--locus igh` by default (`igk`, `igl`, `tra`, `trb`, ...) and `--species human` by default; `--paired-loci` takes all loci mixed.
- **Out:** partis YAML (`--outfname`), holding the germline set, annotations, and for `partition` the clustering path, read in Python with `partis.utils.read_output(fname)` under the image's python (`/opt/venv/bin/python3 -I`, where `partis` imports); AIRR TSV with `--airr-output`; `selection-metrics.yaml` in the paired outdir; parameters (`sw/`, `hmm/`, and for simulations `true/`) under `--parameter-dir`.

## Compute

CPU only; `--n-procs` defaults to every core. Upstream's figures: annotating 10,000 sequences takes about 5 minutes on 8 cores and partitioning them about 25; simulating 10,000 sequences with per-base mutation about 8 minutes on one core, ten times less with `--no-per-base-mutation`. On a laptop at two processes, this tool's test simulates 20 IGH families (86 sequences) in about 5 s and annotates them in 5 s, and partitions 80 simulated paired families (about 990 sequences) in about 50 s; the whole test takes about 70 s. Temporary files go to `--workdir`, by default under `/tmp`; on a cluster running partis's own Slurm parallelism (`--batch-system slurm`), set it to a shared path.

## Running it

On a laptop, from the directory holding `seqs.fa`:

```bash
podman run --rm -v "$PWD":/work ghcr.io/brineylab/toolshed/partis:1.0.0 \
partis annotate --infname /work/seqs.fa --parameter-dir /work/params --outfname /work/ann.yaml --airr-output --n-procs 8
```

On a Slurm cluster with pyxis:

```bash
srun --cpus-per-task=8 --mem=16G --container-image=ghcr.io#brineylab/toolshed/partis:1.0.0 --container-mounts="$PWD":/work \
partis simulate --rearrange-from-scratch --outfname /work/simu.yaml --n-sim-events 1000 --seed 1 --n-procs 8
```

## Gotchas

- Upstream's own CI never exercises the default per-base simulation or TreeSim tree generation (it tests `--no-per-base-mutation --no-tree-gen`); this tool's test is what checks that path. With `--debug 1`, a simulation logs `generating N trees` and, for every family, `using bpp per-base mutation with path /opt/partis/packages/bpp-newlik/_build`; without R or bpp-newlik it fails rather than falling back.
- Parameters are inferred from the sample itself, and a small one gives unstable parameters: with 56 IGL sequences, inference sometimes pruned a J gene that one family needed, the family failed annotation (`removed 11 failed queries`), and its heavy partners were discarded as unpaired, losing 20% of both chains. At about 100 sequences per light chain the test kept at least 97% in every run, so its paired sample is that size. For a small sample, check the counts in the log, or infer parameters on a larger related sample and pass them with `--parameter-dir`.
- With `--is-simu`, a paired partition raises `Exception: missing 0.089 (more than 0.050)` when more than 5% of a light chain's true sequences are missing from its partition (they failed annotation): a deliberate guard in partis's comparison against the truth, not a failed partition. On 40 small simulated families it tripped in about 1 run in 10 (5 of 56 IGL sequences). The test scores partitions itself instead. The partition is not deterministic run to run.
- `colored_traceback`, which every partis program imports only to color tracebacks, kills the program under any `TERM` the image lacks terminfo for, and pyxis passes the caller's `TERM` in; the image replaces it with an empty module, so tracebacks print plain.
- partis's version reads as `unknown`: the image keeps the source tree but not its `.git`. It is v1.0.30, commit `40ff8e3c9b07309193aa76c29652ca4a2531f101`.
- Simulating from scratch reads per-base mutation counts for genes that have none from their nearest relatives and warns that the counts will be wrong where the genes differ; that is partis's documented behavior for `--rearrange-from-scratch`.
- The test runs every command above on two processes (partis's multiprocess path). It simulates 20 IGH families with per-base mutation and TreeSim trees and checks every family went through bpp-newlik; parses them to FASTA, annotates them (the true V gene for at least 90% of the 86 sequences, 82 here, and at least 80% mutated in V) and partitions them (purity at least 0.95, completeness at least 0.75 against the true families); simulates 10 more families from the inferred parameters; simulates 80 paired families and partitions their mixed FASTA with its pairing, requiring per chain at least 85% of sequences partitioned, purity at least 0.95, completeness at least 0.75, and no chain less pure paired than alone (IGK reaches about 0.8 alone and 0.99 to 1.0 paired); then computes selection metrics (16 or 17 families reach the tree-size minimum) and parses the IGH partition to FASTA and AIRR, one row per sequence. It does not run a repertoire-scale partition.
- partis is GPLv3, Bio++ CeCILL, TreeSim and TreeSimGM GPL-2; the full partis source, with its submodules' sources and licenses, is in the image at `/opt/partis`.
97 changes: 97 additions & 0 deletions tools/partis/test/run.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
set -euo pipefail
w=$(mktemp -d)
cd "$w"
run() { local n=$1; shift; "$@" > "$w/$n.log" 2>&1 || { sed 's/\x1b\[[0-9;]*m//g' "$w/$n.log" | tail -40; exit 1; }; sed -i 's/\x1b\[[0-9;]*m//g' "$w/$n.log"; }
py() { /opt/venv/bin/python3 -I - "$@"; }

# Purity and completeness of an inferred partition against a simulation's true families: the share of sequences in
# the dominant true family of their inferred cluster, and in the dominant inferred cluster of their true family.
cat > "$w/score.py" <<'PY'
import sys
from collections import Counter
from partis import utils
def score(inferred, truth):
fam = {u: i for i, a in enumerate(utils.read_output(truth)[1]) for u in a["unique_ids"]}
clusters = [[u for u in c if u in fam] for c in utils.read_output(inferred)[2].best()]
n = sum(len(c) for c in clusters)
purity = sum(Counter(fam[u] for u in c).most_common(1)[0][1] for c in clusters if c) / n
where = {u: i for i, c in enumerate(clusters) for u in c}
by_fam = {}
for u in where:
by_fam.setdefault(fam[u], []).append(where[u])
completeness = sum(Counter(v).most_common(1)[0][1] for v in by_fam.values()) / n
return n, purity, completeness
PY
score() { py "$w" "$@" <<'PY'
import sys; sys.path.insert(0, sys.argv[1]); from score import score
n, p, c = score(*sys.argv[2:])
print(f"{n} {p:.3f} {c:.3f}")
PY
}

# Simulate IGH from scratch with the default per-base mutation model: trees from TreeSim in R, mutation along them by
# bpp-newlik's bppseqgen. partis falls back on nothing here: without R or bpp-newlik it fails.
run simu partis simulate --rearrange-from-scratch --outfname "$w/simu.yaml" --n-sim-events 20 --seed 1 --n-procs 2 --debug 1
[[ $(awk '/generating [0-9]+ trees/ { n += $2 } END { print n }' "$w/simu.log") -eq 20 ]] # one batch per process
[[ $(grep -c 'using bpp per-base mutation with path /opt/partis/packages/bpp-newlik/_build' "$w/simu.log") -eq 20 ]]

# Parse it to FASTA, cache parameters and annotate, writing AIRR; check against the truth the simulation carries.
run simufa parse-output.py "$w/simu.yaml" "$w/seqs.fa"
run annotate partis annotate --infname "$w/seqs.fa" --parameter-dir "$w/params" --outfname "$w/ann.yaml" --airr-output --n-procs 2
[[ -d "$w/params/hmm" && -s "$w/ann.tsv" ]]
py "$w" <<'PY'
import csv, sys
from partis import utils
w = sys.argv[1]
_, simu, _ = utils.read_output(f"{w}/simu.yaml")
true_v = {u: a["v_gene"].split("*")[0] for a in simu for u in a["unique_ids"]}
rows = list(csv.DictReader(open(f"{w}/ann.tsv"), delimiter="\t"))
same = sum(r["v_call"].split("*")[0] == true_v[r["sequence_id"]] for r in rows)
mutated = sum(float(r["v_identity"]) < 1 for r in rows)
print(f"annotate: {len(rows)} sequences, {same} with the true V gene, {mutated} mutated in V")
assert len(rows) == len(true_v), (len(rows), len(true_v))
assert same >= 0.9 * len(rows) and mutated >= 0.8 * len(rows)
PY

# Partition them into clonal families, single chain.
run partition partis partition --infname "$w/seqs.fa" --parameter-dir "$w/params" --outfname "$w/partition.yaml" --n-procs 2
read -r n p c <<< "$(score "$w/partition.yaml" "$w/simu.yaml")"
echo "partition: $n IGH sequences, purity $p, completeness $c"
awk -v p="$p" -v c="$c" 'BEGIN { exit !(p >= 0.95 && c >= 0.75) }'

# Simulate again from the parameters inferred from that sample, mimicking it.
run simu2 partis simulate --parameter-dir "$w/params" --outfname "$w/simu2.yaml" --n-sim-events 10 --seed 2 --n-procs 2 --debug 1
[[ $(grep -c 'using bpp per-base mutation' "$w/simu2.log") -eq 10 ]]

# Paired heavy/light: simulate, partition from the mixed FASTA and its pairing, and score each chain against the truth.
# partition is not deterministic, and families of a few sequences make completeness coarse, so the bar is purity, and
# that pairing never leaves a chain less pure than single-chain partitioning does. 80 families give IGL about 100
# sequences: at 40 (56 IGL), parameter inference sometimes pruned a J gene one family needed, which then failed
# annotation and took its heavy partners with it (45 of 56 IGL kept). Here at least 85% of each chain must be kept.
run psimu partis simulate --paired-loci --rearrange-from-scratch --paired-outdir "$w/psimu" --n-sim-events 80 --seed 3 --n-procs 2
run ppartition partis partition --paired-loci --infname "$w/psimu/all-seqs.fa" --input-metafnames "$w/psimu/meta.yaml" --paired-outdir "$w/ppart" --n-procs 2
for l in igh igk igl; do
read -r n p c <<< "$(score "$w/ppart/partition-$l.yaml" "$w/psimu/$l.yaml")"
read -r _ ps _ <<< "$(score "$w/ppart/single-chain/partition-$l.yaml" "$w/psimu/$l.yaml")"
t=$(grep -c "^>.*-$l\$" "$w/psimu/all-seqs.fa")
echo "paired partition $l: $n of $t sequences, purity $p (alone $ps), completeness $c"
awk -v n="$n" -v t="$t" -v p="$p" -v c="$c" -v ps="$ps" 'BEGIN { exit !(n >= 0.85 * t && p >= 0.95 && c >= 0.75 && p >= ps) }'
done

# Selection metrics on the paired partition, and parsing partis output into FASTA and AIRR.
run metrics partis get-selection-metrics --paired-loci --paired-outdir "$w/ppart" --n-procs 2
run fasta parse-output.py "$w/ppart/partition-igh.yaml" "$w/igh.fa"
run airr parse-output.py "$w/ppart/partition-igh.yaml" "$w/igh.tsv" --airr-output
py "$w" <<'PY'
import sys, yaml
from partis import utils
w = sys.argv[1]
n = sum(len(c) for c in utils.read_output(f"{w}/ppart/partition-igh.yaml")[2].best())
metrics = yaml.safe_load(open(f"{w}/ppart/selection-metrics.yaml"))
assert metrics and all("lb" in m for m in metrics), "no selection metrics"
fasta = sum(l.startswith(">") for l in open(f"{w}/igh.fa"))
airr = sum(1 for _ in open(f"{w}/igh.tsv")) - 1
print(f"selection metrics for {len(metrics)} families; parse-output wrote {fasta} FASTA and {airr} AIRR rows of {n} IGH sequences")
assert fasta == airr == n
PY
echo ok