telomerehunter2 1.0.1

An advanced version for TelomereHunter in Python 3 with new features

TelomereHunter2

TelomereHunter2 is a Python-based tool for estimating telomere content and analyzing telomeric variant repeats (TVRs) from genome sequencing data. It supports BAM/CRAM files, flexible telomere repeat and reference genome inputs, and provides outputs for bulk and single-cell genome sequencing data.

---

Release Notes

See RELEASE_NOTES.md for the latest changes and version history.

---

Features

• Fast, container-friendly Python 3 implementation
• Parallelization and algorithmic steps for drastic speedup
• Supports BAM/CRAM, custom telomeric repeats, and now also non-human genomes
• Static and interactive HTML reports (Plotly)
• Docker and Apptainer/Singularity containers
• Single cell sequencing support (e.g. scATAC-seq; barcode splitting and per-cell analysis)
• Robust input handling and exception management
• Fast mode for quick overview of unmapped reads

Installation

Classic setup:

pip install telomerehunter2

From source:

# With pip:
git clone https://github.com/ferdinand-popp/telomerehunter2.git
cd telomerehunter2
python -m venv venv
source venv/bin/activate
pip install -e . --no-cache-dir

# With uv:
git clone https://github.com/ferdinand-popp/telomerehunter2.git
cd telomerehunter2
uv pip install -e . --no-cache-dir

Container usage:
See Container Usage for Docker/Apptainer instructions.

Quickstart

Bulk Analysis

telomerehunter2 -ibt sample.bam -o results/ -p SampleID -b telomerehunter2/cytoband_files/hg19_cytoBand.txt

For all options:

telomerehunter2 --help

Single Cell Analysis

telomerehunter2_sc -ibt sample.bam -o results/ -p SampleID -b telomerehunter2/cytoband_files/cytoband.txt --min-reads-per-barcode 10000

See Bulk Analysis and Single cell sequencing Analysis below for more details.

Usage

Bulk Analysis

• Single sample:
  telomerehunter2 -ibt tumor.bam -o out/ -p TumorID -b cytoband.txt
• Tumor vs Control:
  telomerehunter2 -ibt tumor.bam -ibc control.bam -o out/ -p PairID -b cytoband.txt
• Custom repeats/species:
  telomerehunter2 ... --repeats TTTAGGG TTAAGGG --repeatsContext TTAAGGG
• Fast mode (quick overview of unmapped reads generating summary with overview):
  telomerehunter2 -ibt sample.bam -o out/ -p SampleID --fast_mode

Single cell sequencing Analysis

TelomereHunter2 now supports direct single-cell BAM analysis (with CB barcode tag). Simply run:

telomerehunter2_sc -ibt sample.bam -o results/ -p SampleID -b telomerehunter2/cytoband_files/cytoband.txt --min-reads-per-barcode 10000

This will perform barcode-aware telomere analysis and output per-cell results in a summary file. The minimum reads per barcode threshold can be set with --min-reads-per-barcode.

See tests/test_telomerehunter2_sc.py for example usage and validation.

Input & Output

Input:

• BAM/CRAM files (aligned reads)
• Cytoband file (tab-delimited, e.g. hg19_cytoBand.txt)
• Optional: custom telomeric repeats

Output:

• summary.tsv, TVR_top_contexts.tsv, singletons.tsv
• Plots (plots/ directory, PNG/HTML)
• Logs (run status/errors)
• For sc-seq: Additionally to the complete bulk run you get per-cell results in sc_summary.tsv and barcode_counts.tsv with reads counts per barcode

Dependencies

• Python >=3.6
• pysam, numpy, pandas, plotly, PyPDF2
• For static image export: kaleido (requires chrome/chromium)
• Docker/Apptainer (optional)

Install all dependencies:

pip install -r requirements.txt

Container Usage

Docker (recommended):

Build locally:

docker build -t telomerehunter2 .
docker run --rm -it -v /data:/data telomerehunter2 telomerehunter2 -ibt /data/sample.bam -o /data/results -p SampleID -b /data/hg19_cytoBand.txt

Pull from Docker Hub:

docker pull fpopp22/telomerehunter2

Run from Docker Hub:

docker run --rm -it -v /data:/data fpopp22/telomerehunter2 telomerehunter2 -ibt /data/sample.bam -o /data/results -p SampleID -b /data/hg19_cytoBand.txt

Apptainer/Singularity:

Build locally:

apptainer build telomerehunter2.sif Apptainer_TH2.def
# mount data needed
apptainer run telomerehunter2.sif telomerehunter2 -ibt /data/sample.bam -o /data/results -p SampleID -b /data/hg19_cytoBand.txt

Pull from Docker Hub (as Apptainer image):

apptainer pull docker://fpopp22/telomerehunter2:latest
apptainer run telomerehunter2_latest.sif telomerehunter2 ...

Troubleshooting

• Memory errors: Use more RAM or limit cores used with -c flag.
• Missing dependencies: Check requirements.txt.
• Banding file missing: Needs reference genome banding file -b otherwise analysis will run without reads mapped to subtelomeres.
• Plotting: Try disabling with --plotNone or use plotting only mode with --plotNone.
• Minor changes to TH1: Skipping the tvrs normalization per 100 bp, improved detection of GXXGGG TVRs, read lengths are estimated from first 1000 reads, added TRPM

For help: GitHub Issues or our FAQ.

Documentation & Resources

• Wiki (WIP)
• Example Data
• Tutorial Videos (WIP)
• Original TelomereHunter Paper

Citation

If you use TelomereHunter2, please cite:

• Feuerbach, L., et al. "TelomereHunter – in silico estimation of telomere content and composition from cancer genomes." BMC Bioinformatics 20, 272 (2019). https://doi.org/10.1186/s12859-019-2851-0
• Application Note for TH2 (in preparation).

Contributing

Fork, branch, and submit pull requests. Please add tests and follow code style. For major changes, open an issue first.

License

GNU General Public License v3.0. See LICENSE.

Contact

• Ferdinand Popp ([e-mail])
• Lars Feuerbach ([e-mail])

Acknowledgements

Developed by Ferdinand Popp, Lina Sieverling, Philip Ginsbach, Lars Feuerbach. Supported by German Cancer Research Center (DKFZ) - Division Applied Bioinformatics.

---

Copyright 2025 Ferdinand Popp, Lina Sieverling, Philip Ginsbach, Lars Feuerbach