solote

name	solote
display_name	SoloTE
description	Locus-specific transposable element quantification from single-cell RNA-seq BAMs, producing a gene+TE 10x-style count matrix.
license	GPL-3.0
metadata	null

SoloTE: Single-Cell Transposable Element Quantification

Overview

SoloTE quantifies transposable element (TE) expression in single-cell RNA-seq by re-annotating aligned, cell-barcoded BAM reads against TE genomic coordinates. The output is a 10x-style cell-by-feature matrix that fuses gene counts with locus-level (and where ambiguous, subfamily-level) TE counts.

Standard scRNA-seq pipelines (Cell Ranger, STARsolo) discard or down-weight multi-mappers — the same reads that hold most TE signal. SoloTE re-uses an existing BAM (no realignment) and routes TE-overlapping reads through a locus-vs-subfamily decision so that uniquely-mappable TE loci are preserved at locus resolution while ambiguous reads collapse to the subfamily level.

When to Use This Skill

• Single-cell TE quantification from 10x Genomics / Cell Ranger BAMs (cell-barcoded, UMI-tagged).
• Resolving locus-specific TE expression where multi-mappers usually get discarded by standard scRNA-seq pipelines.
• Adding TE features alongside genes for downstream Seurat / Scanpy clustering and differential expression.

Not for:

• FASTQ → BAM alignment (run Cell Ranger or STARsolo upstream first).
• Bulk RNA-seq TE quantification (use TEtranscripts / SQuIRE).
• BAMs without a CB cell-barcode tag (e.g. raw STAR output without --soloFeatures).

Prerequisites

git clone https://github.com/bvaldebenitom/SoloTE.git
cd SoloTE

# System tools — install via conda or your HPC module system
conda install -c bioconda "samtools>=1.16" "bedtools>=2.29.2" "r-base>=4"

# Python deps
pip install "pysam" "pandas>=1.5.0"

python SoloTE_RepeatMasker_to_BED.py -g hg38
# Replace hg38 with the build you aligned to (mm10, mm39, GRCh38, etc.).
# Produces a BED with col4 = locus|Subfamily:Family:Class — required input below.

Input Format

Input	Description
Aligned BAM	Cell-barcoded, UMI-tagged BAM. Cell Ranger's possorted_genome_bam.bam works out of the box; STARsolo output works if it carries the CB tag.
TE annotation BED	5-column BED: chr start end locus|Subfamily:Family:Class strand. Always (re)generate with SoloTE_RepeatMasker_to_BED.py -g <build> — hand-editing this file breaks the locus/subfamily decision logic.

Quick Start

python SoloTE_pipeline.py \
  --threads 8 \
  --bam possorted_genome_bam.bam \
  --teannotation hg38_rmsk.bed \
  --outputprefix sample1 \
  --outputdir ./results

Parameters

Name	Default	Description
--bam	required	Aligned, cell-barcoded BAM (Cell Ranger / STARsolo). Must carry the CB tag.
--teannotation	required	TE annotation BED from SoloTE_RepeatMasker_to_BED.py.
--outputprefix	required	Sample prefix prepended to all output filenames.
--outputdir	required	Destination directory for the MTX output and intermediates.
--threads	1	Parallelism for the samtools / bedtools steps. Bump to the per-job CPU budget on HPC.

Additional flags (e.g. read-length / locus-vs-subfamily thresholds) are not surfaced in the upstream README — consult python SoloTE_pipeline.py --help for the full list.

Output

A 10x-style MTX directory written to --outputdir, containing genes + TE features in a cells × features matrix:

<outputprefix>_SoloTE_output/
  matrix.mtx
  barcodes.tsv
  features.tsv

Feature naming:

• Genes keep their Ensembl / symbol IDs.
• TE features are named either by locus — SoloTE|chr:start-end|Subfamily:Family:Class — or, where reads can't be assigned to a single locus, collapsed to the subfamily.

Loads directly into Seurat (Read10X) or Scanpy (scanpy.read_mtx + companion barcodes/features).

Sharp Edges

• CB tag is mandatory. Input BAM must carry the cell-barcode tag — works out-of-the-box with Cell Ranger / STARsolo output; raw aligner BAMs without CB fail silently or produce empty matrices.
• TE BED format is strict. Column 4 must be locus|Subfamily:Family:Class — always (re)generate it with SoloTE_RepeatMasker_to_BED.py, never hand-edit.
• Resource scaling is undocumented. Memory and runtime scale with BAM size and --threads; expect multi-hour runs and tens of GB RAM for a typical 10x sample.
• Linux / macOS only in practice (samtools / bedtools chain) — no Windows-native support; use WSL or a remote HPC.
• /tmp is node-local on HPC. Point --outputdir at a shared filesystem path when running on compute nodes, or intermediates vanish between login and compute nodes.
• No alignment step. FASTQ → BAM (Cell Ranger / STARsolo) must be run upstream — SoloTE consumes BAMs, not reads.

References

• Source: github.com/bvaldebenitom/SoloTE
• Rodríguez-Quiroz R, Valdebenito-Maturana B. SoloTE for improved analysis of transposable elements in single-cell RNA-seq data using locus-specific expression. Communications Biology 5, 1063 (2022). DOI: 10.1038/s42003-022-04020-5