ModTector

ModTector is a high-performance RNA modification detection tool developed in Rust, supporting multi-signal analysis, data normalization, reactivity calculation, and accuracy assessment. Based on pileup analysis, it can detect RNA modification sites from BAM-format sequencing data and generate rich visualization results.

🚀 Key Features

• Multi-signal Analysis: Simultaneous analysis of stop signals (pipeline truncation) and mutation signals (base mutations)
• High-performance Pileup: Robust pileup traversal based on htslib, supporting large file processing
• Batch Processing: Process multiple BAM files sequentially with glob pattern matching
• Single-cell Unified Processing: Unified processing strategy for single-cell data with cell label extraction and splitting
• Data Distribution Optimization: Smart data distribution scanning for efficient processing
• Data Normalization: Signal validity filtering and outlier handling
• Reactivity Calculation: Calculate signal differences between modified and unmodified samples with multi-threading support
• Accuracy Assessment: AUC, F1-score and other metrics evaluation based on secondary structure with auto-shift correction
• Rich Visualization: Signal distribution plots, reactivity plots, ROC/PR curves, and RNA structure SVG plots
• Multi-threading: Parallel processing and plotting for improved efficiency
• Complete Workflow: One-stop solution from raw data to final evaluation
• Base Matching: Intelligent base matching algorithm handling T/U equivalence
• Auto-alignment: Auto-shift correction for sequence length differences

🔄 Complete Workflow

The following diagram shows the complete ModTector workflow from raw data to evaluation results:

ModTector provides a complete workflow from raw BAM data to final evaluation results:

1. Data Input: BAM files (modified/unmodified samples), FASTA reference sequences, secondary structure files
2. Statistical Analysis: Pileup traversal, counting stop and mutation signals
3. Reactivity Calculation: Calculate signal differences between modified and unmodified samples, generate reactivity data
4. Data Normalization: Normalize reactivity signals, signal filtering, outlier handling, background correction
5. Comparative Analysis: Compare modified vs unmodified samples, identify differential modification sites
6. Visualization: Generate signal distribution plots, reactivity plots, and RNA structure SVG plots
7. Accuracy Assessment: Performance evaluation based on secondary structure

🔧 Installation

System Requirements

• Operating System: Linux, macOS, or Windows
• Memory: 4 GB RAM (8 GB recommended for large datasets)
• Storage: 2 GB free space
• CPU: Multi-core processor recommended for parallel processing

Required Dependencies

• Rust: Version 1.70 or higher
• Cargo: Included with Rust installation

Installing Rust

Linux/macOS

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

Windows

Download and run the rustup installer from https://rustup.rs/

Installing ModTector

From crates.io (Recommended)

cargo install modtector

From Source

git clone https://github.com/TongZhou2017/ModTector.git
cd ModTector
cargo build --release

System Dependencies

ModTector requires the following system libraries:

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install build-essential pkg-config libssl-dev libhts-dev

Linux (CentOS/RHEL)

sudo yum groupinstall "Development Tools"
sudo yum install pkgconfig openssl-devel htslib-devel

macOS

xcode-select --install
brew install htslib

Rust Dependencies

ModTector uses the following Rust crates:

[dependencies]
rust-htslib = "0.47.0"    # BAM file processing
bio = "2.0.1"             # Bioinformatics utilities
plotters = { version = "0.3", features = ["svg_backend", "bitmap_backend"] }  # Plotting and visualization
csv = "1.3"               # CSV file handling
rayon = "1.8"             # Parallel processing
clap = { version = "4.5", features = ["derive"] }  # Command-line argument parsing
chrono = "0.4"            # Date and time handling
rand = "0.8"              # Random number generation
quick-xml = "0.36"        # XML/SVG parsing
regex = "1.11"            # Regular expressions

📋 Command Line Usage

Quick Start

# Generate pileup data from BAM files
modtector count -b sample.bam -f reference.fa -o output.csv

# Calculate reactivity scores
modtector reactivity -M mod_sample.csv -U unmod_sample.csv -O reactivity.csv
# (Optional) For workflows without an unmodified control, omit -U to run in mod-only mode
# modtector reactivity -M smartshape_mod.csv -O reactivity.csv

# Normalize reactivity signals
modtector norm -i reactivity.csv -o normalized_reactivity.csv -m winsor90

# Compare samples and identify differences
modtector compare -m mod_sample.csv -u unmod_sample.csv -o comparison.csv

