Systematic Analysis of Framework Antibody RSS Immunogenomics for IGHJ Gene Segments
An automated, validated bioinformatics pipeline for species-agnostic discovery and characterization of immunoglobulin heavy-chain joining (IGHJ) gene segments from mammalian genome assemblies. Designed for comparative immunogenomics in non-model organisms.
- Species-agnostic: Works on any mammalian genome assembly without species-specific tuning
- Locus-aware filtering: Single-linkage clustering algorithm distinguishes true IGH locus genes from genome-wide pseudogene noise — the key innovation preventing false-positive inflation
- RSS-23 scoring: Information Content (IC) scoring of recombination signal sequences with enrichment analysis against genomic background
- Biological validation: 10 automated plausibility tests (3 CRITICAL, 4 MAJOR, 3 MINOR) prevent biologically impossible outputs
- Tested on diverse species: Validated across multiple Bovidae species with varying assembly qualities
- 37 unit tests ensuring reproducible, reliable results
Genome FASTA
|
v
[1] makeblastdb ──> BLAST database
|
v
[2] tBLASTn (protein queries, PAM30, evalue=1.0)
|
v
[3] Hit filtering (pident >= 60%, aln_length >= 10 aa)
|
v
[4] Hit merging (deduplicate overlapping hits, 30 bp window)
|
v
[5] LOCUS IDENTIFICATION ← Key innovation
| Single-linkage clustering (50 kb gap threshold)
| Dominant cluster selection
| ±500 kb margin filtering
|
v
[6] RSS-23 scoring (sliding window, both strands)
| IC = 24.69 − (total_mm × 2.21)
|
v
[7] Gene classification
| Functional: stops=0 + WG.G motif + IC >= 18
| ORF: stops=0, fails motif or IC
| Pseudo: stop codons present
|
v
[8] Enrichment analysis (locus RSS IC vs random background)
|
v
[9] Biological validation (10 automated tests)
|
v
Results: candidates.tsv, rss_scores.tsv, summary.tsv, ...
# Clone the repository
git clone https://github.com/jpierrevd/safari-ighj.git
cd safari-ighj
# Install (editable mode recommended for development)
pip install -e .
# Or install directly
pip install .| Tool | Required | Purpose |
|---|---|---|
| BLAST+ | Yes | makeblastdb + tblastn for homology search |
| Python >= 3.10 | Yes | Runtime |
| pandas | Yes | Data handling (auto-installed) |
| MAFFT | Optional | Multiple sequence alignment for phylogeny |
| IQ-TREE | Optional | Maximum-likelihood phylogenetic inference |
safari-ighj \
--genome /path/to/genome.fasta \
--species "Bos taurus" \
--outdir results/bos_taurus \
--validateCreate a TSV file with columns species and genome_path (see example_batch.tsv):
species genome_path
Bos_taurus /path/to/bos_taurus_genome.fna
Ovis_aries /path/to/ovis_aries_genome.fna
Capra_hircus /path/to/capra_hircus_genome.fna
safari-ighj \
--batch example_batch.tsv \
--outdir results/ \
--validatePer species (in results/{species}/):
| File | Description |
|---|---|
tblastn_raw.tsv |
All BLAST hits before filtering (full transparency) |
candidates.tsv |
Locus-filtered IGHJ candidates with coordinates, classification, FR4 motifs |
locus_report.tsv |
Clustering statistics: cluster count, sizes, dominant scaffold |
rss_scores.tsv |
RSS-23 heptamer, nonamer, spacer length, IC per candidate |
classification.tsv |
Gene classification (Functional / ORF / Pseudo) with criteria |
enrichment.tsv |
Locus RSS enrichment ratio vs genomic background |
candidates.fasta |
Nucleotide sequences of all candidates |
candidates_aa.fasta |
Translated amino acid sequences |
Batch mode additionally produces:
summary.tsv— Cross-species summary table- Phylogenetic tree files (if MAFFT + IQ-TREE available)
| Parameter | Default | Description |
|---|---|---|
--genome |
— | Path to genome FASTA (single mode) |
--species |
— | Species name (single mode) |
--batch |
— | Path to batch TSV file |
--outdir |
— | Output directory |
--evalue |
1.0 | tBLASTn e-value threshold |
--min-pident |
60.0 | Minimum percent identity (%) |
--min-aln-length |
10 | Minimum alignment length (amino acids) |
--locus-window |
50000 | Single-linkage clustering gap threshold (bp) |
--locus-margin |
500000 | Margin around dominant locus cluster (bp) |
--locus-min-hits |
2 | Minimum hits to define a locus cluster |
--functional-ic-threshold |
18.0 | Minimum RSS IC for Functional classification |
--no-enrichment |
— | Skip RSS enrichment analysis |
--no-phylogeny |
— | Skip phylogenetic reconstruction |
--validate |
— | Run biological plausibility tests after analysis |
SAFARI-IGHJ includes pre-flight genome validation to prevent common methodological artifacts:
- File size check: Genome must be >= 50 MB (rejects IGH-region-only files)
- Header format check: Detects coordinate-based headers (e.g.,
scaffold:start-end) that indicate extracted regions instead of whole genomes - Scaffold count check: Requires >= 5 scaffolds (rejects single-scaffold extractions)
These checks ensure the locus clustering algorithm has a complete genome to work with, preventing artificially inflated enrichment ratios from pre-filtered inputs.
The pipeline includes 10 automated biological plausibility tests that run with --validate:
| # | Test | Severity | Description |
|---|---|---|---|
| 1 | Reference species counts | CRITICAL | Known species (Bos taurus, Ovis aries) must match expected IGHJ counts |
| 2 | RSS IC range | CRITICAL | All IC values must be within [0, 24.69] bits |
| 3 | Cluster size plausibility | MAJOR | Locus cluster must be < 500 kb |
| 4 | Scaffold clustering | MAJOR | Detects fragmented assemblies (hits on many scaffolds) |
| 5 | Diversity minimum | CRITICAL | Batch mode: minimum species diversity check |
| 6 | Phylogeny parameters | MINOR | Tree construction sanity checks |
| 7 | RSS enrichment | MAJOR | Locus RSS IC must exceed random background |
| 8 | Candidate count | MAJOR | Species must have < 30 candidates (sanity limit) |
| 9 | Functional ratio | MAJOR | At least 1 putative Functional gene expected |
| 10 | Cross-species consistency | MINOR | Outlier detection across batch |
# Run all 37 unit tests
pytest tests/ -v
# Run specific test module
pytest tests/test_locus.py -v # Locus identification (12 tests)
pytest tests/test_rss.py -v # RSS scoring (7 tests)
pytest tests/test_classification.py -v # Gene classification (13 tests)safari-ighj/
├── ighj_pipeline/ # Core pipeline package
│ ├── __init__.py # Package metadata (v1.0.0)
│ ├── __main__.py # CLI entry point
│ ├── pipeline.py # Main orchestrator
│ ├── mining.py # BLAST database + tBLASTn
│ ├── locus.py # Locus identification (key innovation)
│ ├── rss.py # RSS-23 IC scoring
│ ├── classification.py # Functional/ORF/Pseudo classification
│ ├── enrichment.py # RSS enrichment analysis
│ ├── phylogeny.py # MAFFT + IQ-TREE phylogeny
│ └── utils.py # Constants, helpers, I/O, genome validation
├── tests/ # Unit test suite (37 tests)
│ ├── test_rss.py
│ ├── test_locus.py
│ └── test_classification.py
├── validation/ # Biological validation framework
│ ├── biological_tests.py # 10 automated plausibility tests
│ └── ground_truth.py # Reference species expected values
├── data/queries/ # BLAST reference sequences
│ ├── IGHJ_protein_queries.fasta
│ └── IGHJ_nucleotide_queries.fasta
├── results/ # Output directory (generated by pipeline)
├── pyproject.toml # Package configuration
├── LICENSE # MIT License
└── README.md
If you use SAFARI-IGHJ in your research, please cite this repository:
Viana de Correia, J.P. (2026). SAFARI-IGHJ: Systematic Analysis of Framework Antibody RSS Immunogenomics. GitHub. https://github.com/jpierrevd/safari-ighj
MIT License. See LICENSE for details.
Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.