Fragment Size Coverage (FSC)

Command: krewlyzer fsc

Purpose

Computes GC-corrected coverage of cfDNA fragments in 6 biologically-meaningful size channels per genomic bin. Designed for ML feature extraction in cancer detection.

Biological Context

Why Fragment Sizes Matter

cfDNA fragments are not random—their sizes reflect the chromatin state of their source cells:

Cancer signature: Tumors release shorter cfDNA fragments than healthy cells due to: - Altered nucleosome positioning - Different apoptotic pathways - Chromatin accessibility changes

6-Channel ML Features

FSC partitions fragments into non-overlapping channels optimized for ML:

Implementation Details

Counting Pipeline

flowchart LR
    BED["sample.bed.gz"] --> RUST["Rust Backend"]
    BINS["100kb Bins"] --> RUST
    GC["GC Correction"] --> RUST

    RUST --> FSC["FSC.tsv"]

    subgraph "6 Channels"
        FSC --> US["ultra_short (65-100bp)"]
        FSC --> CS["core_short (101-149bp)"]
        FSC --> MN["mono_nucl (150-220bp)"]
        FSC --> DN["di_nucl (221-260bp)"]
        FSC --> LG["long (261-400bp)"]
        FSC --> UL["ultra_long (401-1000bp)"]
    end

    subgraph "With --pon-model"
        FSC --> PON["PON log₂ ratios"]
    end

    subgraph "With --target-regions"
        RUST --> FSC_ON["FSC.ontarget.tsv"]
    end

Python/Rust Architecture

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

    subgraph "Rust Backend"
        UP --> RUST["_core.run_unified_pipeline()"]
        RUST --> GC["GC correction"]
        GC --> COUNT["6-channel counting (65-1000bp)"]
    end

    subgraph "Python (Post-processing)"
        COUNT --> PROC["fsc_processor.py"]
        PROC --> AGG["Window aggregation"]
        AGG --> PON["PON log2 ratios"]
        PON --> OUT["FSC.tsv"]
        PON --> GENE["FSC.gene.tsv"]
        GENE --> REG["FSC.regions.tsv"]
        REG --> E1["filter_fsc_to_e1()"]
        E1 --> E1OUT["FSC.regions.e1only.tsv"]
    end

Aggregation Strategy

Why this matters: - 5Mb aggregation is great for detecting arm-level events (e.g., 1p/19q co-deletion) - Focal amplifications (e.g., EGFR amp <1Mb) are washed out by 5Mb aggregation - Panel targets are already gene-resolution—aggregation destroys their value

Recommendation: - For broad CNV detection (tumor fraction, aneuploidy): Use aggregated 5Mb windows - For focal analysis (driver genes, amplicons): Preserve raw bin resolution

GC Correction Details

Each fragment receives a weight based on its (length, GC%) bin:

weight = correction_factors[(length, gc_pct)]
channel_count += weight  # Instead of += 1

This removes GC bias before ML, not after. The correction factors come from: - WGS: Computed from all genome-wide fragments - Panel: Computed from off-target reads only (when --target-regions provided)

Bin Assignment

Fragments are assigned to bins based on overlap (not midpoint):

// If fragment overlaps bin, count it
tree.query(start, end, |bin| {
    bin.channel_count += weight;
});

A fragment spanning two bins counts in both. This is intentional for coverage metrics.

Usage

# Basic (auto-loads bundled 100kb bins)
krewlyzer fsc -i sample.bed.gz -o output/ --genome hg38

# With PoN for log2 ratios
krewlyzer fsc -i sample.bed.gz -o output/ --pon-model cohort.pon

# Custom bin size
krewlyzer fsc -i sample.bed.gz -o output/ --bin-input custom_bins.bed

CLI Options

Output Format

Output: {sample}.FSC.tsv

Base Columns (always present)

PoN Columns (when --pon-model provided)

WGS vs Panel Data (MSK-ACCESS)

Panel Mode Details

When you provide --target-regions to run-all:

1. GC model training: Uses only off-target reads (unbiased by capture)
2. Counting: All reads are counted (on-target + off-target)
3. Interpretation: On-target bins have high counts, off-target bins are sparse

krewlyzer run-all sample.bam -g ref.fa -o out/ \
    --target-regions msk_access_baits.bed

Panel Recommendations

ML Feature Engineering

