MotifScan

Streaming, low-memory motif scanning CLI in Rust

Exact matching for FASTA and FASTQ reads, with optional reverse-complement scanning, CSV motif tables, read-level hit reports, and Aho-Corasick acceleration for larger motif sets.

MotifScan is a streaming, low-memory, multi-threaded Rust CLI for exact motif scanning in FASTA and FASTQ reads.

Dependency

• Rust toolchain for building from source

Installation

Build from source with the Rust toolchain:

git clone https://github.com/jiehua1995/MotifScan
cd MotifScan
cargo build --release

Binary path:

./target/release/motifscan

Install directly from crates.io:

cargo install motifscan

Crates.io page: https://crates.io/crates/motifscan

Version information:

motifscan -v
motifscan --version

Quick Start

Multiple motifs:

motifscan count \
  -i reads.fastq \
  --motifs motifs.csv \
  --revcomp \
  -o count.csv

Single motif:

motifscan count \
  -i reads.fa \
  --motif ATTATGAGAATAGTGTG \
  --motif-name motif1 \
  -o count.csv

Read-level hits:

motifscan count \
  -i reads.fastq \
  --motifs motifs.csv \
  --report-read-hits read_hits.csv \
  -o count.csv

Logging: control logging via the RUST_LOG environment variable or the environment filter; no per-command --debug flag is available.

motifscan Count Options

Option	Default	Description	Notes
-i, --input	required	Input reads file (FASTA/FASTQ or gz)	Use single -i followed by file
-o, --output	required	Output CSV path	Summary CSV; first column is motif
-t, --threads	auto	Number of worker threads	0 means auto-select
--progress	false	Show progress bar on stderr	Useful for long runs
--motif	-	Single motif sequence	Mutually exclusive with --motifs
--motifs	-	Two-column CSV of motifs	name,sequence
--motif-name	motif	Name used with --motif	Only valid when --motif is provided
--revcomp	false	Also scan reverse complements	When set, reverse strand matches counted separately

Motif CSV Format

name,sequence
motif1,ATTATGAGAATAGTGTG
motif2,TTCATTCATGGTGGCAGTAAAATGTTTATTGTG
motif3,ATGAA

Output CSV Columns

Summary:

motif,sequence,length,reads_with_hit,total_hits,forward_hits,revcomp_hits

Read hits:

read_id,motif,strand,position,matched_sequence

Notes

• Input sequences are normalized to uppercase before matching.
• Overlapping hits are counted.
• Palindromic motifs are not double-counted in reverse-complement mode.
• If a motif is longer than a read, that read is skipped for that motif.
• FASTQ input is parsed as standard four-line records.
• The scanner currently supports exact matching only.

Citation

Just mention this repository or cite like:

@software{motifscan,
  author = {jiehua1995},
  title = {MotifScan},
  url = {https://github.com/jiehua1995/MotifScan},
  version = {0.1.7}
}

Releases

If you do not want to build from source, you can download a prebuilt artifact from GitHub Releases generated by CI. Local builds are still recommended because they are the best way to ensure the binary matches your environment.