Skip to content

Chimera Detection

Ali Altintas edited this page Aug 28, 2026 · 10 revisions

Chimera Detection

What the two screens are called

The thing both screens look for is a gene-TE chimeric transcript. They differ only in the evidence they use, and the MultiQC report names them that way — "chimera" and "junction" on their own said nothing about the difference:

Report section Screen Evidence
Gene-TE chimeras: read evidence chimera.junction STAR chimeric reads — reads that cannot be explained by one linear alignment
Gene-TE chimeras: transcript evidence chimera.assembly StringTie transcript structure — an assembled transcript whose exons overlap a TE

Config keys, rule names and output paths keep their existing chimera.junction / chimera.assembly and results/chimera_junction/ names — only the report's section labels changed, so nothing you have scripted against those paths breaks.

Experimental. Both stages below are newer additions to the pipeline — classification and the sample-QC views may still change between releases. Use them for exploration and validate the output before relying on it for published results.

Gene-TE chimeras are detected by two independent, complementary methods: chimera.junction (STAR chimeric-junction reads, on by default — the original screen, detailed below) and chimera.assembly (StringTie transcript-structure evidence, also on by default — see The chimera-assembly screen). The junction screen only sees reads STAR can't explain as one linear alignment; a TE that splices into a gene via an ordinary, canonical, nearby intron aligns as a normal spliced read and never reaches it. The assembly screen exists specifically to catch that case instead. A candidate found by both is cross-referenced — see results/chimera_assembly/candidates_with_junction_evidence.tsv.gz.

If you only want one file, read results/chimera_junction/chimera_evidence.tsv.gz — see The unified evidence table at the bottom of this page. For how to weigh these outputs against each other, see Interpreting Your Results.

The chimera-junction screen

On by default (chimera.junction.enabled: true); set it to false to opt out and return to a plain quantification pipeline. When on, the same STAR alignment that feeds TEcount also detects gene-TE chimeric junctions (no separate alignment step). Per sample, STAR's chimeric junction records (Chimeric.out.junction, from --chimOutType Junctions WithinBAM SoftClip) are annotated against the gene (exon) and TE BED tracks and collapsed into an event table (results/chimera_junction/{sample}_junctions.tsv.gz). Each row is one junction, classified by what its two breakpoint loci overlap:

direction meaning
gene_to_te / te_to_gene a gene exon joined to a TE — the event of interest
gene_to_gene, te_to_te both loci in the same feature class (still recorded)
gene_to_other, other_to_gene, te_to_other, other_to_te one annotated locus, one unannotated
other neither breakpoint overlaps an exon or TE

The non-gene-TE classes are not just noise. STAR's "chimeric" is a purely structural call — a read that cannot be explained by one linear alignment (different chromosomes, inverted strand, out-of-order back-splice, or an over-long gap). STAR never reads annotation, so these buckets also collect circRNA back-splices, read-through transcripts, and PCR/ligation chimeras. Only gene_to_te / te_to_gene are gene-TE chimeras.

How a breakpoint is matched to a feature

STAR does not report the last/first base of the aligned segment. It reports the neighbouring intron base: column 2 is the first base of the donor's intron, column 5 the last base of the acceptor's intron. The feature edge is therefore always one step inward from the number in the file:

              DONOR SIDE (5' half)                    ACCEPTOR SIDE (3' half)
        -- exon --| intron - - - - - - - - - - - intron |-- exon --

 base:  999  1000 | 1001  1002              1999  2000 | 2001  2002
      +-----+-----+                                    +-----+-----+
      | ... |  E  |                                    |  S  | ... |
      +-----+-----+                                    +-----+-----+
              ^     ^                              ^     ^
              |     |                              |     |
     exon ENDS|     |STAR reports 1001    STAR reports   |exon STARTS
        at 1000     |(FIRST base of       2000 (LAST     at 2001
                    | the intron)         base of intron)