Raw Features (per 5Mb window)

• 5 channel counts (ultra_short, core_short, mono_nucl, di_nucl, long)
• 1 total count

Derived Features (recommended)

• Channel ratios: short / long, mono_nucl / total
• Log2 ratios vs PoN: Tumor-specific deviations
• Reliability-weighted: Use reliability scores in loss functions

Example: Short-to-Long Ratio

df['short_long_ratio'] = (df['ultra_short'] + df['core_short']) / (df['long'] + 1e-9)

Higher ratio = more short fragments = potential tumor signal

Normalization Order

1. GC-weighting (Rust): Raw counts × correction factor per (length, GC) bin
2. Window aggregation (Python): 50 bins → 5Mb windows
3. PoN log-ratio (Python): log2(sample / PoN mean) when PoN model provided

Panel Mode (--target-regions)

For targeted sequencing panels (MSK-ACCESS), use --target-regions to generate separate on/off-target outputs:

krewlyzer fsc -i sample.bed.gz -o output/ \
    --target-regions MSK-ACCESS_targets.bed \
    --bin-input gene_level_bins.bed

Processing with Target Regions

flowchart TB
    BED["sample.bed.gz"] --> SPLIT{"Fragment Location"}

    SPLIT -->|"Overlaps target"| ON["On-Target"]
    SPLIT -->|"Does not overlap"| OFF["Off-Target"]

    ON --> FSC_ON["FSC.ontarget.tsv"]
    OFF --> FSC_OFF["FSC.tsv"]

Output Files

When to Use On-Target FSC

Gene-Centric FSC (MSK-ACCESS)

For MSK-ACCESS panels, use --assay to aggregate fragment counts by gene instead of genomic windows:

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

Output Files

Gene FSC Output Format

gene    n_regions  total_bp  ultra_short  core_short  mono_nucl  di_nucl  long  total  *_ratio  normalized_depth
ATM     62         8432      1234         5678        9012       3456     789   20169  ...      1245.67
BRCA2   42         5689      ...

Region FSC Output Format (NEW)

Per-exon/target output for fine-grained copy number analysis:

chrom  start      end      gene  region_name     region_bp  ultra_short  ...  normalized_depth
1      11168235  11168345  MTOR  MTOR_target_02  110        8.0          ...  1272.71
1      11169344  11169429  MTOR  MTOR_target_03  85         6.0          ...  1553.68

E1-Only FSC Output (NEW)

File: {sample}.FSC.regions.e1only.tsv

E1 (first exon) filtering extracts only the first exon per gene by genomic position. Per Helzer et al. (2025), promoter-proximal regions (E1) are Nucleosome Depleted Regions (NDRs) with distinct fragmentation patterns, often showing stronger cancer signal than whole-gene averages.

Usage:

# Default: E1-only file generated automatically with --assay
krewlyzer run-all -i sample.bam -r ref.fa -o out/ -A xs2

# Disable E1-only generation
krewlyzer run-all -i sample.bam -r ref.fa -o out/ -A xs2 --disable-e1-aggregation

Normalized Depth (RPKM-like)

Both gene and region outputs include normalized_depth:

This enables cross-sample depth comparisons independent of library size and region size.

Supported Assays

GC Correction for Gene FSC

In panel mode, gene-level FSC uses on-target GC correction factors (.correction_factors.ontarget.csv) for accurate copy number estimates.

Why this matters: - Different genes have different GC content - High-GC genes (e.g., EGFR) capture with different efficiency than low-GC genes - Without correction, high-GC genes appear falsely deleted, low-GC genes appear amplified

How it works:

# Instead of raw counting (+= 1):
weight = correction_factors[(len_bin, gc_pct)]
gene_count += weight  # GC-corrected counting

Log output example:

Aggregating FSC by gene: 146 genes, GC correction: ON (weighted counting)
Processed 2.4M fragments, 2.4M assigned to genes
  GC correction: avg_weight=1.898, missing_gc=0

See Also

• Citation: Cristiano et al. (2019) - DELFI fragmentomics paper
• PON: Z-Score Normalization - Log2 ratio computation
• Inputs: File Formats - Bin file format
• Related: FSR (ratios), FSD (distribution), Extract (BED.gz source)
• Guides: Panel Mode, GC Correction
• CLI: run-all - Unified pipeline
• Nextflow: Parameters - Batch processing

References