Windowed Protection Score (WPS)

Command: krewlyzer wps

Purpose

Computes ML-ready nucleosome and transcription factor protection profiles from cfDNA fragments around genomic anchors (TSS, CTCF sites) and global chromatin metrics from Alu elements.

Biological Context

What is WPS?

When DNA wraps around a nucleosome, the histone core protects ~147bp from enzymatic digestion. In cfDNA, fragments that span a nucleosome are "protected" (whole), while fragments that end at nucleosome boundaries are "fragmented" (cut).

WPS Formula:

Dual-Stream Processing

Krewlyzer separates fragments into two biological signals:

The tiered weights for nucleosome fragments prioritize "perfect" mono-nucleosome sizes (~167bp) over edge cases.

Python/Rust Architecture

flowchart TB
    subgraph "Python (CLI)"
        CLI["wps.py"] --> UP["unified_processor.py"]
        UP --> ASSETS["AssetManager"]
    end

    subgraph "Rust Backend (Parallel)"
        UP --> RUST["_core.run_unified_pipeline()"]
        RUST --> GC["GC correction"]
        GC --> WPS_NUC["WPS foreground
(par_iter over regions)"]
        GC --> WPS_BG["WPS background (Alu)"]
    end

    subgraph "Python (Post-processing)"
        WPS_NUC --> PROC["wps_processor.py"]
        WPS_BG --> PROC
        PROC --> SMOOTH["Savitzky-Golay smoothing"]
        SMOOTH --> FFT["FFT periodicity (Rust)"]
        FFT --> PON["PON z-scores"]
        PON --> OUT["WPS.parquet"]
    end

Foreground vs Background

WPS generates two complementary outputs that capture different biological scales:

Foreground (sample.WPS.parquet)

What it is: High-resolution WPS profiles around specific genomic anchors (TSS, CTCF sites).

Why it matters: Gene promoters and CTCF sites have characteristic nucleosome patterns: - Active promoters: Nucleosome-depleted region (NDR) upstream of TSS - Silent promoters: Packed nucleosomes across TSS - CTCF sites: Sharp nucleosome boundaries (insulator function)

ML use: These 200-bin vectors are gene-specific signatures. Comparing them across cancer types reveals tissue-of-origin and tumor-specific disruptions.

                          TSS
                           |
    ←───── -1kb ─────      ↓      ───── +1kb ─────→
    [bin 0] ... [bin 99] [100] [bin 101] ... [bin 199]

Background (sample.WPS_background.parquet)

What it is: Stacked WPS profiles from ~770,000 Alu elements across the genome.

Why Alu elements?

1. Ubiquitous: Alu elements are everywhere (~11% of human genome)
2. Consistent size: ~300bp (perfect for 2-nucleosome periodicity)
3. No gene bias: Not restricted to specific genes or pathways
4. Robust signal: Stacking 770K elements averages out noise

What it measures: When you stack all Alu WPS profiles, a periodic wave emerges at ~190bp (nucleosome repeat length). This periodicity reflects global chromatin health:

Hierarchical Groups: - Global_All: All Alu (highest SNR, best for QC) - Family_AluY/S/J: Subfamily ages (~15M / ~35M / ~65M years) - Chr1_All ... ChrY_All: Per-chromosome (CNV context)

Post-Processing: Smoothing and FFT

Savitzky-Golay Smoothing

Purpose: Reduce high-frequency noise while preserving peak shapes.

How it works: Fits a polynomial (order=3) to sliding windows (size=11) and uses the fitted value. Unlike moving average, it preserves peak heights and widths.

When to use: Always use smoothed columns for visualization. Raw columns for debugging.

FFT Periodicity Extraction

Purpose: Quantify the ~190bp nucleosome repeat length (NRL) from Alu stacking.

How it works: 1. Detrend: Remove linear trends from stacked profile 2. Normalize: Z-score to make amplitude comparable across samples 3. Window: Apply Hann window to reduce spectral leakage 4. FFT: Find dominant frequency in 150-250bp range 5. SNR: Compare peak amplitude to background

Expected values: - Healthy samples: NRL ~190bp, quality > 0.7 - Cancer samples: NRL shifted, quality < 0.5

Usage

# Basic (auto-loads bundled assets)
krewlyzer wps -i sample.bed.gz -o output/ --genome hg38

# With explicit background override
krewlyzer wps -i sample.bed.gz -o output/ --background custom_alu.bed.gz

# Panel data (MSK-ACCESS)
krewlyzer wps -i sample.bed.gz -o output/ --target-regions msk_access_baits.bed --bait-padding 20

# Panel data with panel-specific anchors (recommended for MSK-ACCESS)
krewlyzer wps -i sample.bed.gz -o output/ \
    --wps-anchors /path/to/xs2.wps_anchors.bed.gz \
    --target-regions msk_access_baits.bed

Panel-Specific WPS Anchors

For targeted panels like MSK-ACCESS, genome-wide WPS anchors include many regions with no coverage. Use panel-specific anchors for focused analysis:

What's included: - TSS anchors for genes in the panel - CTCF anchors within 100kb of panel genes

Benefits: - Reduced noise from off-target regions - Faster processing - More interpretable ML features

CLI Options

Bait Padding Trade-Off

The --bait-padding option controls how many bp to trim from bait edges to avoid capture artifacts.

Adaptive Safety: The tool automatically reduces padding for small targets:

effective_trim = min(user_trim, target_length / 4)

Dual WPS Output (with --assay)

When using --assay (e.g., for MSK-ACCESS), Krewlyzer generates two WPS output files:

krewlyzer wps -i sample.bed.gz -o output/ --assay xs2

Output Files

Why Dual Output?

How It Works

1. First pass: Genome-wide anchors (TSS+CTCF for ~5,000 genes)
2. Second pass: Panel-specific anchors (genes in your assay)

Both use the same pre-computed GC correction factors for consistency.

Output Files

Foreground: sample.WPS.parquet

Per-region profiles centered on TSS/CTCF anchors (±1kb, 200 bins × 10bp).

PON-Normalized Columns (v2.0)

When using a v2.0 vector PON, these additional columns are computed:

See PON v2.0 for baseline details.

Background: sample.WPS_background.parquet

Hierarchical stacking of ~770K Alu elements into 29 groups.

WGS vs Panel Data (MSK-ACCESS)

Key insight: Background Alu stacking works for panels because Alu elements are genome-wide, not restricted to capture regions.

ML Feature Summary

From Foreground

• Gene-specific nucleosome disruption patterns
• TF binding footprints at promoters
• Tissue-of-origin signatures

From Background

• Global tumor burden: Loss of periodicity correlates with tumor fraction
• Subfamily ratios: Family_AluY / Family_AluJ → Tissue context
• Per-chromosome: Chromatin disruption → CNV context

References

See Also

• Input File Formats - WPS anchors BED6 format for --wps-anchors
• PON Models - Building and using PON
• Troubleshooting - Common issues