Krewlyzer: Comprehensive cfDNA Feature Extraction Toolkit

Krewlyzer is a high-performance toolkit for extracting biological features from cell-free DNA (cfDNA) sequencing data. Designed for cancer genomics, liquid biopsy research, and clinical bioinformatics.

Built with Python + Rust for maximum performance. The compute-intensive core uses PyO3 to deliver 5-50x speedups over pure Python.

[!TIP] Full Documentation: msk-access.github.io/krewlyzer

Why Krewlyzer?

Cancer cells leave molecular fingerprints in your blood. Krewlyzer finds them.

The Fragmentomics Advantage

Key insight: Tumor DNA fragments are shorter (~145bp) than healthy DNA (~166bp). Krewlyzer quantifies this difference and extracts ML-ready features.

What You Get

New to cfDNA? Read Core Concepts for background.

Quick Install

# Docker (recommended - all data bundled)
docker pull ghcr.io/msk-access/krewlyzer:latest

# Clone + Install (development)
git clone https://github.com/msk-access/krewlyzer.git && cd krewlyzer
git lfs pull && pip install -e .

# pip + Data Clone (custom environments)
pip install krewlyzer
git clone --depth 1 https://github.com/msk-access/krewlyzer.git ~/.krewlyzer-data
cd ~/.krewlyzer-data && git lfs pull
export KREWLYZER_DATA_DIR=~/.krewlyzer-data/src/krewlyzer/data

[!NOTE] pip users: The KREWLYZER_DATA_DIR env var is required to locate bundled assets. See Installation Guide for details.

Quick Start

# Run all fragmentomics features
krewlyzer run-all -i sample.bam --reference hg19.fa --output results/

# Generate unified JSON for ML pipelines
krewlyzer run-all -i sample.bam --reference hg19.fa --output results/ --generate-json

# Individual tools
krewlyzer extract -i sample.bam -r hg19.fa -o output/
krewlyzer fsc -i output/sample.bed.gz -o output/

# Panel data (MSK-ACCESS) with target regions
krewlyzer run-all -i sample.bam -r hg19.fa -o results/ \
    --target-regions panel_targets.bed \
    --pon-model msk-access.pon.parquet

Features

Pass --output-format parquet to any of them, or --generate-json to run-all for a single .features.json for ML pipelines.

Inspecting and Validating

These read inputs or a finished output directory rather than producing features.

krewlyzer validate -G hg19                        # assets are intact
krewlyzer validate-pon model.pon.parquet          # the reference is sound
krewlyzer validate-output results/                # results satisfy the contract
krewlyzer describe-output results/{sample_id}/    # what is in each file

# HTML output needs the rendering extras; without them describe-output writes
# the Markdown source into the page and says so.
pip install 'krewlyzer[all]'                      # or [report] for just these
krewlyzer describe-output results/{sample_id}/ -o page.html
krewlyzer report results/{sample_id}/ -o report.html

Extras. [all] is every optional capability of the tool — today [report] (HTML rendering and charts) plus psutil for sharper memory detection. It deliberately excludes [docs], [test] and [dev], which are contributor tooling: installing the tool should not deliver a linter.

[!NOTE] A report contains one sample's actual measurements — generate it on demand for internal use, and use describe-output for anything structural that needs to leave the machine. See the CLI reference for exit codes and options.

Upgrading to 0.9.0 — your own PON will be refused

The bundled PONs were rebuilt for 0.9.0, not just re-stamped. A PON you built yourself with an earlier version is refused rather than scored against:

my.pon.parquet was built for krewlyzer 0.8.3, older than the 0.9.0 floor.
Version 0.9.0 changed what the features mean, so its baselines measure
something else -- a fabricated wps_background, floored sigmas, and a
region-MDS fitted over a different fragment range. Rebuild it with
build-pon. To score against it anyway, set KREWLYZER_ALLOW_OLD_PON=1.

Every pre-0.9.0 model divided some z-scores by a σ of ~10⁻¹⁷ — floating-point residue left where a position had no real spread, not a measurement. Rebuild instead of overriding:

# Minutes, not hours: re-aggregates existing run-all outputs, no BAM re-read
krewlyzer build-pon --from-outputs /path/to/runall_dirs \
    --assay xs1 --genome hg19 -o new.pon.parquet
krewlyzer validate-pon new.pon.parquet

[!WARNING] KREWLYZER_ALLOW_OLD_PON=1 exists for reproducing an old analysis, not for getting past the error. Z-scores from an old model may be divided by residue, which produces values in the 10¹⁸ range that still look like numbers.

Panel Mode (--target-regions)

For targeted sequencing panels (MSK-ACCESS):

krewlyzer run-all -i sample.bam -r hg19.fa -o results/ \
    --target-regions panel_targets.bed

• GC model: Trained on off-target fragments (unbiased)
• Outputs: Split into .tsv (off-target) and .ontarget.tsv
• Auto-PON: Use -A xs2 to auto-load bundled PON for z-scores
• ML negatives: Use -A xs2 --skip-pon to output raw features (no z-scores)

Documentation

• Getting Started - 5-minute quickstart
• Installation - Docker, pip, development
• CLI Reference - Every command and option
• Feature Details - Per-feature documentation
• Nextflow Pipeline - Batch processing

Citation

If you use Krewlyzer, please cite:

• DELFI (FSR): Cristiano S, et al. Nature 2019
• WPS: Snyder MW, et al. Cell 2016
• OCF: Sun K, et al. Genome Res 2019
• UXM: Loyfer N, et al. Nature 2022

See Citation & Scientific Background for full references.

License

GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE.

Developed by Ronak Shah (@rhshah) at Memorial Sloan Kettering Cancer Center.