diff --git a/results/igor/1.0.0.txt b/results/igor/1.0.0.txt new file mode 100644 index 0000000..f6b63de --- /dev/null +++ b/results/igor/1.0.0.txt @@ -0,0 +1,26 @@ +--- +tool: igor +version: 1.0.0 +image: ghcr.io/brineylab/toolshed/igor@sha256:002fd2a650a21b0f81544d637826aa80b1049bc97fe60743743205fbde01370a +digest: sha256:002fd2a650a21b0f81544d637826aa80b1049bc97fe60743743205fbde01370a +runner: podman +host: strix +started: 2026-11-20T18:34:22Z +exit: 0 +--- +Trying to pull ghcr.io/brineylab/toolshed/igor@sha256:002fd2a650a21b0f81544d637826aa80b1049bc97fe60743743205fbde01370a... +Getting image source signatures +Copying blob sha256:c6dd1fd28f55813d9978b46322694c2a901a8001d56698abb7d1f9829c851077 +Copying blob sha256:5c333010138ab1f80002e8f66a0d080fc5a6222033539a01b4c7e81d831ab123 +Copying blob sha256:830ad448e08faf93c7b4ff58048c36ba66d0f061c4aac1007553d8e836ee50db +Copying blob sha256:265e9b98029e3a77ce7d17f188a3cc85eb57001997d21fb88e51de516f05122a +Copying blob sha256:f2814148962027a25a1de7a9247db7ca2f84bc81f72aaf1a141070a19cfe9d6d +Copying blob sha256:c5b0731ec9e1098b8956baff14655a3d919d82583bd2bc98ce8cba2e36dc1846 +Copying config sha256:9a5b7cf65eb08ab0866ff96fdcd25d7991028dae8b805c855277f00dc025e4d3 +Writing manifest to image destination +node: 67d8fa6a3fa5 +gpu: none +trb: 200 of 200 with Pgen > 0, 200 of 200 with the generating V gene as best scenario +igh: 40 of 40 with Pgen > 0, 40 of 40 with the generating V gene as best scenario +inferred a TRB model, scored the 200 reads under it, and generated 10 sequences from it +ok diff --git a/tools/igor/Containerfile b/tools/igor/Containerfile new file mode 100644 index 0000000..75d1c2b --- /dev/null +++ b/tools/igor/Containerfile @@ -0,0 +1,20 @@ +# IGoR 1.4.0, the last release (2020), built from its release archive with igor-1.4.0.patch: Matrix::operator= gains its +# missing `return *this` (upstream issue #62, PR #67), whose absence crashes every optimized build from GCC 8 on during +# generation and inference; three FASTA readers stop indexing past an empty line; and two fixes let it compile at all. +FROM docker.io/library/debian:bookworm-20261104-slim@sha256:c67e92c8099ba22853ab4cfda7cfb494d253d6012ca82dee98ba8976772af018 AS build +RUN apt-get update && apt-get install -y --no-install-recommends build-essential ca-certificates curl unzip patch +COPY igor-1.4.0.patch /src/ +RUN curl -fsSL -o /src/igor_1-4-0.zip https://github.com/qmarcou/IGoR/releases/download/1.4.0/igor_1-4-0.zip \ + && echo "63f0620fc853abb937c51a2d55c368bde2feb9c8ac3b8ca8c1ba839baf7e8733 /src/igor_1-4-0.zip" | sha256sum -c - \ + && cd /src && unzip -q igor_1-4-0.zip && cd igor_1-4-0 && patch -p1 < ../igor-1.4.0.patch \ + && ./configure --prefix=/usr/local CXXFLAGS="-O2 -Werror=return-type" \ + && make -j"$(nproc)" && make install + +FROM docker.io/library/debian:bookworm-20261104-slim@sha256:c67e92c8099ba22853ab4cfda7cfb494d253d6012ca82dee98ba8976772af018 +RUN apt-get update && apt-get install -y --no-install-recommends libgomp1 && rm -rf /var/lib/apt/lists/* +COPY --from=build /usr/local/bin/igor /usr/local/bin/igor +# the models (human TRA, TRB, IGH naive; mouse TRB) are IGoR's weights, at the path the binary was compiled to read +COPY --from=build /usr/local/share/igor /usr/local/share/igor +# GPLv3: the license, and the exact source and patch the binary was built from +COPY --from=build /src/igor_1-4-0/COPYING /src/igor_1-4-0.zip /src/igor-1.4.0.patch /usr/local/share/igor/source/ +COPY test /toolshed/test diff --git a/tools/igor/SKILL.md b/tools/igor/SKILL.md new file mode 100644 index 0000000..28e82de --- /dev/null +++ b/tools/igor/SKILL.md @@ -0,0 +1,77 @@ +--- +name: igor +description: "IGoR, the V(D)J recombination model: aligns TCR and BCR reads to germline, infers a recombination model from them, scores each sequence's generation probability (Pgen) and most likely recombination scenarios, and generates synthetic repertoires. Reach for it for Pgen, recombination statistics, or sequences drawn from a fitted or published model." +metadata: + version: 1.0.0 +--- +# igor + +Image: `ghcr.io/brineylab/toolshed/igor:1.0.0` + +IGoR 1.4.0 (Marcou, Mora & Walczak, *Nat. Commun.* 2018; github.com/qmarcou/IGoR), its last release, built from the release archive on Debian bookworm with a small patch (see Gotchas), run through its own `igor` program. Its published models are in the image at `/usr/local/share/igor/models`: human `alpha` (TRA), `beta` (TRB), `heavy_naive` (IGH), `kappa` (IGK) and `lambda` (IGL), and mouse `beta`. It needs no network. CPU only. + +## Commands + +Every command names a working directory (`-set_wd`), which must exist, and a batch name (`-batch`) that ties the steps of one dataset together; outputs land in subdirectories of the working directory. `-species` and `-chain` select a built-in model; `-set_custom_model ` uses any other, such as one you inferred. `-threads` sets the thread count (default: OpenMP's, every core the process may use, or `OMP_NUM_THREADS`). + +Align reads to the model's germline genes, then score them: Pgen per sequence and each sequence's most likely scenarios. + +```bash +igor -set_wd /work/igor -threads 8 -batch rep1 -species human -chain beta -read_seqs /work/reads.fasta -align --all +igor -set_wd /work/igor -threads 8 -batch rep1 -species human -chain beta -evaluate -output --Pgen --scenarios 10 +``` + +Infer a recombination model from aligned reads (out-of-frame, unselected sequences are what IGoR's published models were learned from), then use it: + +```bash +igor -set_wd /work/igor -threads 8 -batch rep1 -species human -chain beta -infer --N_iter 10 +igor -set_wd /work/igor -threads 8 -batch rep1 -set_custom_model /work/igor/rep1_inference/final_parms.txt /work/igor/rep1_inference/final_marginals.txt -evaluate -output --Pgen +``` + +Generate synthetic sequences, with their CDR3s, from a model: + +```bash +igor -set_wd /work/igor -threads 8 -batch sim -species human -chain heavy_naive -generate 10000 --noerr --CDR3 --seed 42 +``` + +`--noerr` leaves out the model's sequencing-error (or, for IGH, hypermutation) process. The align step takes per-gene options (`--V`, `--D`, `--J`, each with `---thresh` and `---offset_bounds`); the full command reference is IGoR's documentation, qmarcou.github.io/IGoR. + +## Inputs and outputs + +- **In:** `-read_seqs` takes FASTA, a `.csv` of `seq_index;sequence` rows with a header, or a `.txt` with one sequence per line. Reads should be nucleotide sequences in the model's orientation, covering the CDR3 and enough V and J to align. +- **Out**, under the working directory: + - `aligns/_{V,D,J}_alignments.csv` and `aligns/_indexed_sequences.csv` (each read's index), from `-align`. + - `_output/Pgen_counts.csv` (`seq_index;Pgen_estimate`) and `_output/best_scenarios_counts.csv` (one row per scenario: `seq_index;scenario_rank;scenario_proba_cond_seq` then each event's realization as an index into the model, such as the V gene's position in `genomicVs.fasta`), from `-evaluate -output`. + - `_inference/final_parms.txt` and `final_marginals.txt` (the inferred model), with per-iteration files and `likelihoods.out`, from `-infer`. + - `_generated/generated_seqs_noerr.csv` (`seq_index;nt_sequence`), `generated_realizations_noerr.csv` (the scenario behind each), and with `--CDR3` `generated_seqs_noerr_CDR3_info.csv` (`seq_index,nt_CDR3,anchors_found,is_inframe`), from `-generate`. Without `--noerr` the names end in `_werr`. + +## Compute + +CPU only; memory grows with the number of reads and with the IGH model, which is much larger than the TCR ones. On a laptop at two threads, aligning 200 TRB sequences takes about 30 s, evaluating them a few seconds, and evaluating 40 IGH sequences about 10 s; generation is near instant. Alignment and evaluation scale linearly in reads and with threads: give a large repertoire a node's cores. + +## Running it + +On a laptop, from the directory holding `reads.fasta`: + +```bash +mkdir -p igor +podman run --rm -v "$PWD":/work ghcr.io/brineylab/toolshed/igor:1.0.0 \ + igor -set_wd /work/igor -threads 8 -batch rep1 -species human -chain beta -read_seqs /work/reads.fasta -align --all +``` + +On a Slurm cluster with pyxis: + +```bash +mkdir -p igor +srun --cpus-per-task=8 --container-image=ghcr.io#brineylab/toolshed/igor:1.0.0 --container-mounts="$PWD":/work \ + igor -set_wd /work/igor -threads 8 -batch rep1 -species human -chain beta -read_seqs /work/reads.fasta -align --all +``` + +## Gotchas + +- IGoR 1.4.0 as released crashes when built by any GCC from 8 on: `Matrix::operator=` falls off its end without `return *this` (upstream issue #62, PR #67, never merged), which optimized builds turn into a segfault during generation and inference. This image's `igor-1.4.0.patch` adds that return and one more in `Deletion::has_effect_on`, which the build now treats as an error (`-Werror=return-type`); stops three FASTA and sequence readers from reading before the start of an empty line; and makes two changes it needs to compile (`#include `, and `comp_nt_int` no longer `inline`). It changes no model or algorithm. +- `heavy_memory` is accepted and is the same model as `heavy_naive` in 1.4.0: its hypermutation branch is an empty TODO. The hypermutation models for IGH are in `/usr/local/share/igor/models/human/bcr_heavy/supplementary_models`, for use through `-set_custom_model`. +- The working directory must exist before the first command. If it does not, IGoR prints a `mkdir` error, writes nothing, and still exits 0: check that the output files exist, not only the exit code. A rerun with the same batch name overwrites its outputs. +- `-h` opens IGoR's man page, which the image does not carry; use the documentation. +- The test generates 200 TRB and 40 IGH sequences with seed 7, reads them back as FASTA with a blank line among them, aligns and evaluates them on two threads (IGoR's OpenMP path), and checks every sequence has Pgen > 0 under the model that generated it and that its best scenario names the V gene it was generated from; it then infers a TRB model in two iterations, evaluates the reads and generates under it, and generates from every built-in model. It does not run a repertoire-scale inference. +- IGoR and its models are GPLv3. The license, the release archive the binary was built from, and the patch are in the image at `/usr/local/share/igor/source`. A published model's provenance is its `model.info`, beside it under `/usr/local/share/igor/models`. diff --git a/tools/igor/igor-1.4.0.patch b/tools/igor/igor-1.4.0.patch new file mode 100644 index 0000000..1f28ffd --- /dev/null +++ b/tools/igor/igor-1.4.0.patch @@ -0,0 +1,74 @@ +diff -ru a/igor_src/Aligner.cpp b/igor_src/Aligner.cpp +--- a/igor_src/Aligner.cpp ++++ b/igor_src/Aligner.cpp +@@ -85,7 +85,7 @@ + vector> sequence_vect; + + while (getline(infile,temp_str)){ +- if(temp_str[temp_str.size()-1] == '\r'){ ++ if(!temp_str.empty() and temp_str.back() == '\r'){ + temp_str.erase(temp_str.size()-1); + } + if(temp_str[0] == '>'){ +@@ -128,7 +128,7 @@ + vector> sequence_vect; + + while (getline(infile,temp_str)){ +- if(temp_str[temp_str.size()-1] == '\r'){ ++ if(!temp_str.empty() and temp_str.back() == '\r'){ + temp_str.erase(temp_str.size()-1); + } + if(temp_str[0] == '>'){ +@@ -198,7 +198,7 @@ + string seq_str; + + while(getline(infile,seq_str)){ +- if(seq_str[seq_str.size()-1] == '\r'){ ++ if(!seq_str.empty() and seq_str.back() == '\r'){ + seq_str.erase(seq_str.size()-1); + } + if(!seq_str.empty()){ +@@ -895,7 +895,7 @@ + /** + * This function compares nucleotides and output a boolean if they do not necessarily imply an error (ambiguous nucleotides are thus treated in a loose sense). + */ +-bool inline comp_nt_int(const int& nt_1 , const int& nt_2){ ++bool comp_nt_int(const int& nt_1 , const int& nt_2){ + if(nt_1 != nt_2){ + if( (nt_1<4) & (nt_2<4)){ + return false; +diff -ru a/igor_src/CDR3SeqData.h b/igor_src/CDR3SeqData.h +--- a/igor_src/CDR3SeqData.h ++++ b/igor_src/CDR3SeqData.h +@@ -9,6 +9,8 @@ + #ifndef CDR3SEQDATA_H + #define CDR3SEQDATA_H + ++#include ++ + class CDR3SeqData { + public: + CDR3SeqData(); +diff -ru a/igor_src/Deletion.cpp b/igor_src/Deletion.cpp +--- a/igor_src/Deletion.cpp ++++ b/igor_src/Deletion.cpp +@@ -1701,7 +1701,7 @@ + return false; + break; + } +- ++ return false; + } + + void Deletion::iterate_initialize_Len_proba(Seq_type considered_junction , std::map& length_best_proba_map , std::queue>& model_queue , double& scenario_proba , const Marginal_array_p& model_parameters_point , Index_map& base_index_map , Seq_type_str_p_map& constructed_sequences , int& seq_len/*=0*/ ) const{ +diff -ru a/igor_src/Utils.h b/igor_src/Utils.h +--- a/igor_src/Utils.h ++++ b/igor_src/Utils.h +@@ -139,6 +139,7 @@ + for(int i = 0 ; i != rows*cols ; i++){ + this->array_p[i] = other.array_p[i]; + } ++ return *this; + } + + T& operator()(const int& i ,const int& j ){ diff --git a/tools/igor/test/run.sh b/tools/igor/test/run.sh new file mode 100644 index 0000000..bccbb1d --- /dev/null +++ b/tools/igor/test/run.sh @@ -0,0 +1,42 @@ +set -euo pipefail +w=$(mktemp -d) +igor_() { igor -set_wd "$w" -threads 2 "$@" > "$w/log" 2>&1 || { tail -30 "$w/log"; exit 1; }; } + +# Generate, read back as FASTA (with a blank line, which 1.4.0 read past), align, and score against the same model. +# With seed 7, every sequence a model generates has Pgen > 0 under it, and its best scenario names the V gene it was +# generated from: 200 of 200 TRB, 40 of 40 IGH. Two threads take IGoR's OpenMP path. +check() { # batch chain n + local b=$1 c=$2 n=$3 + igor_ -batch "$b" -species human -chain "$c" -generate "$n" --noerr --CDR3 --seed 7 + awk -F';' 'FNR > 1 { print ">" $1; print $2; if (FNR == 3) print "" }' "$w/${b}_generated/generated_seqs_noerr.csv" > "$w/$b.fasta" + igor_ -batch "$b" -species human -chain "$c" -read_seqs "$w/$b.fasta" -align --all + igor_ -batch "$b" -species human -chain "$c" -evaluate -output --Pgen --scenarios 1 + got=$(awk -F';' 'FNR == 1 { next } + FILENAME ~ /realizations/ { v[$1] = $2; next } + FILENAME ~ /Pgen/ { if ($2 + 0 > 0) p++; next } + v[$1] == $4 { s++ } + END { print p + 0, s + 0 }' \ + "$w/${b}_generated/generated_realizations_noerr.csv" "$w/${b}_output/Pgen_counts.csv" "$w/${b}_output/best_scenarios_counts.csv") + read -r p v <<< "$got" + echo "$b: $p of $n with Pgen > 0, $v of $n with the generating V gene as best scenario" + [[ $p -eq $n && $v -eq $n ]] + [[ $(awk -F, 'NR > 1' "$w/${b}_generated/generated_seqs_noerr_CDR3_info.csv" | wc -l) -eq $n ]] +} +check trb beta 200 +check igh heavy_naive 40 + +# Infer a TRB model from those reads, then generate from it. +igor_ -batch trb -species human -chain beta -infer --N_iter 2 +m="$w/trb_inference" +[[ -s "$m/final_parms.txt" && -s "$m/final_marginals.txt" ]] +igor_ -batch trb -set_custom_model "$m/final_parms.txt" "$m/final_marginals.txt" -evaluate -output --Pgen +[[ $(awk -F';' 'NR > 1 && $2 + 0 > 0' "$w/trb_output/Pgen_counts.csv" | wc -l) -eq 200 ]] +igor_ -batch fromtrb -set_custom_model "$m/final_parms.txt" "$m/final_marginals.txt" -generate 10 --noerr --seed 7 +[[ $(awk 'NR > 1' "$w/fromtrb_generated/generated_seqs_noerr.csv" | wc -l) -eq 10 ]] +echo "inferred a TRB model, scored the 200 reads under it, and generated 10 sequences from it" + +# Every chain the image ships a model for generates. +for c in alpha kappa lambda heavy_memory; do igor_ -batch "$c" -species human -chain "$c" -generate 5 --seed 7; done +igor_ -batch mouse -species mouse -chain beta -generate 5 --seed 7 +[[ -s /usr/local/share/igor/source/COPYING ]] +echo ok