Satellome

A comprehensive bioinformatics tool for analyzing satellite DNA (tandem repeats) in telomere-to-telomere (T2T) genome assemblies.

Overview

Satellome uses FasTAN (Fast Tandem Repeat Finder) as its default tandem repeat detection engine, providing fast and accurate identification of repetitive DNA sequences. The tool classifies and visualizes tandem repeats with a focus on centromeric and telomeric regions.

The tool is designed to work with various genome assembly projects including:

• T2T (Telomere-to-Telomere) Consortium assemblies
• DNA Zoo chromosome-length assemblies
• VGP (Vertebrate Genome Project) assemblies
• NCBI RefSeq and GenBank assemblies

Features

• Fast Tandem Repeat Detection: Uses FasTAN by default for rapid, accurate detection
• Smart Classification: Categorizes repeats into microsatellites, complex repeats, and other types
• Rich Visualizations: Generates karyotype plots and chromosome-level visualizations
• Annotation Integration: Supports GFF3 and RepeatMasker annotations
• Parallel Processing: Efficient handling of large genomes
• Smart Pipeline: Automatically skips completed steps (override with --force)
• Compressed File Support: Direct processing of .gz compressed FASTA files
• Optional TRF Support: Traditional TRF analysis available with --run-trf flag

Quick Start

# Install from PyPI
pip install satellome

# Install required binaries (FasTAN, tanbed)
satellome --install-all

# Run on a genome
satellome -i genome.fasta -o output_dir -p project_name -t 8

Installation

From PyPI (Recommended)

pip install satellome

# Install external tools
satellome --install-all

From Source

git clone https://github.com/aglabx/satellome.git
cd satellome
pip install -e .
satellome --install-all

External Tools

Satellome requires FasTAN and tanbed for default operation. Install them automatically:

# Install all tools (FasTAN, tanbed, modified TRF)
satellome --install-all

# Or install individually
satellome --install-fastan
satellome --install-tanbed
satellome --install-trf-large  # For genomes with chromosomes >2GB

Build requirements: git, make, C compiler (gcc/clang)

# Ubuntu/Debian
sudo apt-get install build-essential git

# macOS
xcode-select --install

Usage

Basic Command

satellome -i genome.fasta -o output_dir -p project_name -t 8

Common Options

# With GFF3 annotations
satellome -i genome.fasta -o output_dir -p project_name -t 8 --gff annotations.gff3

# With RepeatMasker annotations
satellome -i genome.fasta -o output_dir -p project_name -t 8 --rm repeatmasker.out

# Force rerun all steps
satellome -i genome.fasta -o output_dir -p project_name -t 8 --force

# Also run traditional TRF analysis
satellome -i genome.fasta -o output_dir -p project_name -t 8 --run-trf

Parameters

Output Structure

output_dir/
├── genome.sat                    # Main SAT output (all arrays)
├── genome.1kb.sat                # Arrays >1kb
├── genome.3kb.sat                # Arrays >3kb
├── genome.10kb.sat               # Arrays >10kb
├── genome.micro.sat              # Microsatellites (1-9 bp monomers)
├── genome.complex.sat            # Complex repeats (>9 bp monomers)
├── genome.pmicro.sat             # Potential microsatellites
├── genome.tssr.sat               # Tandem simple sequence repeats
├── genome.gaps.bed               # Gaps annotation
├── results.yaml                  # Analysis statistics
├── run_manifest.json             # What the run produced (written last) + step statuses
├── fastan/                       # FasTAN intermediate files
│   ├── genome.1aln               # FasTAN alignment output
│   └── genome.bed                # FasTAN BED format
├── fasta/                        # FASTA sequences
│   └── genome.arrays.fasta       # All array sequences
├── gff3/                         # GFF3 annotations
│   ├── genome.1kb.gff
│   ├── genome.complex.gff
│   └── ...
├── images/                       # Visualizations
│   └── *.png
└── reports/                      # HTML reports
    └── satellome_report.html

Taxon Names in File Names

Karyotype charts are named after the taxon (--taxon, or the name resolved from --taxid). Organism names are free text and NCBI strain designations often contain slashes — Leishmania braziliensis MHOM/BR/75/M2904, Chlorella vulgaris CCAP 1055/1. Such a name is reduced to a single safe file-name component (..._MHOM_BR_75_M2904.karyo.*) and the substitution is logged; the plot titles keep the original name. Without this the slash was read as a path separator and the drawing step died with FileNotFoundError after the whole pipeline had already written its data.

Verifying a Run

Do not decide that an output directory is complete by checking that some files exist. A file that was read or copied while satellome was still writing it exists just as hard as a complete one, and a gzip of such a partial read is a valid archive that gzip -t accepts — so truncated data can enter downstream analysis unnoticed.

Every run writes run_manifest.json last, recording each file it produced with its byte size plus the status of every step. Verify against it:

satellome --verify-run output_dir

• exit 0 — the directory matches its manifest and no step failed
• exit 1 — not a verifiably complete run: no/corrupt manifest, a failed step, a missing file, a leftover *.partial, or a file whose size no longer matches what the run wrote (the truncated-copy case)
• exit 2 — the argument is not a directory

Files already compressed by your own pipeline are still checked: for a missing X with an X.gz next to it, the gzip ISIZE trailer (the uncompressed length the compressor actually consumed) is compared to the recorded size, which catches a .gz made from an incomplete read. Above 4 GiB that comparison is modulo 4 GiB and the report says so.

Two other guarantees back this up:

• Atomic outputs — files are written as <path>.partial and renamed into place, so a final name never refers to a half-written file. If you compress or copy an output directory concurrently, you either get the complete file or no file, never a truncated one.
• Output-directory lock — a second satellome run into the same -o is refused, naming the pid and host that holds it, instead of overwriting the first run's files mid-write. Override with --ignore-lock only if you are sure.

A run whose drawing step fails still writes a manifest — with drawing: failed — and exits non-zero. The data files are complete and usable; the failed step is recorded in the run's own artifact rather than only in an exit code.

SAT File Format

The SAT format is a tab-delimited file with the following columns:

Classification System

Satellome classifies tandem repeats into four categories:

Example Results

Analysis of CHM13 v2.0 human genome (3.1 GB):

Utility Scripts

Format Conversion

python scripts/trf_to_fasta.py -i repeats.sat -o repeats.fasta
python scripts/trf_to_gff3.py -i repeats.sat -o repeats.gff3

Analysis Tools

python scripts/trf_get_large.py -i repeats.sat -m 1000 -o large_repeats.sat
python scripts/trf_get_micro_stat.py -i repeats.sat -o micro_stats.txt
python scripts/check_telomeres.py -i genome.fasta -t repeats.sat

Testing

pytest tests/unit/ -v

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Citation

If you use Satellome in your research, please cite:

Komissarov A. et al. (2026). Satellome: A comprehensive tool for satellite DNA
analysis in T2T genome assemblies. [Publication details]

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: Wiki
• Email: ad3002@gmail.com

Acknowledgments

• FasTAN by Gene Myers
• Tandem Repeat Finder by Gary Benson
• T2T Consortium
• DNA Zoo
• Vertebrate Genome Project