Welcome to Readzor

Readzor is a fast, modular, fully-featured FASTQ quality trimming and filtering pipeline.
All processing modules are off by default, giving you full control over your workflow.

Feature overview

Modular trimming approach: By design, each filter will indepedently assess each raw read. Outcomes are merged, and the most stringent trimming result per end is applied.
For example, if the quality trimmer determines 5 bases should be removed from the 3' end, but the adapter trimmer identifies 12 bases to remove from that same end, Readzor will merge these outcomes and trim the most restrictive amount (12 bases) to ensure high-quality output.

• Quality-dependent end trimming.
• Sliding window quality trimming.
• Homopolymer trimming, from both read ends.
• Adapter trimming with built-in TruSeq, Nextera, and Illumina RNA-seq adapters.
• N-base trimming from both read ends, and overall N-base filtering.
• K-mer based low complexity filtering.
• Set-length read end trimming.
• Average output quality threshold.
• Overall length thresholds.

Auto-detection: Using auto-detection methods, Readzor provides an easy-to-use platform for novice users, enabling high quality read trimming with minimal inputs.

• File Pairing: paired vs. unpaired vs. interleaved FASTQ files detection using internal header information, independent of file names.
• Read Numbering: read numbers detection when needed, directly from headers.
• Compression: Gzip compression detection via magic bytes, regardless of the file extension.
• Phred Offsets: per-file Phred quality offsets detection (i.e., Phred33 vs. Phred64) based on quality string symbols.

Extra features: Equipped with a number of other features, like built-in validation and seamless HPC cluster detection methods, Readzor delivers a robust execution environment, ensuring reproducible outputs at any scale.

• Fully automatic mode: invoking Readzor in fully automatic mode (optional file specification possible), will use predetermined settings to optimize read processing. For more info, invoke Readzor with flags --full-auto and --help.
• MGI/BGI header conversion: Built-in module to convert MGI/BGI fastq headers into standard Illumina format for downstream compatibility (e.g., with SAMtools).
• Safe and traceable outputs: Automatically generates isolated, timestamped output directories to prevent accidental file overwrites. Each run includes a comprehensive summary file detailing the exact parameters used and the final trimming outcomes for full reproducibility.
• HPC integration: Automatically reads HPC cluster environment variables to seamlessly scale threads and optimize performance on HPC clusters.
• Live progress monitoring: Features a dynamic progress tracker to accurately provide real-time feedback on processing speed, completion, and estimated time remaining.
• Real-time record validation: Readzor detects malformed or corrupted FASTQ records on the fly, ensuring high-quality output.
• Gzip compression: Compress your output files and control the compression depth to optimize storage size.
• Test run: Perform a short test run according to specified settings, printing verbose output to screen, to catch config errors before committing to a full run.

Input data requirements

• Readzor can handle a mix of gzipped or normal text files as input simultaneously, different file types will be handled dynamically.
• For auto-detection of FASTQ files, the files should either in either fastq/fq (when in text) or gzip/gz (when gzipped).
• Additional adapter sequences should be specified as a fasta file.

Installation and testing

Installation of Readzor is made easy through pip and conda, but you can also clone this repository:

Bioconda

conda search readzor
conda install readzor
readzor --version

Docker

docker pull ghcr.io/abjanssen/readzor:latest
docker run --rm ghcr.io/abjanssen/readzor:latest --version

Github

git clone https://github.com/abjanssen/Readzor.git
pip install numpy==2.5.2
pip install isal==1.8.0
cd Readzor/src/readzor
chmod u+x readzor.py
python readzor.py --version

Pip

pip install readzor
import readzor
print(readzor.VERSION)

Using Readzor

Beginner

# Use predetermined settings, and let Readzor detect the files (and their pairing) in your current working directory:
% Readzor -GO

Beginner+

# Use predetermined settings, but specify your files

# Use on Readzor's paired-filed detection:
% Readzor -GO --input-files /path/to/input/files

