REVERLOR

REpeat VERification using LOng Reads

A bioinformatic tool that finds exact and inexact interspersed repeats in genomic sequences via minimap2 self-alignment, then verifies whether those repeats are spanned by long reads from a BAM alignment file. If less than N reads span a repeat, it is considered unresolved.

---

Table of Contents

• Motivation
• Pipeline Overview
• Limitations
• Installation
• Usage
  • Quick Start
  • BAM File Preparation
  • Full Pipeline (reverlor)
  • Find Only (reverlor_find)
  • Verify Only (reverlor_verify)
• Options Reference
• Output Files
• Examples

---

Motivation

1. Accurate reconstruction of repeat regions (e.g., rRNA clusters, IS elements, prophages) is necessary for complete and contiguous genome assemblies.

2. Even long reads (Oxford Nanopore, PacBio) sometimes fail to span a repeat end-to-end.

3. A program that would find such repeats and verify them (check how many reads span them end-to-end) would be useful.

---

Pipeline Overview

Step 1: Repeat Finding (reverlor_find)

1. Self-align the reference FASTA using minimap2 (via mappy Python package).
2. Extract alignment coordinates as raw BED entries.
3. Merge overlapping/adjacent repeats.
4. Filter by minimum repeat length.
5. Output: repeats.bed.

Step 2: Repeat Verification (reverlor_verify)

1. Read repeat regions from the BED file created at Step 1.
2. For each repeat, compute “shoulder” coordinates (flanking regions upstream and downstream).
3. Use pysam to find long reads spanning from the upstream shoulder position to the downstream one.
4. If fewer than --span reads span the repeat, consider it unresolved.
5. Output: unresolved_repeats.bed.

---

Limitations

• Reverlor reports tandem repeats as a single repeat.

• Reverlor does not cluster repeat families.

• Option (-p/--min-pident) works in a very straightforward way. Given a hit reported by mappy, reverlor computes identity ratio as follows: hit.mlen / hit.blen (see mlen and blem definitions in mappy documentation). Although the method is rather intuitive, it might cause reverlor to miss some repeats. For example, suppose we have a repeat match with the following alignment structure:

|~~~~~ 100 bp, 98% pident ~~~~~|===== 100 bp, 100% pident =====|~~~~~ 100 bp, 98% pident ~~~~~|

Suppose then we set -p 99 and expect reverlor to find at least these middle exactly matching 100 bp. But in fact reverlor is likely to miss such repeat. The reason is that minimap2 will, surely, report the whole 300-bp alignment, but its percent of identity is below 99%, so reverlor will filter it out and will not report it.

---

Installation

Reverlor was tested using Python 3.12.3.

1. From PyPI

We recommend to install reverlor to a separate Python virtual environment.

1.1 Using uv

# Create a virtual environment in, for example, ./reverlor_venv directory
uv venv --python 3.12.3 ./reverlor_venv
# Activate the environment
source ./reverlor_venv/bin/activate
# Install
uv pip install reverlor

1.2 Using pip

# Create a virtual environment in, for example, ./reverlor_venv directory
python3 -m venv ./reverlor_venv
# Activate the environment
source ./reverlor_venv/bin/activate
# Install
pip install reverlor

2. From source

# Get source code
git clone git@github.com:masikol/reverlor.git # Or download a release archive from https://github.com/masikol/reverlor/releases
cd reverlor/
# Create a virtual environment
uv venv --python 3.12.3 ./reverlor_venv
# Activate the environment
source ./reverlor_venv/bin/activate
# Install the “build” package
uv pip install --upgrade build
# Build reverlor package. This will produce a ./dist directory
python3 -m build --installer uv
# Install reverlor (assuming its version is 1.0.0)
uv pip install dist/reverlor-1.0.0-py3-none-any.whl

# If you want to test your installation, install pytest
uv pip install pytest==8.4.2
# Test your installation
python3 -m pytest tests

---

Usage

Quick Start

# Full pipeline: find repeats + verify with long reads
reverlor genome.fasta reads.bam output_dir/

# With verbose output
reverlor -vv genome.fasta reads.bam output_dir/

# With custom parameters
reverlor \
    --min-repeat-len 127 \
    --span 10 \
    --threads 4 \
    genome.fasta reads.bam output_dir/

BAM File Preparation

For best performance, we strongly recommend to pass sorted and indexed BAM files to reverlor.

Here is a quick example on how to create such file:

minimap2 -a genome.fasta reads.fastq.gz \
    | samtools view -F 4 \
    | samtools sort -O BAM -o reads.sorted.bam

samtools index reads.sorted.bam

Full Pipeline (reverlor)

Runs both repeat finding and verification in sequence.

reverlor [options] <fasta> <input_bam> <output_dir>

Positional arguments:

