Overview

Overview

intronIC is a modular tool for intron extraction and U12-type/U2-type classification. It has two primary uses:

1. Classification mode: Score all annotated introns against expectations for U12-type introns, and classify each as U2- or U12-type using a single calibrated RBF SVM ensemble (v3 default: the pmotif_adjudicated raw-feature ensemble, 42 sub-models) on 6 sequence-derived motif features, followed by an output-level species adjudicator.
2. Extraction mode: Retrieve all annotated intron sequences and associated metadata (using intronIC extract).

intronIC supports multiple input modes:

• Genome + annotation (GFF3/GTF)
• Genome + BED file for coordinate-based extraction
• Pre-extracted sequences (.iic format) for classification-only runs

Scientific Background

Minor vs Major Spliceosomes

Eukaryotic pre-mRNA splicing is catalyzed by two distinct spliceosomes:

Major (U2-dependent) spliceosome: Splices ~99.5% of introns

• Recognizes GT-AG (most common) or GC-AG terminal dinucleotides
• Uses U1, U2, U4, U5, U6 snRNPs
• Branch point consensus: loose, A within ~18-40 nt of 3'SS

Minor (U12-dependent) spliceosome: Splices ~0.5% of introns

• Recognizes both AT-AC (~25%) and GT-AG (~75%) terminal dinucleotides
• Uses U11, U12, U4atac, U6atac, U5 snRNPs
• Branch point consensus: highly conserved TCCTTAAC motif, typically 10-15 nt from 3'SS (median ~13 nt)

Despite their rarity, U12-type introns are functionally important and evolutionarily conserved across most eukaryotic lineages. A species that retains U12-type introns is a bearer; a lineage that has lost the minor spliceosome (and with it its U12-type introns) is a U12-loss lineage. Such loss has been documented in several lineages including C. elegans, certain fungi, and some protists (Alioto 2007; Larue & Roy 2023).

Classification basics

intronIC assigns each intron a binary classification (u12 or u2) and an adjusted score (0–100) on the adjudicated calling scale. The call rule is: type_id = u12 iff P_motif ≥ 0.5 (equivalently adjusted_score ≥ 50) and the genome's motif_category is not NOT_DETECTED; otherwise u2. Here P_motif is the species-agnostic, Platt-calibrated motif probability from the SVM ensemble, and motif_category is the per-species population verdict from the adjudicator (only NOT_DETECTED suppresses calls; INCONCLUSIVE/UNASSESSABLE still let strong-motif introns call). A separate rel_score column re-centers the adjusted score on the default high-confidence threshold of 90, so rel_score > 0 marks a U12-type call above that threshold; see Output files for its full definition.

One useful sanity check is to examine the plot.scatter.iic.png and plot.hex.iic.png figures for clear separation between putative intron types.