# Specify paired files:
% Readzor -GO --input-paired /path/to/paired/files

# Specify unpaired files:
% Readzor -GO --input-unpaired /path/to/unpaired/files

# Specify a combination: 
% Readzor -GO --input-unpaired /path/to/unpaired/files --input-paired /path/to/paired/files

Novice

# Adapt the workflow according to your needs by specifying specific trimming modules

# Turn on quality-dependent end trimming, use its default settings:
% Readzor --input-files /path/to/input/files --endqual-filter-flag

# Turn on adapter trimming, use its default settings:
% Readzor --input-files /path/to/input/files --adapter-filter-flag

# Turn on multiple trimming modules:
% Readzor --input-files /path/to/input/files --adapter-filter-flag --endqual-filter-flag

Advanced

# Detail the module settings according to your needs by specifying trimming parameters

# Turn on quality-dependent end trimming, use custom settings:
% Readzor --input-files /path/to/input/files --endqual-filter-flag --endqual-min-start 25 --endqual-min-end 25

# Turn on adapter trimming, add custom sequences:
% Readzor --input-files /path/to/input/files --adapter-filter-flag --adapter-fasta-add /path/to/fasta/file

Command line options

All modules are off by default. To use a module, specify a module flag. Further specifications with module settings possible.

General settings

--help, -h [FLAG]: Show this help message and exit. Combine with --full-auto/-GO for more information on fully automatic mode. Combine with --adapter-filter-flag/-af for more information on built-in adapter sequences.
--version, -v [FLAG]: Show Readzor version and exit.
--full-auto, -GO [FLAG]: Run Readzor in fully automatic mode. Combine with --help/-h for more information on fully automatic mode.
--progress [FLAG]: Show a live progress bar and estimated time remaining during processing, based on estimated read counts. Default: off.
--list-adapters [FLAG]: Show all built-in adapter sequences and exit.
--verbose [FLAG] Write verbose output to terminal, in addition to the log file. Default: off.

Input options

Specify input FASTQ files using any combination of --input-files, --input-paired, --input-unpaired, and --input-interleaved. Lists with any combination of regular (fastq/fq) and gzipped (fastq.gz/fq.gz) files accepted. If no input flags are provided, data will be read directly from standard input (stdin)."
--input-files, -i: FASTQ files of unspecified pairing. Paired, in terleaved, unpaired files will be auto-detected.
--input-interleaved, -ii: Interleaved FASTQ files. Note: these files will be split in forward and reverse reads.
--input-paired, -ip : Paired-end FASTQ files, given as one or more R1/R2 pairs, e.g. --input-paired sample1_R1 sample1_R2 sample2_R1 sample2_R2.
--input-unpaired, -iu: Unpaired FASTQ files.

Output options

--gzip [FLAG]: Compress filtered FASTQ files in gzip format using isal. Default: off.
--gzip-level: Set gzip compression level. Higher compression decreases processing speed. Possible values: 0-3. Default: 1.
--interleaved-out: Interleave surviving FASTQ reads of paired and interleaved input files, resulting in one output file.
--output, -o: Path to directory in which the timestamped results folder will be created. Default: current working directory.
--stdout: Stream resulting FASTQ reads to stdout. Forces --interleaved-out for paired and interleaved files. Overrides --verbose, --progress, and --write-rejected to off. Overridden to 'off' by --gzip. Note: all files will be streamed on end, without any seperators.
--write-rejected: Write rejected reads to file. Either one (for unpaired and when --interleaved-out is set), or two (for forward and reverse reads) are produced. Overridden to 'off' when --stdout is set. Default: off.
--discard-singles: Discard single leftover reads. For paired and interleaved reads, single surviving reads will be discarded instead of written to a seperate file. No effect on unpaired read filtering. Default: off.\

General quality filters

