Repository navigation
Chimera Detection
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.
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.
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.
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.
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.
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— theall_eventscatalog filtered to the gene-TE chimeras only (directiongene_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_genefirst, 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_tevste_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.
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
Stage by stage:
-
Reference (once) —
annotation_to_bed.pyturns 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. -
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. -
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 givesgene_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 thechimera_typesubclass (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 (optionallyrequire_canonical_junction: truekeeps only GT/AG junctions). -
Aggregation & QC —
chimera_counts.pymerges the per-sample tables into theall_events.tsvcatalog and the event×samplecounts_matrix.tsv.junction_qc.pygives a per-sample QC table, from which a junction-QC barplot (counts + % by direction) is merged into the report;sample_qc.Rtransforms 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)
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 withconfirmed_by_junction_screenandjunction_supporting_readscolumns 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 bychimera_type, for loading alongsidechimera.junction's own IGV track (chimera.assembly.outputs.write_igv_bed: true, defaultfalse).
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 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.