Protocol for detecting germline copy number variants from whole-exome sequencing using agent-assisted Snakemake workflows

Summary

Germline copy number variants (gCNVs) are vital for diagnosing rare monogenic disorders. Here, we present a containerized, agent-assisted Snakemake protocol for detecting, annotating, and visualizing gCNVs from short-read whole-exome sequencing data. We describe steps for constructing baseline models, executing CNV calling, annotating variant pathogenicity using public datasets, and rendering interactive visual reports. This automated workflow simplifies routine management and ensures cross-platform reproducibility through a unified interface.

Graphical abstract

Highlights

• •Instructions for containerized environment setup and baseline CNV model training
• •Steps for executing per-sample gCNV discovery and joint postprocessing
• •Guidance on automated variant pathogenicity annotation and ACMG/ClinGen filtering
• •Procedures for cohort-level multi-sample visualization and HTML report compilation

Publisher’s note: Undertaking any experimental protocol requires adherence to local institutional guidelines for laboratory safety and ethics.

Germline copy number variants (gCNVs) are vital for diagnosing rare monogenic disorders. Here, we present a containerized, agent-assisted Snakemake protocol for detecting, annotating, and visualizing gCNVs from short-read whole-exome sequencing data. We describe steps for constructing baseline models, executing CNV calling, annotating variant pathogenicity using public datasets, and rendering interactive visual reports. This automated workflow simplifies routine management and ensures cross-platform reproducibility through a unified interface.

Before you begin

High-throughput Whole Exome Sequencing (WES) has become widely adopted for the diagnosis and screening of rare genetic disorders, substantially improving molecular diagnostic yield in clinical practice. However, accurate detection of germline CNVs (gCNVs) from short-read WES data remains technically challenging. Several intrinsic limitations affect WES-based CNV analysis: 1) incomplete breakpoint resolution because many CNV breakpoints occur outside captured exonic regions; 2) uneven target capture efficiency caused by GC-rich or repetitive regions; 3) limited sensitivity for small CNVs because of sparse probe spacing; and 4) batch effects introduced by sequencing platform differences, library preparation methods, and experimental variability. These limitations affect essentially all WES-based CNV detection methods, including the Genome Analysis Toolkit (GATK) gCNV framework¹ used in this protocol.

The GATK gCNV caller is currently one of the most widely used approaches for CNV detection from exome sequencing data. By leveraging Bayesian modeling and cohort-based normalization, GATK gCNV improves specificity and robustness compared with earlier depth-based methods. Nevertheless, practical implementation often requires complex software configuration, coordinated execution of multiple preprocessing steps, and careful management of model training and inference. To address these practical challenges, we developed a fully reproducible Snakemake-based workflow for WES CNV detection. Compared with traditional shell-script pipelines, the workflow provides improved modularity, reproducibility, scalability, and execution transparency through automatic dependency management, checkpoint tracking, parallel execution, and containerized deployment.