Argument	Description
fasta	Path to input FASTA file (reference genome)
input_bam	Path to input BAM file (sorted, indexed long reads)
output_dir	Path to output directory

---

Find Only (reverlor_find)

Finds repeats without verification.

reverlor_find [options] <input_fasta> <output_dir>

Positional arguments:

Argument	Description
input_fasta	Path to input FASTA file
output_dir	Path to output directory

---

Verify Only (reverlor_verify)

Verifies pre-existing repeat predictions against a sorted and indexed BAM file.

reverlor_verify [options] <input_fasta> <input_bed> <input_bam> <output_dir>

Positional arguments:

Argument	Description
input_fasta	Path to input FASTA file
input_bed	Path to input BED file (repeat predictions)
input_bam	Path to sorted and indexed input BAM file
output_dir	Path to output directory

---

Options Reference

Common Options

Flag	Type	Default	Description
-V, --version	flag	--	Show version and exit
-v, --verbose	count	0	Verbosity level: -v (warnings), -vv (info), -vvv (debug)
-t, --threads	int	1	Number of CPU threads (passed to minimap2)
--keep-tmp	flag	False	Keep temporary files
--tmpdir	str	system	Temporary directory path

Repeat Finding Options

Flag	Type	Default	Description
-l/--min-repeat-len	int	200	Minimum repeat length to report
-i/--min-repeat-interval	int	100	Minimum interval between repeats (shorter ones get merged)
-p/--min-pident	float	0.0	Minimum alignment percent identity in the range [0.0, 100.0]
--inter-only	flag	False	Report only INTERreplicon matches, i.e. thouse between different input FASTA sequences
--intra-only	flag	False	Report only INTRAreplicon matches, i.e. thouse within the same input FASTA sequence
-k/--minimap-k	int	19	minimap2 k-mer length
-w/--minimap-w	int	19	minimap2 minimizer window size
-m/--minimap-m	int	65	minimap2 min chain score
--minimap-x	choice	None	minimap2 preset: map-ont, lr:hq, map-hifi, map-pb, map-iclr, asm5, asm10, asm20

Repeat Verification Options

Flag	Type	Default	Description
-s/--span	int	5	Minimum number os spanning reads to consider a repeat resolved
-u/--shoulder-len	int	200	Shoulder length (bp) for coordinate checking
--samtools-f	int	[]	samtools -f flag (includes segments having these flags, repeatable)
--samtools-F	int	[256]	samtools -F flag (excludes segments having these flags, repeatable)

Filter reads using SAM flags (--samtools-f, --samtools-F)

• These flags are applied at Step 2.3 (see the Pipeline Overview above).

• Default -F 256 excludes secondary alignments from verification.

• Add --samtools-F 2048 to also exclude supplementary alignments:

reverlor \
    --samtools-F 256 \
    --samtools-F 2048 \
    genome.fasta \
    reads.sorted.bam \
    output/dir/

• Add --samtools-f 16 to only include reverse-complementedly mapped reads.

reverlor \
    --samtools-F 256 \
    --samtools-f 16 \
    genome.fasta \
    reads.sorted.bam \
    output/dir/

---

Output Files

Reverlor outputs BED files.

In unresolved_repeats.bed, the 5th column holds the number of spanning reads.

Full Pipeline (reverlor)

File	Description
repeats.bed	Detected repeat regions
unresolved_repeats.bed	Repeats with insufficient spanning coverage

Find Only (reverlor_find)

File	Description
repeats.bed	Detected repeat regions

Verify Only (reverlor_verify)

File	Description
unresolved_reapeats.bed	Repeats with insufficient spanning coverage

---

Examples

Example 1: Basic usage on a bacterial genome

reverlor \
    genome.fasta \
    reads.sorted.bam \
    output_dir/

Example 2: Exclude secondary and supplementary alignments

reverlor \
    --samtools-F 256 \
    --samtools-F 2048 \
    genome.fasta \
    reads.sorted.bam \
    output_dir/

Example 3: Find repeats only, no verification (no BAM required)

reverlor_find \
    genome.fasta \
    output_dir/

Example 4: Verify existing repeat predictions (repeats.bed)

reverlor_verify \
    --span 10 \
    --shoulder-len 300 \
    genome.fasta \
    repeats.bed \
    reads.sorted.bam \
    output_dir/

Example 5: Debug mode with temporary files

reverlor \
    -vvv \
    --keep-tmp \
    --tmpdir /tmp/reverlor_debug \
    genome.fasta \
    reads.sorted.bam \
    output_dir/

Example 6: Full pipeline with verbose messages

reverlor \
    --min-repeat-len 200 \
    --min-repeat-interval 50 \
    --span 5 \
    --shoulder-len 200 \
    --samtools-F 256 \
    -t 8 \
    -vv \
    genome.fasta \
    reads.sorted.bam \
    output_full/