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
26 changes: 26 additions & 0 deletions results/igor/1.0.0.txt
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions tools/igor/Containerfile
Original file line number Diff line number Diff line change
@@ -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
77 changes: 77 additions & 0 deletions tools/igor/SKILL.md
Original file line number Diff line number Diff line change
@@ -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 <parms> <marginals>` 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/<batch>_{V,D,J}_alignments.csv` and `aligns/<batch>_indexed_sequences.csv` (each read's index), from `-align`.
- `<batch>_output/Pgen_counts.csv` (`seq_index;Pgen_estimate`) and `<batch>_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`.
- `<batch>_inference/final_parms.txt` and `final_marginals.txt` (the inferred model), with per-iteration files and `likelihoods.out`, from `-infer`.
- `<batch>_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 <string>`, 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`.
74 changes: 74 additions & 0 deletions tools/igor/igor-1.4.0.patch
Original file line number Diff line number Diff line change
@@ -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<pair<const int, const std::string>> 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<pair<string,std::string>> 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 <string>
+
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<int,double>& length_best_proba_map , std::queue<std::shared_ptr<Rec_Event>>& 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 ){
42 changes: 42 additions & 0 deletions tools/igor/test/run.sh
Original file line number Diff line number Diff line change
@@ -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