Krewlyzer: Comprehensive cfDNA Feature Extraction Toolkit

Krewlyzer logo

PyPI version GitHub Actions Docker

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

Traditional Liquid Biopsy Fragmentomics with Krewlyzer
Look for specific mutations Analyze how DNA is cut
Need prior knowledge of tumor Works without knowing mutations
Miss ~50% of early cancers Detect more cancers, earlier

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

What You Get

Feature Clinical Use
Fragment size ratios Tumor burden estimation
Cutting patterns Tissue of origin identification
Nucleosome positioning Epigenetic profiling
Mutation-specific sizes MRD monitoring

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

Command Description Output
extract Extract fragments from BAM .bed.gz
motif End, breakpoint & MDS scores .EndMotif.tsv, .BreakPointMotif.tsv, .MDS.tsv
fsc Fragment size coverage .FSC.tsv
fsr Fragment size ratios .FSR.tsv
fsd Size distribution by arm .FSD.tsv
wps Windowed protection score .WPS.parquet
ocf Orientation-aware fragmentation .OCF.tsv
region-entropy TFBS/ATAC size entropy .TFBS.tsv, .ATAC.tsv
region-mds Gene- and exon-level MDS .MDS.gene.tsv, .MDS.exon.tsv
uxm Fragment-level methylation .UXM.tsv
mfsd Mutant vs wild-type sizes .mFSD.tsv
build-pon Build Panel of Normals (--from-outputs re-aggregates existing runs) .pon.parquet
build-gc-reference Build GC reference assets .gc_reference.tsv
run-all All features in one pass All outputs

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.

Command Description
validate Check input assets — BEDs, anchors, GC factors — before a run
describe-output What is in each output file: shape, columns, ranges
report Single-sample HTML report — verdict, charts, interpretation
validate-output Check results against the downstream output contract
validate-cohort Cross-sample degeneracy checks over fingerprints
validate-pon Check a PON before anything is scored against it
stamp-pon Record the release a built PON ships with 
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
pip install 'krewlyzer[report]'
krewlyzer report results/{sample_id}/ -o report.html

[!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

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.

Project links

Data verified by PyPI on Aug 16, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.9.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for msk-access from gravatar.com msk-access

Credits

Author: Ronak Shah

GitHub Statistics

Data verified by PyPI on Aug 16, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.10

Provides Extra

dev docs report test

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

krewlyzer-0.9.1.tar.gz (443.7 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

krewlyzer-0.9.1-cp312-cp312-manylinux_2_28_x86_64.whl (7.6 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.28+ x86-64

krewlyzer-0.9.1-cp311-cp311-manylinux_2_28_x86_64.whl (7.6 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.28+ x86-64

krewlyzer-0.9.1-cp310-cp310-manylinux_2_28_x86_64.whl (7.6 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.28+ x86-64

File details

Details for the file krewlyzer-0.9.1.tar.gz.

File metadata

  • Download URL: krewlyzer-0.9.1.tar.gz
  • Upload date:
  • Size: 443.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for krewlyzer-0.9.1.tar.gz
Algorithm Hash digest
SHA256 72bc49ca9d0d9912df5fb81ba76025fd7e8f1a664dc0669131de0f4d8e50204a
MD5 509dad75143886f2f95c92c555ec8865
BLAKE2b-256 1bc6e7e7dc293b6aadf2110aaabeb4e3d534ab2de819487e38d875aadaa34e08

See more details on using hashes here.

Provenance

The following attestation bundles were made for krewlyzer-0.9.1.tar.gz:

Publisher: release.yml on msk-access/krewlyzer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file krewlyzer-0.9.1-cp312-cp312-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for krewlyzer-0.9.1-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9db9c70c896961e3ced76c4c34f1308ecc2f9f8e82516c45b0676d886b9f5c6a
MD5 90b33ea85b73a7aa52305b80ca1d82c8
BLAKE2b-256 7d2f6ab83c2066a0e8f5eb0e6cf46acf456d08c2999b5817e4ed66feefcd0a62

See more details on using hashes here.

Provenance

The following attestation bundles were made for krewlyzer-0.9.1-cp312-cp312-manylinux_2_28_x86_64.whl:

Publisher: release.yml on msk-access/krewlyzer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file krewlyzer-0.9.1-cp311-cp311-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for krewlyzer-0.9.1-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 444b7f0aaff730ed0fc868cb2d575e6e765fcf32854c517c6e5b3138f5152535
MD5 4eb12abbfc45b666a3065b2cc1f14b32
BLAKE2b-256 ba73ceb6f25150d693174c74e4575f7be2911e9f94fa79a59f8d31412aac8ffc

See more details on using hashes here.

Provenance

The following attestation bundles were made for krewlyzer-0.9.1-cp311-cp311-manylinux_2_28_x86_64.whl:

Publisher: release.yml on msk-access/krewlyzer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file krewlyzer-0.9.1-cp310-cp310-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for krewlyzer-0.9.1-cp310-cp310-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a467e1314fc01a6d7324bea630c1ff3cb74d0e7122d74829c2e23890175fc1f8
MD5 64757475c8e9a6c42db4a3c4972791a3
BLAKE2b-256 fa4a3858de0aa625dcec36880ec68793c38673b4f98273367079c9842d4578da

See more details on using hashes here.

Provenance

The following attestation bundles were made for krewlyzer-0.9.1-cp310-cp310-manylinux_2_28_x86_64.whl:

Publisher: release.yml on msk-access/krewlyzer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.9.2

4 files

This release

0.9.1 This release

4 files

0.9.0

4 files

0.8.3

4 files

0.8.2

4 files

0.8.1

4 files

0.8.0

4 files

0.7.0

4 files

0.6.0

4 files

0.5.3

4 files

0.5.2

4 files

0.5.1

4 files

0.5.0

4 files

0.3.2

4 files

0.3.0

4 files

0.2.3

4 files

0.2.2

4 files

0.2.1

2 files

0.2.0

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page