All workflow files, scripts, configuration files, and example datasets are available in the GitHub repository (https://github.com/model-lab/Identify_gCNV_with_WES). The workflow is implemented in Snakemake, which automates task scheduling, dependency management, execution tracking, and reproducible pipeline execution. All command-line examples provided in this protocol have been validated using the included demonstration dataset in a standard Linux environment. Unless otherwise specified, commands should be executed within the supplied Conda environment or the recommended Docker container. Throughout this protocol, input files, output directories, configuration files, and naming conventions are standardized. Users generally need only modify project-specific file paths and sample identifiers while preserving the overall directory structure and file formats. This modular Snakemake implementation simplifies workflow customization and enables scalable, reproducible CNV analysis compared with conventional shell script–based pipelines.

Innovation

Beyond the standard GATK-gCNV analytical workflow, this protocol introduces an integrated framework designed to optimize usability, automation, and reproducibility. Key advancements include a reproducible Snakemake workflow that ensures automated dependency tracking, checkpoint management, and scalable parallel execution. Software environments are standardized via Docker and Conda to guarantee version control across platforms. To streamline execution, the protocol incorporates agent-assisted automation utilities that automate routine workflow planning, project validation, command generation, quality control aggregation, and standardized result packaging. These utilities reduce manual configuration and user errors while preserving Snakemake’s underlying execution engine. Furthermore, the framework provides flexible execution modes, supporting both cohort-specific model training and rapid direct inference using pre-trained models. Finally, it seamlessly connects raw calling to comprehensive downstream analyses, including CNV annotation, quality assessment, and publication-ready report generation. Validated on publicly available 1000 Genomes Project (1kGP) WES data, the workflow accepts FASTQ or BAM/CRAM inputs for end-to-end processing.

Download the workflow and reference resources

Timing: ∼10–20 min

The complete Snakemake workflow, Docker configuration, Conda environment specification, agent-assisted workflow automation utilities, example datasets, and documentation are available from the GitHub repository: https://github.com/model-lab/Identify_gCNV_with_WES. Before beginning the analysis, download the repository and the required reference resources. The repository contains the following major components:

workflow/: Snakemake workflow files including the main Snakefile and configuration resources.

Scripts/: helper scripts for downloading resources, preprocessing, visualization, and reporting.

Scripts/agents/: agent-assisted workflow automation utilities for generating workflow plan files, validating inputs, executing standardized workflows, collecting QC reports, and packaging analysis results.

Plans/: example per-sample plan files.

Model/: pre-trained baseline and ploidy models.

Data/: reference genomes, interval lists, annotation resources, and example BAM files.

Outputs/: suggested output directory for workflow results.

• 1.Clone the GitHub repository:

git clone https://github.com/model-lab/Identify_gCNV_with_WES.git

cd Identify_gCNV_with_WES/

• 2.
  Download the required reference datasets and annotation resources:

  bash scripts/download zendo data.sh

This script retrieves required reference genomes, target capture interval lists, annotation resources, and pre-trained model files from Zenodo into the appropriate directories. The downloaded files serve as example inputs for the pipeline. For their own analyses, users should prepare input files according to their specific project requirements by following the instructions described in the “prepare the input files” section below.

Prepare the input files

Timing: ∼Hours to days depending on the user's project

Timing: 2–4 days depending on the user's internet speed (step 3a)

Timing: Hours to days (factors that affect timing include the number of samples and available computing resources) (step 3b)

Timing: ∼30 min depending on the user's internet speed (step 3c)

Timing: ∼30 min depending on the user's internet speed (step 3d)

Timing: ∼10 min (step 3e)

Before running the workflow, prepare all sequencing data, reference resources, and sample metadata required for the analysis.

• 3.Organize the project directory.
  Organize the project directory and prepare the necessary input resources, including paired-end WES FASTQ files or aligned BAM/CRAM files, the reference genome and corresponding index files, target capture interval files matching the sequencing panel, known variant resources required for GATK Base Quality Score Recalibration (BQSR), gCNV reference resources generated by the GATK-gCNV pipeline (if applicable), and sample metadata describing sample identifiers, sequencing batches, and project organization.

  Note: Samples analyzed within the same cohort should preferably originate from the same sequencing platform, target enrichment panel, and reference genome build to ensure reliable coverage normalization during cohort-based CNV detection. Confirm that all reference genome files, index files, interval lists, and annotation databases are correctly downloaded and accessible before launching the workflow.

  • a.
    Download paired-end WES FASTQ files.
    We use WES datasets from the 1kGP Phase 3 as a case study to illustrate the following CNV analysis workflow. Based on the aforementioned dataset list, users can download the raw sequence data (provided in FASTQ format) or alignment data (provided in BAM/CRAM format) from the FTP server: ftp.1000genomes.ebi.ac.uk. Users can download the data by utilizing the full path with tools like ‘wget’ or ‘curl’, or by using command-line FTP client tools such as ‘lftp’.

    Note: We recommend using at least 30 samples for cohort model training. Larger cohorts are preferable when samples originate from different sequencing centers or library preparation protocols, as increased cohort diversity improves robustness against sequencing-specific technical variation.

  • b.
    WES data preprocessing.
    The Snakemake workflow supports preprocessing from either raw FASTQ files or existing BAM/CRAM files. If raw sequencing reads are provided, preprocessing follows the GATK Best Practices workflow for generating analysis-ready BAM files. Major preprocessing steps are implemented as modular Snakemake rules within the main Snakefile, including read alignment, duplicate marking, and base quality score recalibration. Example preprocessing rules include:
    map_reads_bwa: alignment of sequencing reads using BWA.
    mark_duplicates_picard: duplicate marking using Picard.
    base_recalibrator_gatk: generation of recalibration tables.
    apply_bqsr_gatk: application of recalibrated quality scores.
    Users may execute preprocessing through Snakemake directly:

    snakemake --snakefile workflow/Snakefile --cores 8
    Alternatively, preprocessing can be managed through per-sample plan files automatically generated by the agent-assisted workflow utilities, which standardize sample organization and reduce manual preparation.

    • i.
      Mapping sequence reads to the reference genome: Sequencing reads are aligned to the reference genome using BWA-MEM to generate coordinate-sorted BAM files.
    • ii.
      Marking duplicates: PCR duplicates are identified and flagged using Picard MarkDuplicates.
    • iii.
      Base quality score recalibration: Base quality scores are recalibrated using GATK BaseRecalibrator and ApplyBQSR.
      These preprocessing steps are automatically coordinated by Snakemake, ensuring reproducibility and correct dependency execution.

      Note: If data preprocessing is required, users must first complete Step 3c-e to prepare reference genomes, interval lists, and recalibration resources for subsequent steps.

      Note: To save space, as BAM files can be quite large, you can compress them into CRAM format using ‘samtools’. This compression step reduces the storage space required while maintaining compatibility with the subsequent analyses in this protocol. Here are the commands to compress BAM files into CRAM format and index them:

      samtools view -@ 12 -C -T reference_genome.fa -o ${sample_name}.cram ${sample_name}.bam

      samtools index ${sample_name}.cram
  • c.
    Prepare the reference genome.
    Obtain the reference genome in FASTA format. Depending on the selected reference genome build, download the corresponding reference assembly from the GATK Resource Bundle or the IGSR (International Genome Sample Resource) FTP site (see “Reference assembly sequence” in the key resources table). Index the downloaded reference genome using samtools and bwa:

    samtools faidx reference_genome.fa

    bwa index reference_genome.fa
  • d.
    Download known sites for recalibration.
    Download known variant resources required for variant recalibration (e.g., dbSNP, 1000 Genomes, and Mills and 1000G Gold Standard Indels) from the GATK Resource Bundle or the IGSR FTP site (see “Mapping resources” in the key resources table).

    Note: The GATK Resource Bundle is a collection of reference files and known variant datasets for human genome analysis with GATK. Separate resource bundles are available for different reference genome builds, including GRCh38/hg38 and b37/hg19. For additional information, see the GATK documentation: https://gatk.broadinstitute.org/hc/en-us/articles/360035890811-Resource-bundle.

  • e.
    Interval file define subsets of exonic regions.
    To obtain the necessary exon region files for subsequent analyses, follow these steps to access and download the files from the UCSC Genome Browser: Go to https://genome.ucsc.edu/cgi-bin/hgTables; Select the appropriate genome version in the “clade”, “genome”, and “assembly” menus; In the “group” menu, select “Genes and Gene Predictions”; Choose the desired track, such as “NCBI RefSeq” or “GENCODE”; Set Region and Output Format: In the “region of interest” section, select “genome”; Choose “BED” as the output format; Generate the BED File: Click the “get output” button to generate the BED file containing the exon regions; Save the BED file to your local system; Processing the BED File: The BED file will contain all exon regions of interest.
    Users can use the saved BED file to create the Intervals file required for the CNV analysis protocol. Refer to our GitHub repository for the specific format or see the supported interval list formats on the GATK website: https://gatk.broadinstitute.org/hc/en-us/articles/360035531852-Intervals-and-interval-lists.

    Note: The BED file for exonic target capture regions can also be obtained from the official support or resource pages of sequencing platforms. If the user's data originates from the same sequencing platform, it will be more advantageous in accurately reflecting the genomic regions covered by the sequencing data. For instance, Illumina's exome sequencing products provide relevant files for download. The targeted regions manifest files list the 214,126 targeted exonic regions with start and stop chromosome locations in GRCh37/hg19. These files can be accessed at https://support.illumina.com/downloads/nextera-rapid-capture-exome-v1-2-product-files.html.

Prepare the software environment

Timing: ∼20–30 min (factors that affect timing include internet speed and the method of environment configuration)

To maximize computational reproducibility, this workflow employs a software management strategy based on Conda and Docker. Developed and validated primarily under Linux (x86_64), the workflow is best deployed via Docker, which encapsulates the entire software stack to ensure consistent execution across operating systems. For cross-platform support, Windows users should run Docker Desktop with Windows Subsystem for Linux 2 (WSL2), while macOS users can execute it via Docker, given sufficient computational resources.

The core analytical tools including GATK, Snakemake, BWA, Samtools, Picard, and essential Python, Perl, and R packages are fully packaged within the provided Conda environment and Docker image. Using either environment ensures that all verified software versions run seamlessly without additional language-specific setup.

While several downstream visualization and reporting utilities (such as AnnotSV, knotAnnotSV, vcf2circos, PlotCNV, and HandyCNV) typically require manual installation, their specific versions have been pre-integrated into the workflow and can be executed directly within the containerized environment. Interactive desktop applications, such as the Integrative Genomics Viewer (IGV), must be installed separately as they run outside the container.

Unless otherwise noted, all command-line examples in this protocol were developed and tested under Linux using the supplied Conda environment or Docker image. The complete software inventory and tested versions are summarized in the key resources table, with the corresponding environment.yml and Dockerfile hosted on GitHub to enable reproducible deployment, version tracking, and future maintenance.

• 4.Conda-based installation.

Create the recommended Conda environment.

cd Identify_gCNV_with_WES/

conda env create -f environment.yml

conda activate cnv_workflow

• 5.(Alternative) Docker-based installation.

Build the Docker image:

cd Identify_gCNV_with_WES/

docker build -t cnv-detection .

Example Docker execution:

docker run --rm -it \

 -v $(pwd):/workspace \

 -w /workspace \

 cnv-detection \

 bash -lc "snakemake --snakefile workflow/Snakefile --cores 4"

Note: The workflow was tested primarily under Linux environments. The required software versions and paths are managed centrally through workflow/config.yaml. The provided Conda environment and Docker image automatically configure these dependencies.

Time considerations

The computational time depends on cohort size, sequencing depth, and available computing resources. For a typical WES cohort analyzed on a multi-core Linux server, preprocessing usually requires several hours, whereas cohort-based CNV discovery, annotation, visualization, and report generation may require several additional hours. Approximate execution times for individual protocol sections are provided throughout the step-by-step method details.

Key resources table

REAGENT or RESOURCE	SOURCE	IDENTIFIER
Deposited data
Zenodo resource package	Zenodo	https://zenodo.org/records/19489460
1,000 genomes (1KG) exome sequencing data	The 1000 genomes project consortium, 2015	http://ftp.1000genomes.ebi.ac.uk/vol1/ftp/phase3
Interval files	NCBI RefGene/GENCODE	https://genome.ucsc.edu/cgi-bin/hgTables
Interval files	Nextera Rapid Capture Exome and Expanded Exome Kit, Illumina	https://support.illumina.com/sequencing/sequencing_kits/nextera-rapid-capture-exome-kit.html
Reference assembly sequence	The 1000 genomes project consortium, 2015	ftp.1000genomes.ebi.ac.uk/vol1/ftp/technical/reference/; ftp.broadinstitute.org/bundle
Mapping resources (GATK bundle files: Mills, 1000G, dbsnp)	The 1000 genomes project consortium, 2015	ftp.1000genomes.ebi.ac.uk/vol1/ftp/technical/reference/; ftp.broadinstitute.org/bundle
Software and algorithms
Docker/latest	Docker Inc.	-
Snakemake/v8.28.0	Snakemake	https://snakemake.github.io/
R/v4.4	The R Foundation	https://www.r-project.org/
Perl/v5.34	Larry Wall	https://www.perl.org/
Python/v5.34.1	Python Software Foundation	https://www.python.org/
Conda/py314_26.5.3-2	Anaconda Inc.	https://docs.conda.io/
CNV workflow repository	GitHub Inc.	https://github.com/model-lab/Identify_gCNV_with_WES
Agent-assisted workflow scripts	This study	scripts/agents/
GATK/v4.5.0.0	Broad Institute	https://gatk.broadinstitute.org/
bwa/v0.7.18	Li et al.2	https://github.com/lh3/bwa
picard/v2.25.1	Broad Institute	https://broadinstitute.github.io/picard/
samtools/v1.21	Li et al.3	https://www.htslib.org/
AnnotSV/v3.4.2	Geoffroy et al.4	https://lbgi.fr/AnnotSV/
knotAnnotSV/v1.1.5	Geoffroy et al.5	https://github.com/mobidic/knotAnnotSV
vcf2circos/v1.2.0	Geoffroy et al.6	https://github.com/bioinfo-chru-strasbourg/vcf2circos
Integrative Genomics Viewer (IGV)	igvteam7	https://igv.org/
PlotCNV	Findlay Bewicke-Copley8	https://github.com/model-lab/PlotCNV
HandyCNV/v1.1.7	Zhou et al.9	https://github.com/JH-Zhou/HandyCNV
SegmentModel Spy/v1.0	Kari Lavikka10	https://genomespy.app/segmentmodel/

Step-by-step method details

Baseline CNV model training

Timing: Days to weeks (factors that affect timing include the number of samples and available computing resources)

Here, we describe steps for training cohort-level baseline models, including the ploidy and gCNV models, using control samples to characterize cohort-specific read-depth distributions and establish background expectations for subsequent CNV calling. The integrated Snakemake workflow automatically performs interval preprocessing, GC-content annotation, cohort-level read-count collection, contig ploidy inference, and baseline model training. Running the Snakemake workflow described above completes all required model training procedures. The following code blocks are provided only to illustrate the underlying processes and are not required for execution.

The major training stages are organized into dedicated Snakemake rules and can be executed automatically using:

snakemake --snakefile workflow/Snakefile -R train_models --cores 8

The workflow generates two major outputs:

ploidy-model: cohort ploidy inference model.

baseline-model: cohort-trained baseline model for CNV detection.

These trained models are subsequently reused during CNV calling in CASE mode.

Note: As analyzing the entire genome would necessitate greater computational resources, to reduce computational burden during model training, users may partition the genome into chromosomal or regional subsets and train models independently for each subset. These models can subsequently be combined during the CNV calling stage.

• 1.
  Prepare the preprocessed interval list and target annotations for training model.

  • a.
    Extract targeted exon regions from the reference genome assembly using target BED files:

    samtools dict hg19_chr20.fa > hg19_chr20.dict

    awk -F“\t” 'NR == FNR {print $0;next} FNR > 1 && NR > FNR && $3 == “chr20” {split($10, a, “,”); split($11, b, “,”);gsub(“chr”, “”, $3);for (i = 1; i <= $9; i++) {print $3 “\t” a[i] “\t” b[i] “\t” $13“_” i}}' hg19_chr20.dict UCSC_RefGene_hg19.bed > hg19_chr20.interval_list

    Note: This Snakemake rule “create_interval_list” first generates a dictionary file (.dict) for the reference genome, then processes the exon region BED file downloaded from UCSC (refer to step 3e in the above “before you begin” section) to create an interval list. For simplicity, we will concentrate on chromosome 20.

  • b.
    Generate preprocessed interval files by running the following command:

    gatk PreprocessIntervals --reference hg19_chr20.fa --intervals hg19_chr20.interval_list --bin-length 0 --padding 250 --interval-merging-rule OVERLAPPING_ONLY --output targets.preprocessed.500.interval_list

    Note: The input intervals are initially examined for overlapping regions, which are subsequently merged. The resulting intervals are then padded. These padded intervals are then divided into bins to prepare for coverage collection.

    Note: For targeted exome analysis, intervals can be padded by 250 bases and binning can be disabled. ‘--padding’: Specifies the length (in bp) of the padding regions on each side of the intervals. ‘--bin-length’: Specifies the length (in bp) of the bins. If set to zero, no binning will be performed.

  • c.
    Annotate genomic intervals with GC-content and mappability scores for preprocessed interval:

    gatk AnnotateIntervals --intervals targets.preprocessed.500.interval_list --reference hg19_chr20.fa --interval-merging-rule OVERLAPPING_ONLY --output targets.preprocessed.500.annotated_intervals.tsv

    Note: This process annotates intervals with GC content and, optionally, blacklisted, low-complexity genomic regions, and segmental-duplication content. The resulting output can be used as input for tools such as CollectReadCounts or GermlineCNVCaller. The annotated intervals file is a tab-separated values (TSV) file, which includes a header of sequence dictionary, a row specifying the column headers for the annotations, and the corresponding data rows.

• 2.
  Collect read counts across the training cohort BAM files.

  • a.
    Execute read count collection for each aligned sample BAM file.

    filename=$(basename ${sample_name}.bam)

    gatk CollectReadCounts --intervals targets targets.preprocessed.500.interval_list --reference $reference --interval-merging-rule OVERLAPPING_ONLY --input ${sample_name}.bam --format TSV --output $filename.readcounts.tsv

    Note: Collect read counts in above preprocess intervals from cohort for each sample WES data (in BAM format): In this step, read counts are collected at specified intervals by counting the number of read starts within each interval. The output is generated in TSV format, including a header with a sequence dictionary and the read group sample name, followed by a row that specifies the column headers and the corresponding data rows.

  • b.
    Create filtered intervals with annotations and read count statistics.

    sample_rc=$(ls ∗.readcounts.tsv | awk '{ printf “ -I %s”, $0 }')

    gatk FilterIntervals --intervals targets.preprocessed.500.interval_list --annotated-intervals targets.preprocessed.500.annotated_intervals.tsv $sample_rc --interval-merging-rule OVERLAPPING_ONLY --output gc.filtered.500.interval_list

    Note: Using specified intervals, the GC-annotated intervals from AnnotateIntervals, and the counts from CollectReadCounts, this step outputs a filtered interval list. Adjustable parameters allow for filtering based on annotations first, followed by read counts. Singleton intervals (i.e., those that are isolated on their contigs) remaining after other filters are applied will be removed. This filtered interval list can then be passed via the -L option to subsequent steps like DetermineGermlineContigPloidy and GermlineCNVCaller to exclude specific intervals from analysis.

    Note: A blacklist of regions can be specified using the -XL parameter to ensure that intervals in these regions are always filtered out, regardless of other applied filters. This list can be used to exclude telomeres, heterochromatin, centromeres from the analysis, and pseudoautosomal regions (PARs).

• 3.
  Train baseline CNV models.

  • a.
    Train the cohort ploidy model.

    grep -v 'ˆ@' targets.preprocessed.500.interval_list | awk -F“\t” '{print $1}' | uniq | awk 'BEGIN {print “CONTIG_NAME\tPLOIDY_PRIOR_0\tPLOIDY_PRIOR_1\tPLOIDY_PRIOR_2\tPLOIDY_PRIOR_3”} {print $1, 0.01, 0.01, 0.97, 0.01}' OFS=“\t” > contig_ploidy_priors.tsv

    gatk DetermineGermlineContigPloidy --intervals gc.filtered.500.interval_list --interval-merging-rule OVERLAPPING_ONLY $sample_rc --contig-ploidy-priors contig_ploidy_priors.tsv --output model --output-prefix ploidy --verbosity DEBUG

    Note: Using DetermineGermlineContigPloidy assigns a baseline copy-number state for each interval/sample, which is used to evaluate the likelihood of alternative states. If the model argument does not specify a path, the tool DetermineGermlineContigPloidy runs in COHORT mode, inferring ploidy model parameters and baseline interval ploidy states. This mode requires a TSV file with prior probabilities for each integer ploidy state and contig, specified via the contig-ploidy-priors argument. The script will first generate this TSV file, which is then used by DetermineGermlineContigPloidy. Autosomal contigs will generally assume a ploidy of 2 (with a probability set at 0.97). The X chromosome can have a ploidy of 1 or 2 based on the sample's sex, and the Y chromosome can have a ploidy of 0 or 1, also based on the sample's sex. If a path with pre-inferred ploidy model parameters is provided, the tool operates in CASE mode, which is used in the CNV calling step.

    Note: To determine the integer ploidy state of all contigs using counts data, it is necessary to model the technical coverage bias and variance for each contig. The Bayesian model and inference method implemented in DetermineGermlineContigPloidy provide mechanisms for inferring and correcting technical variation. Moreover, karyotyping confidence is dynamically adjusted for each sample and contig.

  • b.
    Train the cohort gCNV model across interval shards.

    gatk GermlineCNVCaller --run-mode COHORT --intervals gc.filtered.500.interval_list $sample_rc --contig-ploidy-calls model/ploidy-calls --annotated-intervals targets.preprocessed.500.annotated_intervals.tsv --interval-merging-rule OVERLAPPING_ONLY --output model --output-prefix baseline --verbosity DEBUG

    Note: Within the cohort (the provided training samples), each sample's read counts from step 2a,b and ploidy estimations from step 3a are fed into the GermlineCNVCaller in COHORT mode, facilitating the concurrent training of the model alongside CNV state inference. The parameter “--intervals” (-L) can be used to input a filtered interval list created by FilterIntervals to exclude specific intervals from the model. The output will generate two subdirectories: one ending with "-model" and the other with "-calls". The model subdirectory captures a snapshot of the inferred coverage model parameters, which can be applied to subsequent CNV calling in similarly sequenced samples. The calls subdirectory comprises sequentially-ordered subdirectories for each sample, each detailing various sample-specific estimates, such as the probabilities of different copy-number states for each interval, GC curve parametrization, sample-specific unexplained variance, read-depth, and loadings of coverage bias factors.

    Note:GermlineCNVCaller, when run in COHORT mode, creates a Bayesian probabilistic model based on the cohort of training samples to capture the read-count biases present in the sequencing data. The parameters generated by this model are then utilized to infer CNV states in future case samples when GermlineCNVCaller is executed in CASE mode.

Model application to CNV calling

Timing: Hours to days (factors that affect timing include the number of samples and available computing resources)

Here, we describe steps for applying the trained baseline and ploidy models to query samples for CNV detection, including copy-number state determination, raw CNV callset generation, and production of individual- and cohort-level CNV results. Following model training, the Snakemake workflow automatically performs read-count collection, contig ploidy inference, CNV calling, postprocessing, annotation, and visualization using the established cohort-specific models. Executing the Snakemake steps described above completes the model application and CNV detection process. The following code blocks are provided only to illustrate the underlying procedures and is not required for execution.

Users can perform CNV detection directly using workflow plan files automatically generated by the agent-assisted workflow utilities:

python scripts/agents/plan_agent.py \

 --sample HG00099 \

 --bam data/bam/HG00099.recal.bam \

 --out plans/HG00099.plan.yaml

snakemake --snakefile workflow/Snakefile \

 --configfile plans/HG00099.plan.yaml \

 --cores 4

The workflow outputs: genotyped interval VCFs, genotyped segment VCFs, denoised copy-ratio files, annotation reports, visualization outputs, and workflow logs and QC summaries.

• 4.
  Collect read counts for target evaluation samples.

  • a.
    Run read count collection on target BAM files using the preprocessed intervals established in Step 1.

filename=$(basename ${sample_name}.bam).

gatk CollectReadCounts --intervals targets targets.preprocessed.500.interval_list --reference $reference --interval-merging-rule OVERLAPPING_ONLY --input ${sample_name}.bam --format TSV --output ${filename}.readcounts.tsv

Note: This step is the same as Step 2a of the model training process. Users need to preprocess samples intended for CNV detection, generating BAM files to be used as input. Read counts are collected in the intervals that were used during the training phase.

• 5.
  Execute direct CNV inference on target samples using pre-trained models.

  • a.
    Determine germline contig ploidy for case samples.

    gatk DetermineGermlineContigPloidy --model model/ploidy-model --input ${filename}.readcounts.tsv --output output_dir --output-prefix ploidy-case --verbosity DEBUG

    Note: This step differs from Step 3a of the model training procedure, where DetermineGermlineContigPloidy is executed in COHORT mode to build the ploidy model. Here, the tool is run in CASE mode with the --model argument to apply the pre-trained ploidy model to query samples. The model parameters generated in Step 3a are loaded from the specified "ploidy-model" directory within the "model" directory. Using these parameters, the workflow infers contig ploidy for case samples. In CASE mode, the output is limited to the "-call" subdirectory, which follows the same directory structure as the corresponding output generated in COHORT mode.

  • b.
    Call gCNVs on target samples with the pre-trained cohort model.

    gatk GermlineCNVCaller --run-mode CASE --input ${filename}.readcounts.tsv --contig-ploidy-calls ploidy-case-calls --model model/baseline-model --output output_dir --output-prefix ${filename} --verbosity DEBUG

    Note: This step differs from Step 3b, GermlineCNVCaller, in the model training procedure, where the tool is executed in COHORT mode to generate the cohort-level baseline model. Here, GermlineCNVCaller is run in CASE mode by specifying the --run-mode CASE parameter and providing the previously generated baseline model directory through the --model argument. The baseline model is loaded from the "baseline-model" directory generated during model training and is used to infer CNV states for query samples. In CASE mode, the output consists only of the ${filename}-calls directory. Similar to the COHORT mode output, this directory contains sample-specific CNV inference results and model-derived parameters, including copy number state probabilities for each interval, GC curve parameters, unexplained variance estimates, read-depth measurements, and coverage bias factors. The genomic intervals analyzed in this step are defined by the interval file stored within the "baseline-model" directory, and all intervals specified by this file must be present in every input read-count file (${filename}.readcounts.tsv).

  • c.
    Execute PostprocessGermlineCNVCalls to merge genomic interval shards and produce sample-level VCF files.

    gatk PostprocessGermlineCNVCalls --model-shard-path model/baseline-model --calls-shard-path ${filename}-calls --allosomal-contig X --allosomal-contig Y --contig-ploidy-calls ploidy-case-calls --sample-index 0 --output-genotyped-intervals ${filename}.genotyped-intervals.vcf.gz --output-genotyped-segments ${filename}.genotyped-segments.vcf.gz --output-denoised-copy-ratios ${filename}.denoised-copy-ratios.txt --sequence-dictionary hg19_chr20.dict

    Note: This step processes the CNV calling results and generates two types of VCF files: interval-level and segment-level VCFs. These files summarize the most likely copy number states for each genomic interval, together with associated quality metrics, including the quality of integer copy number calls, assigned genotypes, and phred-scaled posterior probability vectors. Because individual CNV events often span multiple adjacent genomic intervals, neighboring intervals with identical copy number states may be merged into a single constant copy number segment.

    CRITICAL: For the two VCF outputs, CNV genotypes are assigned based on the inferred copy number state relative to the reference copy number of each contig. The alternate allele is reported as <DEL> when the inferred copy number is lower than the reference copy number and as <DUP> when the inferred copy number is higher than the reference copy number.

    CRITICAL: Allosomal contigs can be specified using the --allosomal-contig parameter, whereas all unspecified contigs are assumed to be autosomal. For allosomal contigs, the reference copy number is determined according to the sample sex karyotype and the corresponding contig ploidy state inferred by DetermineGermlineContigPloidy.

Combined gCNVs as a resource

Timing: ∼1 h depending the number of samples

Here, we describe steps for performing joint segmentation and clustering of CNV calls across multiple WES samples to facilitate cohort-level CNV interpretation and downstream analyses. After per-sample CNV calling with GATK GermlineCNVCaller in CASE mode, segmented CNV VCFs (∗.genotyped-segments.vcf.gz) from all samples are aggregated by the joint_segmentation rule. This step invokes JointGermlineCNVSegmentation through the wrapper script scripts/joint_calling.py to harmonize CNV calls across samples using a filtered interval list and optional pedigree information defined in workflow/config.yaml.

Note: The workflow generates a multi-sample clustered VCF file containing: CNV genotypes for all samples, copy-number states, allele counts (AC), allele frequencies (AF), and cohort-wide segmented CNV intervals.

• 6.
  Consolidate gCNV calls into a unified sample callset.

  • a.
    Prepare pedigree information.

    awk -F“\t” 'NR==FNR{a[$1]=1}NR>FNR && a[$2]==1{print $0}' \

    sample_names.list \

    20130606_g1k_3202_samples_ped_population.txt \

    > samples_pedigree.ped

    Note: For family-based or trio analyses, pedigree metadata can be incorporated into the joint segmentation step. Users may extract pedigree information from project metadata files or generate a PED file manually. The pedigree file path can then be specified in workflow/config.yaml.

  • b.
    Perform cohort-level joint segmentation.

    sample_vcf=$(ls ∗.genotyped-segments.vcf.gz | sed 's/ˆ/-V /')

    gatk JointGermlineCNVSegmentation \

     --reference hg19_chr20.fa \

     ${sample_vcf} \

     --model-call-intervals targets.preprocessed.500.interval_list \

     --pedigree samples_pedigree.ped \

     -O cnv_gvcf_clustered.vcf.gz

    Note: The above code blocks are provided only to illustrate the underlying procedures implemented by the Snakemake joint_segmentation rule and are not required for manual execution. After completion of sample-level CNV calling, the Snakemake workflow automatically executes JointGermlineCNVSegmentation through dedicated workflow rules. This automated process manages the collection of sample-level CNV call files and execution of the joint segmentation step, eliminating the need for manual VCF preparation and reducing the risk of execution errors.

    CRITICAL: Cohort-level CNV frequencies generated during this step can subsequently be used for false-positive filtering and pathogenicity prioritization.

Downstream annotation and visualization

Timing: ∼1-2 h depending the number of CNVs

Here, we detail the procedures for annotating raw CNV calls with genomic features, functional consequences, allele frequencies, and clinical pathogenicity classifications using public databases through AnnotSV, as well as for generating interactive visualizations, including genomic locus plots (Circos/PlotCNV), cohort-level quality metrics, and HTML-based diagnostic reports.

This step integrates AnnotSV and knotAnnotSV to annotate detected CNVs with functional annotations, pathogenicity scores, and generate interactive visual reports for clinical interpretation.

• 7.Annotate CNV using AnnotSV.

AnnotSV \

 -annotationsDir /path/to/AnnotSV_annotations \

 -SVinputFile cnv_gvcf_clustered.vcf.gz \

 -outputFile cnv_gvcf_clustered.annotated.tsv

Note: The Snakemake workflow incorporates an automated annotation framework for interpreting clustered gCNVs identified from WES data. Following joint segmentation, the clustered CNV VCF (cnv_gvcf_clustered.vcf.gz) is processed by the annotate_calls rule, which invokes AnnotSV through the wrapper script scripts/run_annotsv.py.

Note: The annotation workflow integrates multiple genomic and clinical resources configured through workflow/config.yaml, enabling comprehensive characterization of CNV events. AnnotSV summarizes genomic coordinates, overlapping genes, functional consequences, regulatory elements, known pathogenic regions, and clinically relevant annotations (Figure S1) into a tabular output file (cnv_gvcf_clustered.annotated.tsv). The workflow also supports user-defined annotation databases through the annotsv_annotations_dir parameter, allowing flexible adaptation to institution-specific or population-specific resources.

CRITICAL: To ensure compatibility with cohort-level analyses, the Snakemake workflow performs annotation after joint segmentation rather than at the single-sample stage. This design reduces redundancy among overlapping CNV calls and provides harmonized annotations for recurrent or shared CNVs across samples. The resulting annotated CNV table serves as the central resource for downstream visualization, manual review, and clinical interpretation.

The generated annotation tables include: gene-level annotations, OMIM and disease associations,¹¹ GenCC annotations,¹² haploinsufficiency scores,¹³ dosage sensitivity information,¹³ population CNV frequencies, overlaps with DGV and 1000 Genomes CNVs,^14,15 regulatory annotations,¹⁶ enhancer and promoter overlaps,¹⁶ repeat and GC-content annotations, ACMG/ClinGen-based CNV classification.^17,18

• 8.Generate interactive visual reports with knotAnnotSV.
  To facilitate interpretation of annotated gCNVs, the Snakemake workflow includes dedicated visualization modules for exploring annotation-derived genomic and clinical information. After generation of the harmonized annotation table (cnv_gvcf_clustered.annotated.tsv) using AnnotSV, the workflow supports downstream rendering of annotation-centric summaries through knotAnnotSV and related reporting utilities.

  • a.
    Convert AnnotSV TSV outputs into XLSM reports (structured knotAnnotSV format).

    perl knotAnnotSV2XL.pl \

     --configFile config_AnnotSV.yaml \

     --annotSVfile cnv_gvcf_clustered.annotated.tsv \

     --outDir output_dir \

     --outPrefix test \

     --genomeBuild hg19 \

     --LOEUFcolorRange 1 \

     --datatableDir DataTables
  • b.
    Render interactive HTML report tables for visual inspection and candidate variant prioritization.

    perl knotAnnotSV.pl \

     --configFile config_AnnotSV.yaml \

     --annotSVfile cnv_gvcf_clustered.annotated.tsv \

     --outDir output_dir \

     --outPrefix test \

     --genomeBuild hg19 \

     --LOEUFcolorRange 1 \

     --datatableDir DataTables

    Note: The above code blocks are provided only to illustrate the procedures implemented by the Snakemake visualize_knotAnnotSV rule and are not required for manual execution. As part of the workflow, the visualize_knotAnnotSV rule automatically invokes the wrapper script scripts/visualize_knotannotsv.py to generate interactive HTML reports from the annotated CNV table. These reports facilitate rapid inspection of CNV-associated genes, genomic coordinates, overlapping pathogenic regions, and annotation information integrated from external databases. All generated reports are organized under outputs/figures/knot/, enabling convenient cohort-level review and manual interpretation of CNV results.

    CRITICAL: Visualization is performed after joint segmentation and annotation to ensure that recurrent or shared CNV events are represented consistently across all samples in the cohort. This improves the interpretation of cohort-wide CNV patterns and facilitates downstream clinical review. The generated HTML reports provide interactive filtering, searchable annotation tables, database hyperlinks, color-coded pathogenicity indicators, and customizable annotation columns (Figure 1). The reports can be opened directly in modern web browsers, whereas the accompanying XLSM files can be viewed using standard spreadsheet software. The modular design of the workflow also enables users to incorporate additional annotation-aware visualization frameworks by extending the corresponding Snakemake rules.

• 9.Aggregate cohort-level CNV visualization and summary statistics.
  In addition to annotation-centric reports, the Snakemake workflow provides multiple visualization modules for exploring genome-wide CNV distributions, interval-level CNV patterns, and structural variation landscapes. These visualization components are implemented as independent Snakemake rules, allowing flexible customization and straightforward integration into downstream analyses.

  Note: The following R and Python code blocks are provided only to illustrate the procedures implemented by the corresponding Snakemake visualization rules and are not required for manual execution.

  • a.
    Interval-level CNV inspection, read-depth visualization.

    • i.
      Optional interfaces for PlotCNV.

      zcat cnv_gvcf_clustered.vcf.gz | awk '/ˆ#CHROM/{split($0,b,“\t”);};!/ˆ#/{split($3,a,“_”);OFS=“\t“;for(i=10;i<=NF;i++){if($i∼/\.\/\./){print “chr”a[2],b[i],a[3],a[4],“Gain”};if($i∼/0\/1/){print “chr”a[2],b[i],a[3],a[4],“Loss”};if($i∼/1\/1/){print “chr”a[2],b[i],a[3],a[4],“CN-LOH”}}}' >cnv_gvcf_clustered.tsv

      CNV <- read.csv(“cnv_gvcf_clustered.tsv”,sep=“\t”,header=F)

      colnames(CNV)<-c(“chr”,“sampleID”, “start.pos”, “end.pos”, “calls”)

      CNV <- prepareCNV(CNV, chr=“chr”, sampleID=“sampleID”, start.pos=“start.pos”, end.pos=“end.pos”, calls=“calls”)

      CNV <- orderCNV(CNV)

      CNV <- setPositionsCNV(CNV, genome=“hg19”, StartChrom=“chr20”,FinalChrom=“chr20”)

      CNV <- plotCopynumber(CNV, setColours = c(“Gain”=“#F8766D”, “Loss”=“#619CFF”))

      CNV@Plot$plot

      ggsave(“PlotCNV_TestPlot.png”, width=10, height=3)

      Note: The above code block demonstrates a customized implementation using PlotCNV, an R package for generating publication-quality CNV plots from segment files, and is provided only to illustrate the procedures implemented by the Snakemake plot_plotcnv rule. Manual execution is not required. This module enables customized visualization of CNV states within genomic regions of interest and supports cohort-level comparison of CNV patterns. The resulting plots resemble those shown in Figure 2A.

    • ii.
      Optional interfaces for HandyCNV.

      zcat cnv_gvcf_clustered.vcf.gz | awk '/ˆ#CHROM/{split($0,b,“\t”);};!/ˆ#/{split($3,a,“_”);OFS=“\t”;for(i=10;i<=NF;i++){split($i,c,“:”);print b[i],a[2],a[3],a[4],c[2]}}' >cnv_gvcf_clustered_handycnv.tsv

      cnv_visual(clean_cnv=cnv_gvcf_clustered_handycnv.tsv, start_position = 41,end_position = 43,chr_id=20,width_1=20,height_1=12,folder=“cnv_visual”)

      cnv_visual(clean_cnv = cnv_gvcf_clustered_handycnv.tsv, individual_id = “HG00099”, width_1 = 20, height_1 = 13, folder = “cnv_visual”)

      call_cnvr(cnv_gvcf_clustered_handycnv.tsv, chr_set = 20, folder = "cnvr")

      call_gene(refgene = “refgene/Human_hg19.txt”, interval = “cnvr/cnvr.txt”,clean_cnv = cnv_gvcf_clustered_handycnv.tsv,folder = “call_gene”)

      cnv_visual(clean_cnv=“call_gene/cnv_annotation.txt”,target_gene = “BPIFA3”,width_1=20,height_1=12,folder=“cnv_visual”)

      cnv_visual(clean_cnv=cnv_gvcf_clustered_handycnv.tsv, refgene = “refgene/Human_hg19.txt”, chr_id=20, start_position = 31,end_position = 32,col_gene = “red”,width_1=20,height_1=12,folder=“cnv_visual”)

      Note: The above code block demonstrates a customized implementation using HandyCNV, an R package for standardized CNV summarization, annotation, comparison, and visualization, and is provided only to illustrate the procedures implemented by the Snakemake handycnv_visualize rule. Manual execution is not required. The generated scripts provide comprehensive visualization of CNV patterns at the cohort, chromosomal, and gene levels (Figures 2A–2C), while also producing aggregated cohort-level summary statistics, including CNV burden, genomic distribution, and other descriptive metrics (Figures 3A–3E).

  • b.
    Genome-scale CNV visualization.

    • i.
      Optional interfaces for vcf2circos.

      option=/path/to/install/vcf2circos/Static/options.json

      vcf2circos -i ∗.genotyped-segments.vcf.gz -a hg19 -o test_vcf2circos.html -p ${option}

      Note: The above code block demonstrates a customized implementation using vcf2circos, a Python package based on Plotly for generating interactive Circos plots from VCF files, and is provided only to illustrate the procedures implemented by the Snakemake visualize_vcf2circos rule. Manual execution is not required. The generated scripts produce interactive HTML reports for genome-wide visualization of CNV distributions and copy number states. These interactive visualizations can be exported as publication-quality images, as illustrated in Figure 2D.

    • ii.
      Optional interfaces for Integrative Genomics Viewer (IGV).

      sample_name=$(zcat ∗.genotyped-segments.vcf.gz | grep -v ‘##’ | head -n1 | cut -f10)

      gatk VariantsToTable -V ∗.genotyped-segments.vcf.gz -F CHROM -F POS -F END -GF NP -GF CN -verbosity ERROR -O ${sample_name}.table.txt

      awk -v sampleName=${sample_name} 'BEGIN {FS=OFS=“\t”} {print sampleName, $0}' ${sampleName}.table.txt >${sampleName}.seg

      Note: The above code block demonstrates a customized implementation for Integrative Genomics Viewer (IGV), a fast, scalable visualization tool for genomic data and annotations. Manual execution is required. The generated files can be loaded directly into IGV for interactive visualization of genome-wide CNV profiles and copy number states. Combined with aligned sequencing reads (BAM files), these visualizations facilitate detailed inspection and validation of individual CNV events, as illustrated in Figure 2E.

    • iii.
      Optional interfaces for SegmentModel_Spy.

      awk -F“\t” 'BEGIN{print “CONTIG\tSTART\tEND\tLOG2_COPY_RATIO”}!/@|CONTIG/{$NF=log($NF)/log(2);print $0}' ∗.denoised-copy-ratios.vcf.gz >∗.denoised-copy-ratios.tsv

      Note: The above code block demonstrates a customized implementation for SegmentModel_Spy, an interactive visualization tool for GATK copy-number segmentation results. Manual execution is required. The generated files support interactive visualization of CNV segmentation results, allowing users to zoom into genomic regions of interest for detailed inspection of copy number states and segment boundaries, as illustrated in Figure 2F.

Figure 1.

Visualization of CNV annotation results

Presented here is a visual example of the CNV annotation outcomes. Users can perform this visualization by following the “Visualization of the annotation data” procedure.

Figure 2.

Depiction of CNV status

(A–F) Cohort-wide CNV status visualized, produced by Step 8b; (B) CNV status at the individual chromosome level, visualized through Step 9a-i; (C) Genomic interval CNV status, visualized using Step 9a-ii; (D) CNV status represented in a Circos plot, produced by Step 9b-i; (E) CNV status of individual chromosomes visualized with Integrative Genomics Viewer (IGV), executed in Step 9b-ii; (F) Interactive visualization of individual chromosome-level copy ratios, with input file generation in Step 9b-iii.

Figure 3.

Visualization of CNV summary

(A–E) Summary plots include aggregated CNV results categorized by length group, CNV type, chromosome, individual, and distribution at the chromosomal level, visualized through Step 9a-ii. CNV states are indicated using color coding: green for loss, red for gain, and black for mixed states.

Agent-assisted workflow management

Timing: ∼5–10 min

Here, we describe steps for using the agent-assisted workflow automation utilities in scripts/agents/to streamline sample discovery, workflow plan generation, input-file validation, execution command generation, quality-control report collection, and standardized result packaging.

To simplify workflow execution and improve reproducibility, the protocol includes a collection of agent-assisted workflow automation utilities implemented in scripts/agents/. These utilities do not perform autonomous reasoning or adaptive decision-making. Instead, they automate a series of routine workflow management tasks, including sample discovery, generation of workflow plan files, validation of input files, execution command generation, quality-control report collection, and standardized result packaging.

• 10.
  Perform agent-assisted workflow.

  • a.
    Generate a plan file.
    Plan files centralize sample metadata, BAM file paths, reference resources, model locations, and output directories.

    python scripts/agents/plan_agent.py \

    --sample HG00099 \

    --bam data/bam/HG00099.recal.bam \

    --out plans/HG00099.plan.yaml
  • b.
    Validate workflow execution.

    python scripts/agents/run_agent.py \

    --plan plans/HG00099.plan.yaml \

    --cores 4.
  • c.
    Execute workflow automatically.

    python scripts/agents/run_agent.py \

    --plan plans/HG00099.plan.yaml \

    --cores 4 \

    --execute
  • d.
    Generate QC reports.

    python scripts/agents/qc_agent.py \

    --plan plans/HG00099.plan.yaml \

    --out outputs/HG00099.qc.yaml
  • e.
    Package results for publication.

    python scripts/agents/publish_agent.py \

    --plan plans/HG00099.plan.yaml \

    --out-dir outputs/publish/HG00099 \

    --package

    Note: To facilitate reproducible workflow execution, these utilities automate routine workflow management tasks but do not perform autonomous reasoning or adaptive decision-making.

    CRITICAL: Compared with a conventional Snakemake workflow, these utilities reduce manual configuration, improve consistency of project organization, minimize user errors during repetitive setup steps, and facilitate batch processing across multiple sequencing projects.

Expected outcomes

Successful execution of this protocol generates a standardized collection of gCNV detection results, including raw CNV callsets, functional annotation tables, quality-control reports, visualization files, and cohort-level summary statistics. In addition to the analytical outputs produced by the underlying Snakemake workflow, the agent-assisted workflow utilities automatically generate workflow plan files, perform input validation, compile quality-control summaries, record execution logs, and package analysis results into a standardized project structure. These automation utilities improve workflow reproducibility, usability, and project consistency while preserving the transparency and execution logic of the underlying Snakemake pipeline. Representative examples of the final outputs are shown in Figures 1, 2, 3, 4, 5, and 6.

Figure 4.

Exon 5 heterozygous deletion in the BPIFA3 gene of HG00383 (transcript NM_178466.5)

The upper panel displays the reads distribution across the deletion interval using the Integrative Genomics Viewer (IGV), with HG00179 provided for comparison. The lower panel shows a Sashimi plot indicating the coverage depth of the corresponding genomic region.

Figure 5.

Heterozygous deletion in Exons 14–16 of the SIGLEC1 gene for HG00099 (transcript NM_023068.4)

The upper panel displays the reads distribution across the deletion interval from both WES and WGS data using the Integrative Genomics Viewer (IGV). The lower panel features a Sashimi plot indicating the coverage depth of the corresponding genomic region. HG00383 is randomly chosen for comparison with the HG00099 sample.

Figure 6.

Copy number gain in RBL1 Exons 1–12 for HG00277 (transcript NM_001323282.2)

The reads distribution and coverage depth across the duplicated region are presented, with HG00501 randomly chosen as a comparison. WGS data for HG00277 and HG00501 are included for reference.

The primary deliverables of the workflow include:

• •Raw CNV callsets, generated by the GATK-gCNV pipeline in VCF format, containing the genomic coordinates, CNV type (deletion or duplication), copy-number state, genotype information, and confidence scores for each detected event.
• •Annotated CNV tables, produced using AnnotSV, integrating gene annotations, overlap with genomic databases, ACMG evidence categories, population allele frequencies, and clinically relevant annotations. These tables serve as the primary resource for downstream variant interpretation and candidate prioritization.
• •Quality-control reports, summarizing sequencing coverage, target capture performance, workflow execution status, and cohort-level CNV statistics. These reports facilitate rapid assessment of data quality and identification of samples requiring further investigation.
• •Visualization outputs, including read-depth plots, IGV snapshots, Circos plots, and cohort summary figures, enabling manual validation of candidate CNVs and comprehensive evaluation of CNV distributions across the study cohort.
• •Workflow management outputs, automatically generated by the agent-assisted workflow utilities, including workflow plan files, input validation reports, execution logs, quality-control summaries, and standardized packaging of analysis results. These outputs facilitate project organization, execution tracking, troubleshooting, and reproducibility while maintaining compatibility with the underlying Snakemake execution engine.

The annotated CNV table represents the principal output of the protocol and should be used as the starting point for downstream biological interpretation. Candidate pathogenic CNVs can be prioritized according to gene content, predicted functional consequences, ACMG evidence, population frequency, and disease relevance with visualization of the annotated CNV table. Read-depth visualizations and IGV inspection provide complementary evidence supporting the computational CNV calls and are particularly useful for evaluating exon-level deletions or duplications before downstream validation.

In addition to the biological outputs, successful execution of the agent-assisted workflow utilities is reflected by the automatic generation of workflow management artifacts, including validated workflow plan files, execution logs, standardized directory structures, and quality-control summaries. Successful execution of the workflow can be assessed using several practical quality-control criteria. First, the Snakemake workflow should complete without failed rules or interrupted tasks, and all expected output directories should be generated successfully. Second, the final annotation files, quality-control reports, and visualization outputs should be produced without software errors. Third, sequencing coverage should be sufficient for reliable CNV detection, and quality-control reports should not indicate abnormal target coverage or excessive missing intervals. Finally, representative CNVs should exhibit read-depth patterns consistent with the predicted copy-number state in the generated visualization files. When orthogonal validation data, such as Whole Genome Sequencing (WGS), are available, representative CNVs are expected to show concordant copy-number status, providing additional support for the detected events.

Figures 1, 2, 3, 4, 5, and 6 illustrate representative outputs generated by the workflow. Figure 1 visualizes the annotated CNV list. Figure 2 demonstrates the status of detected CNVs on genomes. Figure 3 presents cohort-level CNV summaries and genomic distributions with HandyCNV (step 9a-ii). Figures 4, 5, and 6 show representative read-depth and IGV visualizations for manually reviewing candidate CNVs, including examples involving BPIFA3, SIGLEC1, and RBL1. Also, these figures illustrate representative comparisons between WES-derived CNV calls and corresponding WGS results, highlighting the expected concordance that can be achieved for high-confidence events. Together, these outputs provide a complete and reproducible framework for gCNVs discovery, annotation, visualization, quality assessment, and downstream interpretation from whole-exome sequencing data. The accompanying agent-assisted workflow utilities further automate routine workflow management tasks including workflow planning, input validation, quality-control summarization, execution logging, and standardized result packaging, thereby improving workflow reproducibility and usability without replacing the underlying Snakemake execution engine.

Quantification and statistical analysis

To improve CNV detection accuracy, we suggest filtering out false positives by analyzing CNV frequencies within the studied cohort. Frequently identified CNVs in certain regions are often attributable to sequencing bias, whereas rare CNV regions are more likely to represent true positives. We propose that CNV frequencies within a large cohort should follow a normal distribution. Typically, CNVs with frequencies significantly exceeding the 95% confidence interval of the cohort’s overall distribution are considered less reliable. Additionally, CNV annotation combined with existing databases that link CNV frequency and pathogenicity can further refine the filtering process.

Limitations

While this protocol provides an automated, reproducible workflow for gCNVs discovery from WES data, several inherent limitations remain. Primarily, WES is less optimal for clinical CNV detection compared to WES because CNV breakpoints often lie in non-coding intronic or intergenic regions outside the targeted exons, while typical short read lengths further hamper exact breakpoint identification. Consequently, CNV calling relies heavily on target capture depth, making performance highly susceptible to sequencing biases, low-mappability zones, high GC-content regions, and batch effects introduced by DNA capture technologies and sequencing procedures. Benchmark studies on real-world WES data consistently report low sensitivity and recall across existing computational tools, leading to a noticeable rate of false positives. In practice, high-frequency CNVs in 5′UTR-CDS, CDS-3′UTR, or UTR regions frequently arise from systematic sequencing bias and require frequency-based filtering, while improper CNV merging may split contiguous non-overlapping regions and necessitate manual or plot-based inspection. Indeed, our validation on 1000 Genomes Project data revealed that several CNVs initially deemed true positives were confirmed as false positives when evaluated against whole-genome sequencing ground truth (see the supplemental materials for false-positive cases). Additionally, cohort-based baseline model training requires a minimum number of high-quality control samples under identical capture kits to establish stable read-depth expectations, constraining single-sample processing without pre-trained cohort references. To mitigate these challenges, users should validate CNV reliability across larger cohort datasets to reduce false positives and consider developing downstream machine learning models to further refine candidate variant prioritization.

Troubleshooting

Problem 1

Select the appropriate genome version before executing this protocol. This pertains to the data preprocessing outlined in the ‘before you begin’ section, as well as the Baseline CNV Model Training steps.

Potential solution

The genome version chosen during the WES data preprocessing mapping step dictates the genome version for all subsequent reference files in this protocol. While the protocol is flexible regarding genome versions, maintaining consistency throughout the entire procedure is crucial. Different genome versions have a negligible effect on CNV detection rates; however, for accurate CNV annotation using databases, we advise using the widely accepted human genome versions GRCh37 and GRCh38.

Problem 2

In the “Prepare the software environment” step, differences in software dependencies and installation requirements among GATK releases may lead to installation failures or compatibility issues. During CNV model training, changes to the gcnvkernel Python module across GATK versions may also affect training parameters and model performance. In addition, some GATK releases do not support sample names shorter than four characters, which can cause model training to fail.

Potential solution

GATK is actively maintained, and newer releases frequently resolve installation, compatibility, and functionality issues present in earlier versions. If installation or model training problems occur, we recommend using the latest stable GATK release rather than the default version specified in key resources table, provided that compatibility with the remaining workflow components is maintained. Users should also ensure that sample names contain at least four characters before initiating model training.

Problem 3

Strategies for genetic screening of individual CNV results involve methods to exclude false positives and enhance screening efficiency.

Potential solution

CNV detection accuracy is strongly influenced by the characteristics of the input WES data, including the sequencing institution, sequencing platform, and target capture technology. To minimize technical bias, we recommend using control samples generated with the same sequencing platform, sequencing center, and capture kit for both baseline model training and CNV detection. If matched control data are unavailable, increasing the size and diversity of the training cohort can improve model robustness across different sequencing conditions. In addition, aggregating individual CNV calls into a cohort-level callset and annotating variants with population and clinical databases enables frequency- and annotation-based filtering, thereby reducing false positives and improving the prioritization of candidate CNVs.

Problem 4

Reduced sensitivity for detecting exon-level or smaller CNVs.

Potential solution

Detection of small CNVs depends on the resolution of the baseline model and interval design. To improve sensitivity for exon-level CNVs, we recommend training the model using intervals optimized for smaller events. During the CNV model training stage, reducing the --padding parameter can increase breakpoint resolution and improve the detection of small CNVs. However, smaller padding values may also increase sensitivity to technical noise, so parameter optimization should be performed according to the sequencing data quality and target capture design.

Problem 5

CNV model training is computationally intensive and requires a long execution time.

Potential solution

To improve computational efficiency, we recommend training baseline models separately for each chromosome, allowing multiple training jobs to run in parallel. The resulting chromosome-specific models can then be applied independently and integrated during the CNV detection stage. This strategy substantially reduces overall runtime while maintaining detection performance.

Problem 6

The Snakemake workflow fails to execute because of missing rule dependencies, incorrect file paths, or incomplete workflow plan files.

Potential solution

Ensure that the workflow is executed from the Identify_gCNV_with_WES/directory and that all file paths specified in workflow/config.yaml and the workflow plan (∗.plan.yaml) are correct and accessible. Before running the workflow, perform a Snakemake dry run:

snakemake --snakefile workflow/Snakefile --configfile plans/EXAMPLE.plan.yaml -n

This command validates the workflow graph, rule dependencies, input/output files, and expected execution plan without running any jobs, allowing users to identify configuration errors before actual execution.

Resource availability

Lead contact

Further information and requests for resources should be directed to and will be fulfilled by the lead contact, Xiang Chen (xiang-chen@zju.edu.cn).

Technical contact

Technical questions about the execution of this protocol or code implementation should be directed to the technical contact, Xiang Chen (xiang-chen@zju.edu.cn).

Materials availability

This study did not generate new biological materials. Pre-trained baseline and ploidy models used for gCNVs detection are distributed within the repository under the model/directory.

Data and code availability

The complete Snakemake workflow, Conda environment specification, Docker configuration, documentation, and example datasets are publicly available through GitHub (https://github.com/model-lab/Identify_gCNV_with_WES) and Zenodo (https://zenodo.org/records/19489460). All software versions used in this protocol are listed in the key resources table. Future updates to the workflow will be maintained through the GitHub repository. The WES data utilized in this protocol are sourced from the 1KGP Phase 3. The corresponding data paths are available in our GitHub repository, allowing users to download these data from the FTP server at ftp.1000genomes.ebi.ac.uk.

Acknowledgments

This work was supported by the Joint Fund of the Zhejiang Provincial Natural Science Foundation of China (grant no. LMRY26H200005) and the Quzhou Municipal Government (grant no. 2024D009). Computational resources were provided by the High-Performance Computing Center at Westlake University. We thank the International Genome Sample Resource (IGSR) and the 1000 Genomes Project (1kGP) for providing publicly available genomic data. We also thank Dr. Quan Zou for his valuable assistance with the conceptualization of this study.

Author contributions

X.C., writing – review and editing, writing – original draft, visualization, validation, supervision, software, resources, project administration, methodology, funding acquisition, formal analysis, data curation, and conceptualization.

Declaration of interests

The authors declare no competing interests.