From ecf5c8bc7c00c3e5bb280b73d9cdf9aca7452956 Mon Sep 17 00:00:00 2001 From: Bryan Briney Date: Fri, 20 Nov 2026 11:36:16 -0800 Subject: [PATCH 1/4] partis 1.0.0 annotates, partitions with pairing, computes selection metrics, and simulates with per-base mutation along TreeSim trees, offline Co-Authored-By: Claude Opus 5.5 --- tools/partis/Containerfile | 27 +++++++++++ tools/partis/SKILL.md | 81 ++++++++++++++++++++++++++++++++ tools/partis/test/run.sh | 96 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 204 insertions(+) create mode 100644 tools/partis/Containerfile create mode 100644 tools/partis/SKILL.md create mode 100644 tools/partis/test/run.sh diff --git a/tools/partis/Containerfile b/tools/partis/Containerfile new file mode 100644 index 0000000..aaa82b2 --- /dev/null +++ b/tools/partis/Containerfile @@ -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 diff --git a/tools/partis/SKILL.md b/tools/partis/SKILL.md new file mode 100644 index 0000000..d91e786 --- /dev/null +++ b/tools/partis/SKILL.md @@ -0,0 +1,81 @@ +--- +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 --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 40 simulated paired families (about 430 sequences) in about 30 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. +- 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 and asks for at least 85% coverage 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 40 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 went from 0.815 alone to 1.000 paired in one run); then computes selection metrics (six 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`. diff --git a/tools/partis/test/run.sh b/tools/partis/test/run.sh new file mode 100644 index 0000000..7635811 --- /dev/null +++ b/tools/partis/test/run.sh @@ -0,0 +1,96 @@ +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. A few light-chain sequences fail +# annotation in some runs (5 of 56 IGL once), so at least 85% of each chain must be partitioned. +run psimu partis simulate --paired-loci --rearrange-from-scratch --paired-outdir "$w/psimu" --n-sim-events 40 --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 From d3caf07645defea136030d7a2edfc9260725a862 Mon Sep 17 00:00:00 2001 From: Bryan Briney Date: Fri, 20 Nov 2026 11:55:43 -0800 Subject: [PATCH 2/4] partis 1.0.0's test simulates 80 paired families, enough light-chain sequences for stable parameter inference Co-Authored-By: Claude Opus 5.5 --- tools/partis/SKILL.md | 7 ++++--- tools/partis/test/run.sh | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/tools/partis/SKILL.md b/tools/partis/SKILL.md index d91e786..98ae431 100644 --- a/tools/partis/SKILL.md +++ b/tools/partis/SKILL.md @@ -52,7 +52,7 @@ Each event is a clonal family: a rearrangement, a tree from TreeSim, and mutatio ## 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 40 simulated paired families (about 430 sequences) in about 30 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. +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 90 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 @@ -73,9 +73,10 @@ srun --cpus-per-task=8 --mem=16G --container-image=ghcr.io#brineylab/toolshed/pa ## 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. -- 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 and asks for at least 85% coverage instead. The partition is not deterministic run to run. +- 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 40 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 went from 0.815 alone to 1.000 paired in one run); then computes selection metrics (six 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. +- 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 went from 0.815 alone to 1.000 paired in one run); then computes selection metrics (six 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`. diff --git a/tools/partis/test/run.sh b/tools/partis/test/run.sh index 7635811..42598c5 100644 --- a/tools/partis/test/run.sh +++ b/tools/partis/test/run.sh @@ -65,9 +65,10 @@ run simu2 partis simulate --parameter-dir "$w/params" --outfname "$w/simu2.yaml" # 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. A few light-chain sequences fail -# annotation in some runs (5 of 56 IGL once), so at least 85% of each chain must be partitioned. -run psimu partis simulate --paired-loci --rearrange-from-scratch --paired-outdir "$w/psimu" --n-sim-events 40 --seed 3 --n-procs 2 +# 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")" From 624769f759fbb80d2bae55c381d47ee8ef206ba9 Mon Sep 17 00:00:00 2001 From: Bryan Briney Date: Fri, 20 Nov 2026 11:59:27 -0800 Subject: [PATCH 3/4] partis 1.0.0's skill gives the test's measured run time and selection-metric family count Co-Authored-By: Claude Opus 5.5 --- tools/partis/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/partis/SKILL.md b/tools/partis/SKILL.md index 98ae431..01eb5c5 100644 --- a/tools/partis/SKILL.md +++ b/tools/partis/SKILL.md @@ -52,7 +52,7 @@ Each event is a clonal family: a rearrangement, a tree from TreeSim, and mutatio ## 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 90 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. +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 @@ -78,5 +78,5 @@ srun --cpus-per-task=8 --mem=16G --container-image=ghcr.io#brineylab/toolshed/pa - `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 went from 0.815 alone to 1.000 paired in one run); then computes selection metrics (six 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. +- 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`. From 4e100a500d52b8e33f19c663b109c822252b443d Mon Sep 17 00:00:00 2001 From: Bryan Briney Date: Fri, 20 Nov 2026 12:01:16 -0800 Subject: [PATCH 4/4] partis 1.0.0's record: the test passed on a laptop under podman with no network Co-Authored-By: Claude Opus 5.5 --- results/partis/1.0.0.txt | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 results/partis/1.0.0.txt diff --git a/results/partis/1.0.0.txt b/results/partis/1.0.0.txt new file mode 100644 index 0000000..0f66dc2 --- /dev/null +++ b/results/partis/1.0.0.txt @@ -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