So the parser tests base bp-1 for a donor and bp+1 for an acceptor -- and that flips on the minus strand, where the transcript runs the other way:

   + strand:   exon --->| intron            intron |<--- exon
               donor tests bp-1             acceptor tests bp+1

   - strand:   intron |<--- exon            exon --->| intron
               donor tests bp+1             acceptor tests bp-1

breakpoint_tolerance widens the window around that base. It exists for genuine annotation-convention slack, not to absorb coordinate error -- a breakpoint sitting exactly on a feature edge resolves at tolerance 0.

When the classification is ambiguous

A single breakpoint can overlap both a gene exon and a TE — TEs sit inside gene bodies routinely. In that case more than one of the classes above genuinely applies and the first matching one simply wins. Those rows carry direction_ambiguous = yes, so the reported direction (and the chimera_type derived from it) is one defensible reading of an ambiguous locus, not the only one. The donor_hits / acceptor_hits columns always carry the full gene+TE sets (gene:ENSG1,ENSG2|te:AluJb_3) — check those before trusting a single label at multi-copy or nested-TE loci. The per-sample QC table reports the count as ambiguous_direction.

What te_id refers to

te_id is the individual TE insertion (L1PA2_dup1 — the TE GTF's transcript_id), not the subfamily. Three levels are reported, and they are genuinely different:

column example level
te_id L1PA2_dup1 the specific insertion — joinable with TElocal
te_subfamily L1PA2 the level TEcount reports, for cross-referencing
te_family L1 the family

The three are nested, and the TE GTF stores them in different attributes:

  class     LINE                          <- class_id
    |
    +-- family     L1                     <- family_id
          |
          +-- subfamily  L1PA2            <- gene_id        (TEcount's row)
                |
                +-- insertion  L1PA2_dup1   chr1:1,000-7,200   <- transcript_id
                +-- insertion  L1PA2_dup2   chr4:88,100-94,300
                +-- insertion  L1PA2_dup3   chrX:2,410-8,600

te.bed is built per insertion. That distinction is not cosmetic -- keying it by subfamily instead (taking min-start/max-end across every copy) collapses a whole family of scattered insertions into one interval:

  per subfamily (WRONG):   chr1 |==========================| one 192 Mb interval
                                 ^dup1                ^dup2
                                 every breakpoint in between "hits L1PA2"

  per insertion (CORRECT): chr1 |=|                    |=|  ~6 kb each
                                dup1                  dup2

With the collapsed version the breakpoint-overlap test cannot fail, so essentially every junction is called a TE hit. Measured on a real GRCm38 rmsk annotation, the worst such interval spanned 192,359,570 bp.

Columns include the breakpoint coordinates/strands, STAR junction type and whether it is canonical (GT/AG), the number of supporting reads, the donor/ acceptor overlap hits, the gene and TE ids (+ subfamily/family/class), a chimera_type label for gene-TE events (te_initiated / te_terminated / te_exonized, from the gene's strand and the TE's position relative to it), an antisense flag, and the strandedness-derived gene_strand_match above.

chimera_type is read off the TE's position relative to the gene, along the direction of transcription -- so the labels mirror on the minus strand:

  + strand gene   (transcription --->)

     [TE]        +--------- gene ---------+        [TE]
      ^                      ^                       ^
  te_initiated          te_exonized            te_terminated
  TE before the TSS     TE inside the body     TE past the 3' end

  - strand gene   (transcription <---)

     [TE]        +--------- gene ---------+        [TE]
      ^                      ^                       ^
  te_terminated         te_exonized            te_initiated

Only assigned for gene<->TE events whose two breakpoints are on the same chromosome; a trans event gets ., since "upstream" has no meaning across two chromosomes.

Reading the table. When a breakpoint overlaps several genes or several TE copies, the reported gene_id / te_id (and the chimera_type derived from their spans) use the alphabetically-first hit — deterministic and reproducible, but only one of the candidates. The full overlap set per junction is always in the donor_hits / acceptor_hits columns (e.g. gene:ENSG1,ENSG2|te:AluJb_3), so check those at multi-copy / nested-TE loci. And note the pipeline never applies a read-count filter: all_events.tsv.gz and counts_matrix.tsv.gz carry every annotated event verbatim, so apply your own min-reads / min-replicates cut before treating any call as confident.

Which per-sample file is which

Four per-sample tables, which are just two row-sets × two column-sets — not four different analyses:

File vs. the base file Contents
{sample}_junctions.tsv.gz (base) every chimeric junction, all directions
{sample}_junctions_te-gene-chimeras.tsv.gz fewer rows same columns, gene↔TE junctions only
{sample}_junctions_with-telocal.tsv.gz more columns same rows as the base, + TElocal locus columns
{sample}_junctions_te-gene-chimeras_with-telocal.tsv.gz both gene↔TE rows and TElocal columns

The two _with-telocal files only exist when telocal.enabled is true. Note the naming: _ separates components, - joins words inside one, so under byte-order sorting (LC_ALL=C, i.e. sort and most HPC shells) the base file lists first with its variants grouped beneath it.

The per-sample tables then merge into:

  • results/chimera_junction/all_events.tsv.gz — every event across samples (with the per-sample supporting read counts and a total).
  • results/chimera_junction/te-gene-chimeras.tsv.gz — the all_events catalog filtered to the gene-TE chimeras only (direction gene_to_te/te_to_gene), same columns — the gene-TE chimeras as their own table, no filtering needed.
  • results/chimera_junction/counts_matrix.tsv.gz — events x samples read counts.
  • results/chimera_junction/{sample}_junctions_te-gene-chimeras.tsv.gz — per sample, the same gene-TE filter of {sample}_junctions.tsv.gz (same columns, handy for per-sample inspection or IGV-style work).
  • results/chimera_junction/qc/{sample}_junction_qc.tsv.gz — per-sample summary (total junctions, gene-TE vs other, canonical/non-canonical split, repeat-flagged count, top families/classes).
  • results/chimera_junction/qc/junction_qc_mqc.json — a junction-QC barplot for the report: per sample, junction counts (and % of total junctions) by direction (gene_to_te/te_to_gene first, then the other classes), switchable between counts and % in the interactive plot.
  • results/chimera_junction/qc/te_gene_chimeras_mqc.json — the Gene-TE chimeras barplot: the gene↔TE subset on its own (gene_to_te vs te_to_gene, counts and % of total junctions), the last chimera view in the report.

If chimera.junction.outputs.write_counts_matrix is on (default), a sample-QC view is produced with DESeq2 (nf-core/rnaseq style): the counts matrix is transformed (vst/rlog/log2, chimera.junction.qc.pca_transform), and the transformed matrix drives a PCA scatter and a sample-to-sample distance heatmap, written as MultiQC custom-content JSON and rendered interactively inside multiqc_report.html (points colored by the sample sheet's condition column). The chimera.junction.qc filters (min_samples_present, min_total_counts, min_events) apply only to this QC view — the event catalog and counts matrix are never reduced. If too few events pass the filters, the plot rule ships empty custom-content JSON (the report documents the skip) and a log message instead of failing.

With chimera.junction.outputs.write_igv_bed: true, each sample also gets a BED track of its gene-TE junctions (results/chimera_junction/igv/{sample}_junctions.bed) for direct loading in IGV (optionally colored by direction).

chimera.junction.require_canonical_junction: true restricts the gene-TE classification to canonical (GT/AG) junctions; the default keeps everything and records the canonical flag in the table. The chimera.junction.star parameters are passed through to STAR's chimeric-alignment detection; the shipped defaults follow the TEtranscripts authors' recommendations for gene-TE chimeras. The screen calls for at least 2 samples (the PCA/heatmap view needs replicates); the QC-view min_events floor controls when the plots are drawn.

How chimeric TEs are detected (junction screen)

The chimera screen reuses the same STAR alignment that feeds TEcount — no separate alignment step. STAR is asked for chimeric junction records (--chimOutType Junctions WithinBAM SoftClip), each chimeric read becomes one line in {sample}_Chimeric.out.junction, and the pipeline annotates those breakpoints against the gene and TE tracks. The whole flow:

flowchart TD
    subgraph reference["Reference (built once)"]
        gtf["gene GTF"] --> bed["annotation_to_bed.py"]
        te_gtf["TE GTF"] --> bed
        bed --> genes["genes.bed"]
        bed --> exons["exons.bed"]
        bed --> te["te.bed"]
    end

    subgraph alignment["Alignment (per sample)"]
        reads["trimmed reads"] --> star["STAR alignment<br/>--chimOutType Junctions WithinBAM SoftClip<br/>--chimSegmentMin 12 · --chimJunctionOverhangMin 12<br/>--chimScoreDropMax 20"]
        star --> bam["sorted BAM<br/>(SA tags → IGV re-inspection)"]
        star --> junc["{sample}_Chimeric.out.junction<br/>one line per chimeric read:<br/>donor 5' / acceptor 3' breakpoints, strands,<br/>junction type, repeat flag"]
    end

    subgraph annotate["Per-sample junction annotation"]
        junc --> parse["parse_chimeric_junctions.py"]
        genes --> parse
        exons --> parse
        te --> parse
        stranded["RSeQC strandedness"] --> parse
        parse --> classify["classify each breakpoint pair by track overlap<br/>gene_to_te · te_to_gene → the event of interest<br/>gene_to_gene · te_to_te · gene_to_other · te_to_other · other<br/>(annotate-only: nothing is filtered away)"]
        classify --> event["{sample}_junctions.tsv<br/>event_id · supporting reads · gene/TE ids<br/>family/class · chimera_type<br/>(te_initiated / te_terminated / te_exonized)<br/>antisense flag · strand match"]
    end

    subgraph aggregate["Aggregation"]
        event --> counts["chimera_counts.py"]
        counts --> all_events["all_events.tsv"]
        counts --> matrix["counts_matrix.tsv"]
    end

    subgraph qc["QC & inspection"]
        event --> jqc["junction_qc.py"]
        jqc --> jq["per-sample junction QC table"]
        jq --> jqb["junction QC barplot (counts + % by direction)<br/>→ MultiQC report"]
        matrix --> sqc["sample_qc.R<br/>DESeq2 transform (vst/rlog/log2)"]
        sqc --> plots["PCA scatter + sample-distance heatmap<br/>→ MultiQC report"]
        event --> igv["junctions_to_igv_bed.py<br/>(optional)"]
        igv --> bedtrack["IGV BED track"]
    end
Loading

Stage by stage:

  1. Reference (once) — annotation_to_bed.py turns the gene GTF and the curated TE GTF into three BED tracks (genes.bed, exons.bed, te.bed) that the breakpoint-overlap test runs against.
  2. Alignment — STAR detects chimeric alignments while it maps (defaults: chimSegmentMin 12, chimJunctionOverhangMin 12, chimScoreDropMax 20). Each chimeric read is reported as a donor (5') and acceptor (3') segment with breakpoint coordinates, strands, junction type and a repeat flag. The BAM's SA tags let any junction be re-inspected in IGV.
  3. Annotation — for every junction, the donor and acceptor breakpoints are tested against the exon and TE tracks (within chimera.junction.breakpoint_tolerance). A gene exon joined to a TE gives gene_to_te / te_to_gene — the event of interest; the other overlaps are recorded but not discarded. Identical junctions across reads collapse into one event with a supporting-read count, plus the chimera_type subclass (te_initiated / te_terminated / te_exonized, from the gene strand and the TE's position), an antisense flag, and a strandedness-derived strand match. Annotate-only by design: nothing is filtered here (optionally require_canonical_junction: true keeps only GT/AG junctions).
  4. Aggregation & QC — chimera_counts.py merges the per-sample tables into the all_events.tsv catalog and the event×sample counts_matrix.tsv. junction_qc.py gives a per-sample QC table, from which a junction-QC barplot (counts + % by direction) is merged into the report; sample_qc.R transforms the matrix (vst/rlog/log2) and renders the PCA + sample-distance heatmap in the MultiQC report. Optionally, an IGV BED track per sample supports visual curation of candidates.
A worked example (1 read, 2 hits)

A read whose 5' segment aligns to a LINE1 element and whose 3' segment aligns to an exon of gene G — a te_to_gene chimera:

  chr2 482492─482501                chr2 1005203─1005212
  TE L1PA_0123 (− strand)           gene G exon 1 (+ strand)

  5' ── A G G T T A G C T A | C C T T G G A A C G ── 3'
          └─── donor ───┘   └─── acceptor ───┘
          segment's last    segment's first
          base: 482501      base: 1005203

STAR's {sample}_Chimeric.out.junction line (one per chimeric read):

chr2   482501   -   chr2   1005203   +   1   0   ...
  └chrom┘ └donor bp┘ └strand┘   └acceptor bp┘ └strand┘  │   │
  (chr, donor breakpoint & strand, acceptor chrom,      │   └ repeat flag
   acceptor breakpoint & strand)                        └ junction type
                                                          (1 = canonical GT/AG)

The pipeline's annotation:

event_id:    chr2:482501:-:1005203:+:te_to_gene
direction:   te_to_gene            (5' donor → TE, 3' acceptor → gene exon)
gene_id:     ENSG000... (gene G),  strand +
te_id:       L1PA_0123,  family: L1, class: LINE
chimera_type: te_initiated          (TE upstream of G's TSS on the gene strand)
reads:       7                      (7 supporting reads collapsed into one event)
canonical:   yes
gene_strand_match: yes              (forward-stranded library)

The chimera-assembly screen

On by default (chimera.assembly.enabled: false to skip it). Complements the junction screen above rather than replacing it: STAR only flags a junction as chimeric when a read can't be explained by one linear (possibly spliced) alignment, so a TE that splices into a gene via an ordinary, canonical, nearby intron aligns as a completely normal spliced read and never reaches the junction screen at all. This screen catches that case instead, from StringTie's assembled transcript structure rather than from split reads.

Pipeline: per-sample StringTie assembly (stringtie_assemble, from a dedicated STAR alignment pass with --outSAMstrandField intronMotif — needed for StringTie's strand inference on unstranded data; this suppresses non-canonical-junction reads from that one private BAM only, not the main alignment everything else uses) → cross-sample structural union (stringtie_merge) → per-sample re-quantification (stringtie_requantify) → classification against the same genes.bed/exons.bed/te.bed tracks the junction screen already builds (chimera_assembly_classify) → a candidate × sample TPM matrix (chimera_assembly_quantify) → cross-reference against the junction screen's calls (chimera_assembly_cross_evidence).

For every multi-exon assembled transcript, exons are ordered 5′→3′ by strand, then:

condition chimera_type
first exon overlaps a TE, a downstream exon overlaps an annotated gene exon te_initiated
first exon overlaps a TE, no downstream exon matches any annotated gene te_initiated_intergenic
an internal exon (not first, not last) overlaps a TE te_exonized
the last exon overlaps a TE, an earlier exon matches an annotated gene te_terminated
single-exon transcript overlapping a TE (no splice evidence to confirm gene connectivity) unspliced_te_only, reported separately at lower confidence

Like the junction screen, this is annotate-only — every candidate is written out, with the full TE/gene overlap set preserved (not just the first hit) for inspecting multi-copy/nested-TE loci; apply your own TPM/replicate cutoff downstream. Output:

  • results/chimera_assembly/candidates.tsv.gz — every classified transcript.
  • results/chimera_assembly/tpm_matrix.tsv.gz — candidate × sample TPM.
  • results/chimera_assembly/candidates_with_junction_evidence.tsv.gz — the candidates table with confirmed_by_junction_screen and junction_supporting_reads columns added: a candidate found by both independent methods (assembly structure and chimeric-junction reads) is materially higher confidence than either alone.
  • results/chimera_assembly/igv/candidates.bed — a BED track of each candidate's TE-overlapping exon (not the whole transcript), colored by chimera_type, for loading alongside chimera.junction's own IGV track (chimera.assembly.outputs.write_igv_bed: true, default false).

TElocal evidence on a junction

When telocal is enabled, each gene↔TE junction is annotated with whether the TE locus at the breakpoint is actually expressed (telocal_count, telocal_locus, telocal_active). That is independent support for the TE side being real rather than a mapping artifact, and it is tier 5 of the confidence ladder.

The join is positional: the breakpoint is looked up against an interval index of the TElocal loci. Building that index needs each locus's coordinates — and a TElocal cntTable key does not generally contain them. The key is transcript_id:gene_id:family_id:class_id; only when the TE GTF's transcript_id is itself a coordinate string (the mghlab prebuilt annotations, chr1:564318:564741(L1PA2:+)) can coordinates be recovered from it. An rmsk-derived GTF naming insertions L1PA2_dup1 — the common case, and what the auto-built index produces — yields keys with no coordinates at all.

So coordinates come from results/telocal/telocal_locations.bed, whose name column is exactly the cntTable key. If none of the cntTable keys can be placed, the run fails rather than producing an empty index that would silently mark every locus unexpressed. The usual cause is a telocal.locind built from a different TE annotation than ref.te_gtf — both must describe the same insertions, since that key is the join.

The unified evidence table

The two screens key their output differently — junction rows are breakpoint-keyed (many rows per locus) and assembly rows are transcript-keyed — so neither file reads as "the candidate list", and comparing them by eye means doing a join by hand.

results/chimera_junction/chimera_evidence.tsv.gz is that join, done once: one row per (gene_id, te_id) pair, where te_id is the individual TE insertion (L1PA2_dup1), not the subfamily. Both screens must implicate the same copy to count as agreeing.

It is written whenever chimera.junction is enabled; the assembly columns are filled in when chimera.assembly is also on, and found_by records which screens saw each pair (junction / assembly / both).

Column Meaning
found_by junction, assembly, or both
confidence_tier 2–6, see below
junction_events / junction_reads how many breakpoints collapsed into this row, and their summed reads
junction_max_samples the best replicate support among those events
junction_canonical yes if any event carried a splice motif
telocal_active yes/no if TElocal ran, . if it did not
assembly_transcripts how many assembled transcripts hit this pair
assembly_transcript_ids which ones, for going back to candidates.tsv.gz

The tier is the highest level a pair reaches:

Tier Reached when
1 a gene-TE call exists at all (the floor)
2 seen in more than one sample
3 at least one junction is canonical
4 called by both screens

Read depth is deliberately not part of the ladder — it is the metric artifacts inflate most, so a 999-read bare call stays at tier 1. Reads are still reported, for ranking within a tier.

Neither is telocal_active. It was a tier until a real run showed it is near-universal (91% of gene-TE junctions) and anti-correlated with the splice motif — 6.7% canonical where the TE locus is expressed vs 10.2% where it is quiet.

Confidence Tiers has the full ladder as a diagram, why canonical outranks reproducibility, worked examples of reading a row, and how to filter down to a defensible candidate list.

Rows are written best-first, so zcat chimera_evidence.tsv.gz | head is a usable triage step on its own. The table is strictly coarser than its sources: to see the individual breakpoints or transcripts behind a row, go back to te-gene-chimeras.tsv.gz / candidates.tsv.gz with the same pair.

The MultiQC report's Gene-TE chimeras: read evidence → What to look at and Gene-TE chimeras: transcript evidence → What to look at sections apply the same reasoning to rank this run's top candidates inline, and the report's Start here section says which evidence layers were actually available. See Interpreting Your Results.

Clone this wiki locally