build-pon

Build a unified Panel of Normals (PON) model from healthy plasma samples.

Synopsis

krewlyzer build-pon SAMPLE_LIST --assay NAME -r REFERENCE -o OUTPUT [OPTIONS]

Description

Creates a PON model containing all baselines needed for cfDNA analysis from a cohort of healthy samples:

• GC Bias Model - For coverage correction
• FSD Baseline - Fragment size distributions per arm
• WPS Baseline - Nucleosome protection per region
• OCF Baseline - Open chromatin footprinting per region
• MDS Baseline - Motif diversity and k-mer frequencies
• TFBS Baseline - Transcription factor binding site entropy (808 TFs)
• ATAC Baseline - ATAC-seq peak entropy (23 cancer types)

This model is used for bias correction and z-score normalization during sample processing.

Arguments

Required Options

Optional Parameters

Pipeline Flow

flowchart TB
    subgraph Input
        SL["sample_list.txt"]
        BAM["BAM/CRAM files"]
        BED["BED.gz files"]
    end

    subgraph "Per-Sample Processing (Parallel with -P)"
        EXT["Extract fragments"]
        GC["GC observations"]
        FSD["FSD per arm"]
        WPS["WPS per anchor"]
        OCF["OCF per region"]
        MDS["MDS k-mers"]
        FSC_G["FSC gene/region"]
        TFBS["TFBS entropy"]
        ATAC["ATAC entropy"]
        RMDS["Region MDS"]
    end

    subgraph "Baseline Aggregation"
        AGG_GC["GC bias curves\nmean/std per bin"]
        AGG_FSD["FSD baseline\nmean/std per arm"]
        AGG_WPS["WPS baseline\nmean/std per region"]
        AGG_OCF["OCF baseline\nmean/std per region"]
        AGG_MDS["MDS baseline\nk-mer mean/std"]
        AGG_FSC["FSC gene/region\nmean/std per gene"]
        AGG_TFBS["TFBS baseline\nmean/std per TF"]
        AGG_ATAC["ATAC baseline\nmean/std per type"]
        AGG_RMDS["Region MDS\nmean/std per gene"]
    end

    subgraph Output
        PON["PON.parquet"]
    end

    SL --> BAM & BED
    BAM --> EXT --> GC & FSD & WPS & OCF & MDS & FSC_G & TFBS & ATAC & RMDS
    BED --> GC & FSD & WPS & OCF

    GC --> AGG_GC --> PON
    FSD --> AGG_FSD --> PON
    WPS --> AGG_WPS --> PON
    OCF --> AGG_OCF --> PON
    MDS --> AGG_MDS --> PON
    FSC_G --> AGG_FSC --> PON
    TFBS --> AGG_TFBS --> PON
    ATAC --> AGG_ATAC --> PON
    RMDS --> AGG_RMDS --> PON

Examples

WGS Mode:

krewlyzer build-pon healthy_samples.txt \
    --assay wgs-hg19 \
    --reference hg19.fa \
    --output wgs.pon.parquet

Panel Mode (MSK-ACCESS):

krewlyzer build-pon healthy_samples.txt \
    --assay msk-access-v2 \
    --reference hg19.fa \
    --target-regions msk_access_targets.bed \
    --output msk-access.pon.parquet \
    --threads 16

HPC with custom temp directory:

krewlyzer build-pon healthy_samples.txt \
    --assay xs1 \
    --reference hg19.fa \
    --target-regions msk_access_v1_targets.bed \
    --temp-dir /scratch/$USER/pon_tmp \
    --output xs1.pon.parquet \
    --threads 16 \
    --verbose

Input Formats

Sample list file (samples.txt):

/path/to/sample1.bam
/path/to/sample2.bam
/path/to/sample3.bed.gz

Both BAM/CRAM and BED.gz inputs are supported:

Output

The output is a Parquet file containing:

In panel mode, additional on-target baselines are included:

Panel Mode

When --target-regions is provided:

1. GC model trained on off-target fragments only (unbiased by capture)
2. FSD/WPS include separate on-target statistics
3. Output model includes panel_mode=true in metadata

Recommendations

• Minimum samples: 10+ for stable baselines
• FSC gene/region: Requires minimum 3 samples per gene for statistics
• Same assay: All samples must be from the same assay
• Same reference: Must match reference used for processing
• Healthy samples: Use confirmed non-cancer samples only

MDS Baseline

The MDS (Motif Diversity Score) baseline is computed from k-mer frequencies at fragment ends:

Z-score interpretation:

HPC Usage (SLURM)

For running build-pon on HPC clusters with SLURM, use one of these approaches:

Resource Planning

sbatch Script (Recommended)

Create run_pon.sh:

#!/bin/bash
#SBATCH --partition=your_partition
#SBATCH --job-name=build_pon
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=48
#SBATCH --mem=150G
#SBATCH --time=12:00:00
#SBATCH --output=pon_build_%j.out
#SBATCH --error=pon_build_%j.err

# Create temp directory
mkdir -p ./pon_temp

krewlyzer build-pon samples.txt \
  --assay your-assay \
  -r /path/to/reference.fasta \
  -o output.pon.parquet \
  --temp-dir ./pon_temp \
  --threads 48 \
  -P 6 \
  --memory-per-sample 20 \
  --sample-timeout 7200 \
  --allow-failures \
  -v

Submit with:

sbatch run_pon.sh

srun One-liner

mkdir -p ./pon_temp && srun \
  --partition=your_partition \
  --job-name=build_pon \
  --nodes=1 \
  --ntasks=1 \
  --cpus-per-task=48 \
  --mem=150G \
  --time=12:00:00 \
  krewlyzer build-pon samples.txt \
    --assay your-assay \
    -r /path/to/reference.fasta \
    -o output.pon.parquet \
    --temp-dir ./pon_temp \
    --threads 48 -P 6 --memory-per-sample 20 \
    --sample-timeout 7200 --allow-failures -v \
  2>&1 | tee pon_build.log

Key SLURM Parameters

Key krewlyzer Parameters