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:
---

# SoloTE: Single-Cell Transposable Element Quantification

## Overview

[SoloTE](https://github.com/bvaldebenitom/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

```bash
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

```bash
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](https://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](https://doi.org/10.1038/s42003-022-04020-5)