# Generate visualizations
modtector plot -M mod_sample.csv -U unmod_sample.csv -o plots/ -r normalized_reactivity.csv

# Generate RNA structure SVG plots
modtector plot -o svg_output/ --svg-template rna_structure.svg --reactivity normalized_reactivity.csv

# Evaluate accuracy
modtector evaluate -r normalized_reactivity.csv -s structure.dp -o results/ -g gene_id

1. Count - Data Processing

Generate pileup data from BAM files by counting stop and mutation signals.

modtector count [OPTIONS] --bam <BAM> --fasta <FASTA> --output <OUTPUT>

Parameters: - -b, --bam: Input BAM file path (must be sorted and indexed), or glob pattern for batch/single-cell mode - -f, --fasta: Reference FASTA file path - -o, --output: Output CSV file path (or directory for batch/single-cell mode) - -s, --strand: Optional strand filter (+, -, or +/-; default +/-) - -t, --threads: Number of parallel threads (default: 1) - -w, --window: Window size for genome segmentation in bases (optional) - -l, --log: Log file path (optional) - --batch: Enable batch mode for sequential file processing (use glob pattern) - --single-cell: Enable single-cell unified processing mode (use glob pattern, unified processing with cell labels)

Input File Requirements: - BAM files: Must be sorted and indexed. Use samtools for sorting and indexing: bash samtools sort input.bam -o sorted.bam samtools index sorted.bam - FASTA files: Reference genome sequence file, sequence IDs must match chromosome names in BAM file

Example:

# Standard mode: process single BAM file
modtector count \
  -b data/mod_sample.bam \
  -f data/reference.fa \
  -o result/mod.csv \
  -t 8

# Batch mode: process multiple BAM files sequentially
modtector count --batch \
  -b "/path/to/bam/*sort.bam" \
  -f data/reference.fa \
  -o result/batch_output/ \
  -t 8 \
  -w 10000

# Single-cell unified mode: unified processing with cell labels
modtector count --single-cell \
  -b "/path/to/single_cell/*sort.bam" \
  -f data/reference.fa \
  -o result/single_cell_output/ \
  -t 8 \
  -w 10000

Batch and Single-cell Modes: - Batch mode (--batch): Processes multiple BAM files sequentially, each file independently. Suitable for scenarios where files need separate processing. - Single-cell unified mode (--single-cell): True unified processing strategy that: - Reads all BAM files at once for each window - Collects all reads from all files, unified pileup processing - Tracks cell labels during processing, splits results by cell - Provides 2-3x performance improvement by: - Skipping data distribution scanning (direct processing of all reference sequences) - Unified read collection and pileup (reduces I/O overhead) - Better parallelization efficiency (cross-file parallel processing) - Window-based memory management (prevents memory accumulation)

Cell Label Extraction: - Automatically extracts cell labels from BAM filenames - Supports RHX pattern (e.g., *RHX672.sort.bam → RHX672) - Falls back to last underscore-separated part if RHX not found - Example: in_vivo_single_cell_Mut_transfected_RNAs_in_HEK293T_DMSO_RHX672.sort.bam → RHX672

Progress Reporting: - Real-time progress display: chunks processed, percentage, processing speed - Estimated time remaining (ETA) based on current processing speed - CPU usage recommendations based on BAM file count - Automatic suggestions for optimal thread count

Output Format (CSV):

ChrID,Strand,Position,RefBase,StopCount,MutationCount,Depth,InsertionCount,DeletionCount,BaseA,BaseC,BaseG,BaseT

2. Reactivity - Reactivity Calculation

Calculate reactivity scores by comparing modified and unmodified samples.

modtector reactivity [OPTIONS] --mod-csv <MOD_CSV> --unmod-csv <UNMOD_CSV> --output <OUTPUT>

Parameters: - -M, --mod-csv: Modified sample CSV - -U, --unmod-csv: Unmodified sample CSV (optional, omit for mod-only mode) - -O, --output: Output reactivity file - -s, --stop-method: Stop signal method (kfactor, ding, rouskin; default: kfactor) - -m, --mutation-method: Mutation signal method (kfactor, siegfried, zubradt; default: kfactor) - -t, --threads: Number of parallel threads (default: 8) - --pseudocount: Pseudocount parameter for Ding method (default: 1.0) - --maxscore: Maximum score limit for Ding method (default: 10.0) - --snp-cutoff: SNP threshold for filtering positions (default: 0.25) - --k-prediction-method: K-factor prediction method (background, distribution, recursive; default: background) - --structure-file: Reference secondary structure file (required for recursive method) - --k-background-gene-id: Gene ID for k-factor background region selection

