Skip to content

TElocal

Ali Altintas edited this page Aug 27, 2026 · 2 revisions

TElocal: Locus-Level TE Quantification

On by default (telocal.enabled: true); TElocal provides locus-level TE quantification as a complement to TEcount's subfamily-level counts. Where TEcount pools all copies of a TE subfamily into one count (e.g. all L1PA2 instances → one L1PA2 row), TElocal resolves TEs per genomic instance using the same EM-based multi-mapper assignment, reporting counts per locus (e.g. chr1:564318:564741(L1PA2:+):L1PA2:L1:LINE).

TElocal uses the same unsorted BAM as TEcount (results/star/{sample}_Aligned.out.bam), so no re-alignment is needed. Results go to results/telocal/{sample}.cntTable.gz. Per-sample summary barplots (gene-vs-TE assignment and TE class composition) are rendered in the MultiQC report (results/telocal/qc/telocal_assignment_mqc.json and telocal_te_class_mqc.json).

A sample-QC view mirrors the TEcount one (telocal.qc.*: enabled, view-only filters, pca_transform, feature_class): the per-sample tables are merged into a locus x sample counts matrix (results/telocal/counts_matrix.tsv.gz) that drives a PCA scatter and a sample-to-sample clustering heatmap in the report. The default transform is log2 — locus-level matrices hold one row per TE instance (often millions), which makes DESeq2's vst/rlog prohibitively slow; opt in deliberately if you want them.

Setup

TElocal requires a pre-built .locInd file — a pickled index built from the same TE GTF that TEcount uses. Build one with:

TElocal_indexer --afile TE.gtf --itype TE   # ~30 GB RAM for human genome

Or download prebuilt indices from https://www.mghlab.org/software/telocal. Set the path in your config:

telocal:
  enabled: true
  locind: /path/to/TE_annotation.locInd

When locind is empty, the workflow auto-builds the index from your TE GTF into results/telocal/telocal.locInd (the .locInd suffix is mandatory — TElocal rejects any --TE file whose path lacks it). It is kept by default; outputs.keep_telocal_index: false deletes it once all TElocal runs finish (a user-provided locind path is never touched). Auto-building trades disk for convenience.

Auto-building uses telocal.indexer: fast (default) — a drop-in reimplementation of TElocal_Toolkit's own index builder that fixes an O(n²) bottleneck (a list-membership check that should have been a set), verified against the original on real mouse rmsk data (3.7M TE instances): identical output, ~1000x faster (a build that took ~21 h dropped to ~1 min). Set telocal.indexer: legacy to fall back to TElocal_Toolkit's own unmodified builder if ever needed.

Set telocal.enabled: false to skip locus-level quantification entirely.

Subfamily vs locus

TEcount and TElocal report at two different levels of the same hierarchy:

  subfamily  L1PA2          <- ONE TEcount row: all copies pooled
     |
     +-- L1PA2_dup1   chr1:1,000-7,200      <- one TElocal row each
     +-- L1PA2_dup2   chr4:88,100-94,300
     +-- L1PA2_dup3   chrX:2,410-8,600

So a subfamily that looks uniformly expressed in TEcount may turn out to be one or two highly-expressed copies in TElocal, with the rest silent -- which is the whole reason to run both. The chimera screens' te_id is the insertion-level key, so it joins directly against TElocal rows; their te_subfamily column joins against TEcount rows.

Locus coordinates

TElocal's cntTables key TE rows by transcript_id:gene_id:family_id:class_id but never include genomic coordinates. results/telocal/telocal_locations.bed maps every such key to its coordinates as a standard BED6 (chrom, start, end, name, score, strand, 0-based; name is the TE key, score unused) — one pass over the TE GTF, always built when telocal.enabled is true — so you can join cntTable output against name and also load the file directly into bedtools/IGV. Kept uncompressed (unlike most pipeline outputs) so IGV can load it directly — plain gzip isn't the random-access-indexed format IGV needs.

Clone this wiki locally