/cnvkit-copy-number

name: "cnvkit-copy-number"
description: "Detect somatic CNVs from WES/WGS/targeted BAMs (CNVkit v0.9.x). Bin coverage in target/antitarget regions, normalize vs reference, segment with CBS/HMM, call amps/dels, scatter/diagram plots, purity/ploidy, VCF/SEG export. CLI plus Python API (cnvlib). Use GATK CNV for deep WGS with population controls; use CNVkit for targeted/exome where antitarget bins matter."
license: "Apache-2.0"

CNVkit Copy Number Analysis

Overview

CNVkit detects somatic copy number variants (CNVs) from whole-exome sequencing (WES), whole-genome sequencing (WGS), or targeted panel BAM files. It calculates read depth in both on-target (capture) bins and off-target (antitarget) bins, corrects for GC bias and library depth, segments the log2 copy ratio profile with circular binary segmentation (CBS) or a hidden Markov model (HMM), and calls amplifications and deletions. CNVkit provides both a CLI (`cnvkit.py`) and a Python API (`cnvlib`) for integration into analysis pipelines, and produces scatter plots, chromosome diagrams, heatmaps, and export files in VCF, BED, and SEG formats.

When to Use

• Calling somatic copy number variants from tumor-normal paired exome (WES) or targeted panel sequencing
• Detecting copy number alterations in tumor-only samples using a pooled normal reference
• Running CNV analysis on whole-genome sequencing (WGS) data with the `--method wgs` mode
• Estimating tumor purity and ploidy for samples where purity is unknown, to interpret copy ratio calls
• Generating SEG format copy number files for GISTIC2, cBioPortal, or IGV visualization
• Identifying focal amplifications (e.g., ERBB2, MYC) or homozygous deletions (e.g., CDKN2A, RB1)
• Use **omics-plotting** SKILL for generic coverage/log2-ratio figures from exported tables; genome-wide CNV views use `cnvkit.py scatter/diagram`
• Use **GATK CNV** (`gatk DenoiseReadCounts` / `gatk ModelSegments`) instead for deep WGS cohorts with large matched panel-of-normals (PoN); CNVkit is better suited for targeted/exome data
• Use **Control-FREEC** instead when you need allele-frequency-based B-allele fraction modeling alongside CNV calling

Prerequisites

• **Software**: CNVkit v0.9.x, Python 3.8+, R (for CBS segmentation), samtools
• **Python packages**: `cnvlib` (installed as part of CNVkit), `matplotlib`, `pandas`
• **Input files**: sorted, indexed BAM files (tumor ± matched normal); BED file of capture targets; reference genome FASTA; access to R with DNAcopy package for CBS
• **Data requirements**: minimum ~50× mean target coverage for WES; WGS works at 20-30×

> **Check before installing**: The tool may already be available in the current environment (e.g., inside a `pixi` / `conda` env). Run `command -v cnvkit.py` first and skip the install commands below if it returns a path. When running inside a pixi project, invoke the tool via `pixi run cnvkit.py` rather than bare `cnvkit.py`.

# Install CNVkit via conda (recommended — handles R/DNAcopy dependency)
conda install -c bioconda cnvkit

# Or via pip (requires R + DNAcopy already installed)
pip install cnvkit

# Verify
cnvkit.py version
# cnvkit 0.9.10

# Install R DNAcopy (for CBS segmentation)
Rscript -e 'if (!requireNamespace("BiocManager")) install.packages("BiocManager"); BiocManager::install("DNAcopy")'

# Index BAM files if not already indexed
samtools index tumor.bam
samtools index normal.bam

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: sequencingMethod
    kind: required
    source: data
    ask: "Was this whole-genome, hybrid-capture exome, or amplicon sequencing?"
    default: null

  - id: D2
    param: referenceNormals
    kind: required
    source: user
    ask: "Which normal samples should define the expected coverage baseline?"
    default: null

  - id: D3
    param: targetRegions
    kind: required
    source: user
    depends_on: [D1]
    ask: "Which BED file describes the captured regions?"
    default: null
    skip_if: "whole-genome sequencing - there are no capture targets"

  - id: D4
    param: tumorPurity
    kind: required
    source: user
    ask: "What fraction of the sample is tumour rather than contaminating normal tissue?"
    default: "1.0 - assumes a pure sample, which understates every copy-number change"

  - id: D5
    param: ploidy
    kind: required
    source: user
    ask: "What baseline ploidy should absolute copy number be called against?"
    default: 2

  - id: D6
    param: segmentMethod
    kind: optional
    source: user
    ask: "Which algorithm should join bins into segments?"
    default: "circular binary segmentation"

  - id: D7
    param: binSizes
    kind: optional_conditional
    source: user
    depends_on: [D1]
    ask: "Do the default target and antitarget bin sizes suit this capture design?"
    default: "200 bp targets, 150 kb antitargets"

  - id: D8
    param: processes
    kind: never_ask
    source: data
    reason: "Affects runtime only, not the copy-number calls"
    default: "min(8, available_cores)"

D2 and D4 are the two that decide whether the calls mean anything. A flat reference instead of matched normals leaves capture bias in the log2 ratios, and a purity of 1.0 on a 40%-tumour sample compresses every real gain and loss toward neutral. Both produce a complete, plausible-looking segment table.

Quick Start

# One-command paired tumor/normal CNV analysis (WES)
cnvkit.py batch tumor.bam \
    --normal normal.bam \
    --targets targets.bed \
    --fasta GRCh38.fa \
    --output-dir cnvkit_results/ \
    --diagram --scatter \
    --method hybrid

# Output files in cnvkit_results/:
#   tumor.targetcoverage.cnn   — target bin coverage
#   tumor.antitargetcoverage.cnn — antitarget coverage
#   tumor.cnr                  — copy number ratios
#   tumor.cns                  — segmented copy numbers
#   tumor-scatter.png          — genome-wide scatter plot
#   tum