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 motif & MDS scores .EndMotif.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 .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.

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 12, 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 12, 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.0.tar.gz (440.5 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.0-cp312-cp312-manylinux_2_28_x86_64.whl (7.5 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.28+ x86-64

krewlyzer-0.9.0-cp311-cp311-manylinux_2_28_x86_64.whl (7.5 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.28+ x86-64

krewlyzer-0.9.0-cp310-cp310-manylinux_2_28_x86_64.whl (7.5 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.28+ x86-64

File details

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

File metadata

  • Download URL: krewlyzer-0.9.0.tar.gz
  • Upload date:
  • Size: 440.5 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.0.tar.gz
Algorithm Hash digest
SHA256 f782dddfc669ae31a81e758b2b5923d9f5f48accbd765790607d84cd27b1e688
MD5 301c69a103c1032ba2d9bc0b1e6abf13
BLAKE2b-256 ba3b0865c2a4eb97955739bd169a7ab5450fe3f6042e3d46dfeaa819f94de00f

See more details on using hashes here.

Provenance

The following attestation bundles were made for krewlyzer-0.9.0.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.0-cp312-cp312-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for krewlyzer-0.9.0-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b4628b06377dcd2872e27ee2afbff0b8f69217cc8be92d7208fd6c6515a2e1e1
MD5 f6fc4c3f62717f2841440d7a7342c50a
BLAKE2b-256 3d43157993af775c2c03dd4e5bbbc2ec1efaf5ed43983a4fc3e1284943f6a8f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for krewlyzer-0.9.0-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.0-cp311-cp311-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for krewlyzer-0.9.0-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 6c64dde8af932228b0c263bd63de2c0be4737b5e94fc3598da6331dde71ce49f
MD5 c8d8d35cc6a0d5a0bfb662c553ccdd5c
BLAKE2b-256 71785c9f0fb0067b2ee0021b0b1421a78c4594328dd332dffa9ba4078f2051ca

See more details on using hashes here.

Provenance

The following attestation bundles were made for krewlyzer-0.9.0-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.0-cp310-cp310-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for krewlyzer-0.9.0-cp310-cp310-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 21948b426a8552661251b20e178b4f4ddca642ccf39556ce8ac127922798d770
MD5 97399a62996a9a672eb05712d2bedb86
BLAKE2b-256 0afad73e88f335d0aea8d5a9741a11673b0ba3e2d2806584d15d61d9c6206e16

See more details on using hashes here.

Provenance

The following attestation bundles were made for krewlyzer-0.9.0-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

0.9.1

4 files

This release

0.9.0 This release

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