--min-average-qual-pre <int>: Minimum average quality of input read. Default: 0.
--min-average-qual-post <int>: Minimum average quality of output read. Default: 0.
--min-length-input <int>: Minimum length for input read. Default: off.
--max-length-input <int>: Maximum length for input read. Default: off.
--min-length-output <int>: Minimum length of output read in absolute number of nucleotides. Overrides --min-length-output-perc when both set. Default: 0.
--min-length-output-perc <float>: Minimum length of output read as percentage of input read. Overridden by --min-length-output when both set. Default: 0.
--max-length-output <int>: Maximum length of output read in absolute number of nucleotides. Overrides --max-length-output-perc when both set. Default: off.
--max-length-output-perc <float>: Maximum length of output read as percentage of input read. Overridden by --max-length-output when both set. Default: off.
--n-filter [FLAG]: Reject reads containing N bases anywhere in read. Default: off.

Set-Length end trimming

Trim a set number of bases of the ends of each read, independent of sequence or quality.
--cut-flag, -cf [FLAG]: Turn on the set-length end trimming module. Default: off.
--cut-start, -cs <int>: Number of bases to trim from the start of the read. Default: 0.
--cut-end, -ce <int>: Number of bases to trim from the end of the read. Default: 0.
--cut-both, -cb <int>: Number of bases to trim from both ends of the read. Overwritten by --cut-start and --cut-end. Default: 0.

Quality-dependent end trimming

Trim the ends of each read, dependent on quality. Ends of reads will be trimmed up to first position that fulfills quality requirement.
--endqual-filter-flag, -ef: [FLAG] Turn on quality-dependent end trimming. Default: off.
--endqual-min-start, -ems: Specific phred score threshold for the start of the read. Default: 25.
--endqual-min-end, -eme: Specific phred score threshold for the end of the read. Default: 25.
--endqual-min-both, -emb: Phred score threshold for the quality trimming of read ends. Overwritten by --endqual-min-start and --endqual-min-end. Default: 25.

N-Nucleotide end trimming

Trim the ends of each read for N bases. Redundant when --n-filter is set.
--n-trimming-flag, -ntf: [FLAG]: Turn on the N nucleotide end trimming module. Default: off.

Sliding window quality trimming

Trim the reads for quality based on a sliding window of size X, moved with stepsize Y. Longest portion survives in case of mid-read quality dropoff.
--slider-filter-flag, -sf: [FLAG] Turn on sliding window quality trimming module. Default: off.
--slider-window, -sw: Window size over which average quality is calculated. Default: 5.
--slider-quality, -sq: Minimum average quality in sliding window. Default: 20.
--slider-step, -ss: Sliding window step size. Default: 1.

Homopolymer nucleotide trimming

Illumina NovaSeq, NextSeq, and MiniSeq use a two-color chemistry, in which guanine bases are unlabeled. In event of short fragments, this can result in homolopolymer G calls at the end of reads.
--poly-filter-flag, -pf: [FLAG] Turn on homopolymer read-end trimming module. Default: off.
--poly-bases-start, -pbs: Base(s) to check for a homopolymer run at start of read. Comma-separated bases are checked independently. Default: none.
--poly-bases-end, -pbe: Base(s) to check for a homopolymer run at end of read. Comma-separated bases are checked independently. Default: "G".
--poly-bases-both, -pbb: Base(s) to check for a homopolymer run at both read ends. Comma-separated bases are checked independently. Overwritten by poly_bases_start and poly_bases_end. Default: none.
--poly-length-start, -pls: Minimum length of homopolymer run at start of read required to trigger trimming. Default: 10.
--poly-length-end, -ple: Minimum length of homopolymer run at end of read required to trigger trimming. Default: 10.
--poly-length-both, -plb: Minimum length of homopolymer run at start and end of read required to trigger trimming. Default: 0.

Adapter trimming