Stop Signal Methods: - kfactor: k-factor correction method (default) - ding: Ding et al., 2014 logarithmic processing method - rouskin: Uses only modified sample stop signal

Mutation Signal Methods: - kfactor: k-factor correction method (default) - siegfried: Siegfried method for mutation signal processing - zubradt: Uses only modified sample mutation signal

Example:

# Using default method
modtector reactivity \
  -M result/mod.csv \
  -U result/unmod.csv \
  -O result/reactivity.csv \
  -t 24

# Using Ding method for stop signal
modtector reactivity \
  -M result/mod.csv \
  -U result/unmod.csv \
  -O result/reactivity.csv \
  -t 24 \
  -s ding \
  --pseudocount 1.0 \
  --maxscore 10.0

Output Format (CSV):

ChrID,Strand,Position,RefBase,Reactivity

3. Norm - Data Normalization

Normalize and filter signals to remove noise and outliers.

modtector norm [OPTIONS] --input <INPUT> --output <OUTPUT>

Parameters: - -i, --input: Input reactivity CSV file (output from modtector reactivity) - -o, --output: Output normalized CSV file - -m, --method: Normalization method (winsor90, percentile28, boxplot) - --bases: Target bases for analysis (e.g., AC for A and C bases) - --coverage-threshold: Coverage threshold (default: 0.2) - --depth-threshold: Depth threshold (default: 50) - --linear: Apply Zarringhalam piecewise linear mapping

Example:

modtector norm \
  -i result/reactivity.csv \
  -o result/reactivity_norm.csv \
  -m winsor90 \
  --bases AC \
  --coverage-threshold 0.2 \
  --depth-threshold 50

4. Compare - Sample Comparison

Compare modified and unmodified samples to identify differential modification sites.

modtector compare [OPTIONS] --mod-csv <MOD_CSV> --unmod-csv <UNMOD_CSV> --output <OUTPUT>

Parameters: - -m, --mod-csv: Modified sample CSV - -u, --unmod-csv: Unmodified sample CSV - -o, --output: Output comparison CSV file - --min-depth: Minimum depth threshold (default: 10) - --min-fold: Minimum fold change threshold (default: 2.0)

Example:

modtector compare \
  -m result/mod.csv \
  -u result/unmod.csv \
  -o result/comparison.csv \
  --min-depth 10 \
  --min-fold 2.0

Output Format (CSV):

ChrID,Strand,Position,RefBase,ModStop,ModMutation,ModDepth,UnmodStop,UnmodMutation,UnmodDepth,StopFoldChange,MutationFoldChange,ModificationScore

5. Plot - Visualization

Generate visualization plots including signal distributions and RNA structure SVG plots.

modtector plot [OPTIONS] --mod-csv <MOD_CSV> --unmod-csv <UNMOD_CSV> --output <OUTPUT>

Parameters: - -M, --mod-csv: Modified sample CSV (optional for SVG-only mode) - -U, --unmod-csv: Unmodified sample CSV (optional for SVG-only mode) - -o, --output: Output directory - -r, --reactivity: Reactivity file (optional) - -t, --threads: Number of parallel threads (default: 8) - --coverage-threshold: Coverage threshold (default: 0.2) - --depth-threshold: Depth threshold (default: 50)

SVG Plotting Options: - --svg-template: SVG template file path - --svg-bases: Bases to plot (default: ATGC) - --svg-signal: Signal type to plot (stop, mutation, all) - --svg-strand: Strand to include (+, -, both) - --svg-ref: Reference sequence file for alignment - --svg-max-shift: Maximum shift for alignment (default: 50)

Example:

# Regular plotting
modtector plot \
  -M result/mod.csv \
  -U result/unmod.csv \
  -o result/plots \
  -r result/reactivity.csv \
  -t 8

# SVG-only mode
modtector plot \
  -o svg_output/ \
  --svg-template rna_structure.svg \
  --reactivity result/reactivity.csv \
  --svg-signal all \
  --svg-strand +

# Combined mode (regular + SVG)
modtector plot \
  -M result/mod.csv \
  -U result/unmod.csv \
  -o result/plots \
  --svg-template rna_structure.svg \
  --reactivity result/reactivity.csv

6. Evaluate - Accuracy Assessment

Evaluate the accuracy of results using known secondary structure.

```