RepeatSum

Version: 1.0.0

Author: Muhammad Salman

A small command-line tool to summarize RepeatMasker .out annotations into genome-wide and per-chromosome tables, at both the repeat class level (e.g. LINE, DNA, LTR) and the class/family level (e.g. LINE/L1, DNA/hAT-Charlie).

What it does

1. Computes genome size and per-chromosome lengths from the input FASTA.
2. Parses every hit from the RepeatMasker .out file.
3. Resolves overlapping hits base-by-base: at every genomic position, whichever hit has the highest alignment score there is the one counted. A hit that partially overlaps a higher-scoring neighbour only loses the overlapping bases, not its whole footprint.
4. Writes four CSV summary tables (see Output below).

Requirements

• Python ≥ 3.8
• Python packages: pandas, numpy (installed automatically with pandas), biopython
• Optional: pyfaidx — if installed, genome size is computed via a FASTA index instead of loading the whole file into memory (recommended for large or highly fragmented assemblies)

Installation

git clone https://github.com/salmanento/RepeatSum.git
cd RepeatSum
pip install pandas numpy biopython pyfaidx

Usage

python repeat_summary.py -f genome.fasta -r genome.fasta.out -o results/

A run looks like this:

############################################################
#                     RepeatSum v1.0.0                     #
#----------------------------------------------------------#
#                A simple tool to summarize                #
#                   RepeatMasker output                    #
#                 Author: Muhammad Salman                  #
############################################################

[1/3] Computing genome size from genome.fasta ...
      Genome size: 2,311,343,447 bp (1,234 sequences)
[2/3] Parsing genome.fasta.out ...
      842,113 hits parsed across 1,234 sequences
[3/3] Resolving overlaps and writing summary tables ...

Summary
-------
Genome size:                 2,311,343,447 bp
Total masked (non-overlap.): 1,069,066,708 bp
Genome masked:               46.25 %

For details, view output files.

Output files written to: results/
  - summary.txt
  - repeat_class_summary.csv
  - repeat_classfamily_summary.csv
  - chromosome_class_summary.csv
  - chromosome_classfamily_summary.csv

RepeatSum finished. Repeat landscape summarized successfully.

Options

Short	Long	Description	Default
-f	--fasta	Genome FASTA file (required)	—
-r	--rmout	RepeatMasker .out file (required)	—
-o	--output	Output directory (created if it doesn't exist)	.
-h	--help	Show help message and exit	—
-v	--version	Show version and exit	—

Example

python repeat_summary.py -f genome.fasta \
                          -r genome.fasta.out \
                          -o repeat_summary_results/

Input format

The script expects a standard RepeatMasker .out file: 3 header lines followed by whitespace-delimited columns, where (1-indexed) column 1 is the Smith-Waterman alignment score, column 5 is the sequence/chromosome name, columns 6–7 are the start/end coordinates, and column 11 is the Class/Family string (e.g. LINE/L1). Files in another format (GFF, cross_match native output, etc.) will not parse correctly and the script will exit with an error if no records are found.

Output

Written to the directory given by -o/--output:

File	Description
summary.txt	Plain-text run summary (genome size, total masked bp/%, list of other output files)
repeat_class_summary.csv	Genome-wide bp and % masked, by repeat class
repeat_classfamily_summary.csv	Genome-wide bp and % masked, by repeat class/family
chromosome_class_summary.csv	Per-chromosome bp masked, by repeat class
chromosome_classfamily_summary.csv	Per-chromosome bp masked, by repeat class/family

Genome-wide CSV columns

Column	Meaning
Class / Class_Family	Repeat type
Counts	Copy number of that repeat type genome-wide — the number of distinct insertions found. Fragments of one interrupted repeat (reported by RepeatMasker as separate rows sharing the same internal ID) are merged and counted as a single copy.
Masked_bp	Total bp attributed to this type, genome-wide
Genome_percent	Masked_bp as % of total genome size

Per-chromosome CSV columns

Each repeat type gets its own bp column, followed by:

Column	Meaning
Total_bp	Total bp masked on that chromosome/scaffold (all repeat types combined)
Total_percent	Total_bp as % of that chromosome/scaffold's own length
Repeat_share_pct	Total_bp as % of the genome-wide total repeat content — this chromosome's share of all repeats found across the whole genome. Sums to 100% across all rows.

Caveats

• Overlap resolution is score-based and per-base: at every genomic position, the hit with the highest Smith-Waterman (SW) alignment score is the one counted.
• If a chromosome name in the .out file doesn't match any sequence in the FASTA, the script estimates that chromosome's length from its rightmost hit and prints a warning — worth checking your .out and FASTA use identical sequence names.

License

MIT — see LICENSE.

Citation

If you find this tool useful, please consider citing:

Salman M. "RepeatSum." GitHub, 2026, https://github.com/salmanento/RepeatSum. Accessed 15 July 2026.

(Update the "Accessed" date to the day you actually access/use the repository.)