Trim reads for Illumina adapter sequences. Standard sequences included are TruSeq3 universal and index adapters, and Nextera adapters. Only exactly matching sequences are trimmed. Adapter trimming is performed independent of quality.
--adapter-filter-flag, -af: [FLAG] Turn on adapter trimming module. Default: off.
--adapter-group, -ag: Specify the group(s) of adapters to be used. Ignored if --adapter-fasta-excl is set. Choices: Illumina_RNA, Nextera, TruSeq2, TruSeq3, TruSeq_small_RNA. Default: Nextera.
--adapter-mismatch, -am: Number of mismatches allowed in adapter finding. Default: 0.
--adapter-fasta-add, -ad: FASTA file with adapter sequences to trim for, in addition to defined sequences from --adapter-group.
--adapter-fasta-excl, -ax: Fasta file with adapter sequences to trim for, excluding predefined and additional sequences specified.

Low complexity filtering

Detect complexity of reads using k-mer-based nucleotide frequencies. Low complexity reads are discarded entirely.
--kmer-filter-flag, -kf: [FLAG] Turn on the k-mer-based complexity filtering module. Default: off.
--kmer-size, -ks: K-mer length for k-mer-based complexity filtering. Comma-separated values are checked independently. Default: 4.
--kmer-cutoff, -kc: Minimum percentage of unique k-mers (relative to the maximum possible for the read) required to pass the complexity filter. Higher values are stricter. Default: 50.

MGI header conversion

Convert read header from MGI (BGI) format to Illumina format. Original header will be discarded.
--mgi-convert-flag, -mf: [FLAG] Turn on the MGI-to-Illumina header conversion module. Default: off.
--mgi-bc5, -m5: Input an i5 barcode for Illumina header conversion. Default: 'PLACEHOLDERi5'.
--mgi-bc7, -m7: Input an i7 barcode for Illumina header conversion. Default: 'PLACEHOLDERi7'.
--mgi-instrument, -mi: Instrument name for Illumina header conversion. Default: 'PLACEHOLDERinstrument'.
--mgi-run, -mr: Run ID for Illumina header conversion. Default: 'PLACEHOLDERrun'.

Advanced options

Further options that can be specified to alter the behavior of Readzor.
--threads, -t: Number of threads to use. Default: platform-dependent through auto-detection (assigned CPUs on HPC cluster systems, all-1 otherwise. Fallback: 1).
--reads-for-phred-offset: Number of reads to sample per file for detection of Phred quality encoding offset. Default: 500.
--chunk-size: Number of reads per chunk sent to each worker. Default: platform-dependent (empirically set to 20,000 for HPC cluster systems, 1000 otherwise). Changing can alter processing speed
--phred-offset: Define phred offset for all FASTQ files. When set, per-file auto-detection will not be performed. Possible values: 33, 64. Default: off (auto-detection per file).
--testrun: [FLAG] Perform a limited test run according to specified settings. Also sets --verbose. Default: off.
--ordered-output: [FLAG] Force writing output reads in the same order as the input reads, with the exception of filtered reads. Default: off.
--phred-out: Convert Phred encoding from 33 to 64, and vice versa. Possible values: 33, 64. Default: off. \

Software version

Readzor depends on the following software packages:

• NumPy (version required: 2.5.2)
• Python (no version requirement)
• Python-isal (version required: 1.8.0)

Although Readzor works on older versions of Python, it has been developed and tested for best performance using version 3.14.7:

Issues and bug reports

Please leave a message in issues or discussions if you notice an issue, bug, or otherwise.

License

This project is provded under the GNU General Public License v3.0 (GPLv3).

Author

Axel B. Janssen (Google Scholar/GitHub)

Reference

Please use the DOI (https://doi.org/10.5281/zenodo.22336649) for your references.

Performance benchmarking

Readzor will soon be benchmarked against other read sequencing trimmers.

Legal

The oligonucleotide sequences used for adapter trimming, included in this work, are copyrighted and protected by intellectual property, including issued or pending patents, copyright, and trade secrets.
Oligonucleotide sequences © 2026 Illumina, Inc. All rights reserved.