Docs: report sections are named by evidence source now
The MultiQC report used four section names built on "chimera" with nothing
saying what distinguished them, and three of them were views of one screen.
They are now two sections named for the evidence each uses:
Gene-TE chimeras: read evidence (chimera.junction)
Gene-TE chimeras: transcript evidence (chimera.assembly)
Chimera Detection opens with a table mapping report section -> config key ->
evidence, because the two vocabularies now differ on purpose: config keys,
rule names and output paths keep chimera.junction / chimera.assembly and
results/chimera_junction/, so nothing scripted against them breaks. Saying
that explicitly is the point -- a reader who sees "read evidence" in the
report and "junction" in their config should not have to guess they are the
same thing.
Interpreting Your Results: the "what to open, in order" steps now name the
new sections, and step 5 no longer says "junction-confirmed" -- on this
dataset screen agreement sat at its chance rate, so it now points at the
read-evidence screen without implying confirmation.
Docs: new Confidence Tiers page with the tier ladder as a diagram
chimera_evidence.tsv.gz gives every gene-TE pair a confidence_tier, and
until now that number was explained only as a table buried in Interpreting
Your Results. It gets its own page, built around an ASCII ladder that shows
the tiers stacked weakest-to-strongest with the reasoning for each rung
beside it.
Also diagrams what is NOT on the ladder, which is the part people will
otherwise re-derive wrongly: read depth, and telocal_active. Keeps the
measured numbers (91% coverage; 6.7% vs 10.2% canonical rate) next to the
conclusion, because the original reasoning for including TE expression was
plausible enough that someone will reach for it again.
Adds a table of artifact mode vs. what catches it, which is the actual
argument for canonical outranking reproducibility: template switching is
sequence-driven and recurs in every library, so replication does not rule
it out while a splice motif does.
Ends with worked examples of reading a row and awk recipes for cutting the
table down, with the honest framing that the strict set is small and the
remaining tens of thousands of rows are a screen, not a result.
Interpreting Your Results keeps the summary table and now links here instead
of restating the excluded-signals argument, so the two cannot drift.
Cross-linked from Home and Chimera Detection.
Docs: TE expression is context, not evidence; ladder is now 1-4
The confidence ladder had "the TE locus is expressed" above "has a splice
motif". A real 4-sample run showed that is backwards: the signal covers 91%
of gene-TE junctions, and junctions at an expressed locus are LESS likely to
be canonical (6.7% vs 10.2%). Records the measured numbers rather than just
the conclusion, since the original reasoning was plausible and someone will
reach for it again.
Ladder is now 1-4, ordered by discriminating power, with canonical above
reproducibility -- a sequence-driven template switch recurs across libraries,
so replication does not rule it out while a motif does.
Adds a "what is deliberately not on the ladder" section and a new common
misreading ("the TE is expressed, so the chimera is real").
Docs: how TElocal evidence attaches to a junction, and why it needs the BED
Chimera Detection gains a section on the telocal_active / telocal_count
columns and the positional join behind them.
Records the fact that just caused a silent wrong answer: a TElocal cntTable
key does NOT contain coordinates unless the TE GTF's transcript_id happens
to be a coordinate string, so telocal_locations.bed is the coordinate
source, and an index where no locus can be placed now fails loudly rather
than marking every locus unexpressed.
Docs: Interpreting Your Results; unified evidence table; BED tracks
New page: Interpreting Your Results. A finished run produces several
sections that all mention TEs, and nothing said which of them are
independent. The page separates the two questions the pipeline answers,
shows in a diagram that TEcount/TElocal are one measurement at two
resolutions while only the two chimera screens are independent, gives the
2-6 confidence ladder, and lists the misreadings that ladder is meant to
prevent.
It also carries the corrected canonical-rate guidance. Comparing gene_to_te
against `other` reads as 2.5x enriched, but the donor's annotation status
alone moves the rate from ~3% to ~10%, so most of that ratio is the donor
side. Against a matched background (gene_to_gene) it is 1.19x. The real
evidence is the pattern, not the ratio: both true gene-TE directions beat
their own donor group while the two classes with a TE but no gene partner
fall below theirs. Table of measured values included.
Chimera Detection: documents chimera_evidence.tsv.gz -- one row per
(gene_id, te_id) pair joining both screens, since junction rows are
breakpoint-keyed and assembly rows transcript-keyed and neither reads as
"the candidate list".
Output Layout: adds the reference/ BED tracks (genes.bed, exons.bed,
te.bed), which were never documented -- only annotation.bed12 was listed.
Notes te.bed's BED9 extension and the name/subfamily split: column 4 is the
individual insertion and joins TElocal, column 9 is the subfamily and joins
TEcount. Also adds the new chimera_evidence, junction_highlights and
evidence_overview outputs.
Docs: ASCII diagrams for the three things that are easy to get wrong
Each of these cost real debugging time this week, and each is a geometry
problem that prose describes badly:
- How a breakpoint is matched to a feature. STAR reports the neighbouring
INTRON base, not the aligned segment edge, and the offset mirrors on the
minus strand. Also states plainly that breakpoint_tolerance is for
annotation slack, not for absorbing coordinate error.
- chimera_type geometry. te_initiated / te_exonized / te_terminated read
off the TE's position along the direction of transcription, so the
labels swap on a minus-strand gene.
- The TE annotation hierarchy (class > family > subfamily > insertion) and
which GTF attribute holds each, with a before/after of what keying
te.bed by subfamily instead of insertion actually does to the intervals.
TElocal gets a companion diagram contrasting the pooled TEcount row with
the per-copy TElocal rows, and says which chimera column joins to which.
Docs: chimera.assembly is now enabled by default
It costs a second dedicated STAR pass per sample, and is still newer and
less validated than the junction screen, so the docs say both.
Chimera docs: what te_id refers to now that te.bed is per insertion
te.bed used to collapse every copy of a TE subfamily into one bounding box
(spanning whole chromosomes on real annotations). Now one interval per
insertion, so te_id is the specific copy. Documents the three distinct
levels -- te_id (insertion, joinable with TElocal), te_subfamily (what
TEcount reports), te_family -- since subfamily is not family.
Chimera docs: which file is which, ambiguous classification, gene-TE naming
- Chimera-Detection: table showing the four per-sample files are two
row-sets x two column-sets; the new direction_ambiguous flag and when
to distrust `direction`; other_to_te; and a note that the non-gene-TE
buckets collect circRNA back-splices and read-through/PCR artifacts,
since STAR's chimeric call is structural and annotation-blind.
- Output-Layout: the chimera block was stale (wrong directory name,
missing .gz, missing pca_ prefix, telocal file absent). Rewritten
against the actual rule outputs, plus the chimera_assembly tree
including its dedicated second STAR pass.
- Tool-Versions: add TElocal and StringTie, which were missing.
Add full documentation: config reference, CLI, HPC/SLURM, TElocal, chimera detection, output layout
Moved out of the main repo's README, which was trimmed to a short landing
page (install + quick start + links here).