For example, here is the score scatter plot for introns in human (each point is an intron, and the x and y axes are the background-corrected raw motif log-odds for the 5'SS and BPS motifs, respectively), with introns classified as U12-type at probability >90% in green:

Here is the same kind of plot for D. melanogaster, which has undergone significant (though incomplete) minor intron loss:

D. melanogaster retains a small complement of genuine U12-type introns (here 20, of which 18 are high-confidence at >90%, shown in green) that form a compact cluster cleanly separated from the main U2-type population, a shrunken but unambiguous minor-intron set.

Species-level gate suppression

A genome that has lost the minor spliceosome can still contain a few introns whose motifs happen to resemble U12-type sites by chance. Where they occur, these motif-strong false positives would be reported as minor introns if the call were made on motif alone. The species-level adjudicator is what prevents that. The three panels below follow C. elegans (complete U12-type loss) from raw motif scores, through the adjudicator's test, to the final call.

1. Raw motif scores (unadjudicated). Each intron is coloured by its own motif probability P_motif, before any species-level decision (.plot.scatter_raw.iic.png, emitted only for NOT_DETECTED genomes). Eight introns score above the 90% motif threshold and 13 more between 50% and 90%. But they are few, and sit at the ragged edge of the U2-type cloud rather than forming the distinct, well-separated population seen in D. melanogaster or human.

2. The adjudicator's test (tail model). The adjudicator fits the genome's own U2-type background-margin tail (gray) and asks whether the strong calls (green) exceed what that tail predicts. Here they fall on the extrapolated tail, not above it (z_excess = 0.58, p_gumbel = 0.6): no more high-scoring introns than the genome's own background produces by chance.

3. The final call (adjudicated). Because the strong calls do not clear the background, the genome is marked NOT_DETECTED and the calls are suppressed: the standard scatter, coloured by the final call, shows 0 U12-type.

This is how intronIC avoids reporting a genome's background motif noise as spurious minor introns.

Classification method

intronIC uses the following pipeline (v3):

1. PWM Scoring — Score three key regions against position-weight matrices:

   • 5' splice site (donor): -3 to +9 relative to intron start
   • Branch point: Search window -55 to -5 from 3'SS
   • 3' splice site (acceptor): -6 to +4 relative to intron end

2. Background Correction — Blend species-specific nucleotide frequencies into U2-type denominator PWMs to correct composition bias, yielding background-corrected raw motif log-odds (see Technical Details)

3. Motif classification — Score every intron with the calibrated RBF SVM ensemble (pmotif_adjudicated, 42 sub-models) on the 6 raw features (5'_raw, bp_raw, 3'_raw, bp_offset, bp_scan_confidence, support2_raw) → a per-intron ensemble margin → P_motif, a species-agnostic, Platt-calibrated motif probability

4. Species adjudication — At the genome level, compute z_excess (the Poisson significance of the strong-call count against the genome's own U2-type background tail) plus a per-genome strength gate, and assign a motif_category ∈ {DETECTED, INCONCLUSIVE, NOT_DETECTED, UNASSESSABLE} (see Technical Details)

5. Calling — type_id = u12 iff P_motif ≥ 0.5 and motif_category ≠ NOT_DETECTED; write adjusted_score (the 0–100 calling scale) and rel_score = adjusted_score − 90

For more details on the algorithm, the raw features, and the pretrained model architecture, see the Technical Details page.

Intron scoring applies to unique introns only

Importantly, by default intronIC only processes introns with unique coordinates from the longest annotated isoform for each gene (though this behavior is adjustable). Therefore, the same intron from multiple isoforms will only be included once, and named based upon the longest isoform. See Training data and PWMs and Data filtering notes for additional caveats.

Brief method summary

intronIC should process most annotations, including imperfectly formatted ones, provided they roughly adhere to GFF3/GTF formatting standards, and produce a set of output files described in detail on the Output files page. In order to work with intronIC, the annotation file must have parent information in the last column, such that all features (CDS or exon) from the same transcript/gene can be associated with one another. Beyond that requirement, the parser should be fairly flexible.

At a high level, intronIC works by aggregating all of the CDS/exon sequences under their parent transcripts and/or genes based on the parent-child relationships given by the last column in the annotation file. CDS features are used preferentially, as they allow intron phase to be determined, but exon features are also used in cases where they define unique introns (unless run with -f cds).

Then, in classification mode, it scores those introns and classifies each one with the pretrained model, following the pipeline described under Classification method above. The output includes intron sequences, metadata, and classification results. Custom models can be trained for specialized use cases with the train subcommand.

Basic usage

A typical default scoring run uses both CDS and exon features to define introns, includes introns with non-canonical splice boundaries, and uses the built-in pretrained model:

intronIC -g {genome} -a {annotation} -n {binomial_name}

For the sample data:

intronIC -g Homo_sapiens.Chr19.Ensembl_91.fa.gz -a Homo_sapiens.Chr19.Ensembl_91.gff3.gz -n homo_sapiens

Additional features

intronIC v3 also supports:

• YAML configuration files for managing complex parameter sets (see Example usage)
• Pretrained model producing a species-agnostic P_motif motif probability for cross-species classification, with no per-species recalibration
• Output-level species adjudicator (z_excess gap gate + per-genome strength gate → motif_category) that flags U12-type population evidence without any per-species z-normalization
• Species-specific U2-type background correction for cross-species composition bias
• Ensemble training with cross-validation (--n-models)
• Parallel processing (-p)
• Streaming mode (enabled by default) for roughly half the peak memory of --in-memory mode, with bit-identical classifications

Streaming mode (default)

Streaming mode is the default. It writes intron sequences to temporary on-disk storage during extraction and keeps only scoring motifs in memory; the full pipeline (extraction, BG correction, PWM scoring, classification) parallelizes per-contig. --streaming and --in-memory produce bit-identical classifications, so the choice is purely a memory tradeoff (streaming roughly halves peak memory). For benchmark timings and peak-memory figures on a full human genome, see Technical Details — Memory and Performance.

# Human genome with streaming (default)
intronIC -g GRCh38.fa.gz -a gencode.gff3.gz -n homo_sapiens -p 8

To disable streaming mode, pass --in-memory. In-memory is also the path used internally by -q (sequence input) and -b (BED input) modes.

See Quick start for further instructions on getting set up and checking your installation on test data.