Skip to content
BranchesTags

Repository files navigation

IMPACT-CNV

IMPACT-CNV is an extension of the SCIP (Suite for CNV Interpretation and Prioritization) tool developed by Ding et al. (2023). IMPACT-CNV builds upon SCIP by providing additional scripts and workflows to prioritize and filter copy number variants (CNVs) affecting genes linked to user-specified traits of interest. The workflow integrates CNV calling, annotation, prioritization, and visualization, streamlining the identification of clinically relevant CNVs for downstream analysis and reporting.

Outputs are formatted for direct integration with IMPACT-VIS.

We gratefully acknowledge the SCIP authors for their foundational work. Please cite both the SCIP publication and repository, as well as the IMPACT paper, if you use this tool in your research.

Table of Contents

Overview

IMPACT-CNV consists of four main steps that transform CNV VCF files into curated, IMPACT-VIS-ready output files:

┌──────────────────────────────────────────────────────────────────────────────────────┐
│  CNV VCF Files  ──►  Step 1  ──►  Step 2  ──►  Step 3  ──►  Step 4  ──►  IMPACT-VIS  │
│  (*.cnv.vcf)        Convert      SCIP        Manual       Export      Visualization  │
│                     to SCIP      Backend     Review       to IMPACT                  │
└──────────────────────────────────────────────────────────────────────────────────────┘
Step Purpose Input Output
1 Convert VCF to SCIP format *.cnv.vcf / *.cnv.vcf.gz <sample_id>.unfiltered_CNV.txt
2 Annotate and prioritize CNVs Unfiltered CNV files + annotations <sample_id>.pipeline_summary.txt
3 Manual review and curation Pipeline summary + BAM/CRAM SCIP_results.txt
4 Export for IMPACT-VIS SCIP_results.txt <sample_id>_CNV_IMPACT.txt

⚠️ Important: Data Handling and Security

This repository contains analysis code only. Patient sequencing data (VCF, CRAM, BAM files), analysis outputs, and configuration files with local paths should never be committed to this repository.

All sensitive data is automatically protected by .gitignore. See SECURITY.md for detailed guidelines.

Data to Keep Local (Not Committed)

  • Sample VCF/CRAM/BAM files
  • Output CNV files
  • Configuration files with local paths
  • Temporary and cache files

Safe to Commit

  • Python, Perl, and R scripts
  • Configuration templates (.template files)
  • Documentation

Requirements

Software Dependencies

Software Version Purpose
Python 3 3.6+ VCF conversion and output generation
Perl 5.x SCIP backend processing
R 4.0+ Visualization interface
samtools 1.10+ BAM/CRAM file handling
tabix 0.2.6+ Indexed file access

Python Packages

pip install pandas

R Packages

install.packages(c("shiny", "DT", "plotrix"))

Required Data Files

File Source Location
hg38 annotation files SCIP setup instructions Step2_SCIP_backend/hg38_files/
genemap2.txt OMIM Downloads (registration required) Step2_SCIP_backend/hg38_files/
Reference FASTA (GRCh38/hg38) UCSC/Ensembl/NCBI Step2_SCIP_backend/REF_BAM/REF_FA/
Control sample CRAM/CRAI (e.g., NA12878) 1000 Genomes / your source Step2_SCIP_backend/REF_BAM/

Quick Start

# 1. Clone the repository
git clone https://github.com/boehlernick/IMPACT-CNV.git
cd IMPACT-CNV

# 2. Place your CNV VCF files in Step1 directory and convert
cd Step1_SCIP_vcf_input_conversion
cp /path/to/your/*.cnv.vcf.gz .
python3 convert_to_scip.py

# 3. Configure and run SCIP backend (after setting up annotation files)
cd ../Step2_SCIP_backend
# Copy templates, then edit pipeline_config_hg38.txt and sample_ids.txt
cp pipeline_config_hg38.txt.template pipeline_config_hg38.txt
cp sample_ids.txt.template sample_ids.txt
perl SCIP_backend_hg38.pl -n <sample_id>

# 4. Launch visualization interface for manual review
cd ../Step3_SCIP_Visualization
# Edit interface_config.txt with your sample ID
Rscript -e "shiny::runApp('SCIP_interface_hg38.R')"

# 5. Export results for IMPACT-VIS
cd ../Step4_SCIP_to_IMPACT_outputs
python3 scip_results_to_impact_splitter.py
# Output: <sample_id>_CNV_IMPACT.txt files ready for IMPACT-VIS

Detailed Workflow

Step 1: VCF Input Conversion

Directory: Step1_SCIP_vcf_input_conversion/

Purpose: Converts CNV-containing VCF files into SCIP-compatible tab-delimited text files.

Input Requirements

  • File format: VCF 4.1+ containing CNV calls
  • Required INFO fields: END=<position> and SVTYPE=DEL or SVTYPE=DUP
  • Supported extensions: .vcf, .vcf.gz, .cnv.vcf, .cnv.vcf.gz

Usage

cd Step1_SCIP_vcf_input_conversion

# Default: extract sample ID from filename prefix
python3 convert_to_scip.py

# Use underscore delimiter, take first field as sample ID
python3 convert_to_scip.py --split-delim "_" --split-index 0

# Use regex to extract sample ID
python3 convert_to_scip.py --sample-regex "^(?P<id>[^_]+)"

Output

One file per sample saved to Step2_SCIP_backend/user_data/:

  • Filename: <sample_id>.unfiltered_CNV.txt
  • Format: Tab-delimited, no header
  • Columns: Chromosome, Start_Position, End_Position, CNV_Type, Quality, Filter, Sample_ID

Example

Input File Extracted Sample ID Output File
SAMPLE001.cnv.vcf.gz SAMPLE001 SAMPLE001.unfiltered_CNV.txt
patient_123_dragen.cnv.vcf patient (default) or patient_123 (with regex) patient.unfiltered_CNV.txt

Step 2: SCIP Backend Configuration and Execution

Directory: Step2_SCIP_backend/

Purpose: Annotates, prioritizes, and filters CNVs based on gene relevance, phenotype association, and quality metrics.

Setup Checklist

  1. Annotation files → hg38_files/

  2. Reference genome → REF_BAM/REF_FA/

    • GRCh38/hg38 FASTA file with index

  3. Control sample → REF_BAM/

    • CRAM and CRAI files (e.g., NA12878)

  4. Sample alignments → samples/

  5. Gene list → hg38_files/demo/candidate_gene_list_demo.txt

    • One gene symbol per line
    • Same gene list used in IMPACT-SNV and IMPACT-SV workflows

  6. Configuration → pipeline_config_hg38.txt

    • Verify all PATH variables are correctly set

  7. Sample IDs → sample_ids.txt

    • List sample IDs to process (one per line)

Template available: sample_ids.txt.template

To get started:

cp Step2_SCIP_backend/sample_ids.txt.template Step2_SCIP_backend/sample_ids.txt
# Edit with your real sample IDs (do not commit)

Configuration File (pipeline_config_hg38.txt)

Template available: pipeline_config_hg38.txt.template

To get started:

cp Step2_SCIP_backend/pipeline_config_hg38.txt.template Step2_SCIP_backend/pipeline_config_hg38.txt
# Edit with your local paths

Key parameters to verify:

SAMPLE_ID       ./sample_ids.txt
CURRENT_PATH    .
ALIGNMENT_PATH  ./samples
REF_BAM         ./REF_BAM/NA12878.final.cram
gene_interest   ./hg38_files/demo/candidate_gene_list_demo.txt
OMIM            ./hg38_files/genemap2.txt

Execution

cd Step2_SCIP_backend
perl SCIP_backend_hg38.pl -n <sample_id>

Output

  • user_data/<sample_id>.hg38.pipeline_summary.txt — Prioritized CNV list for visualization
  • user_data/<sample_id>.hg38.variant_list.txt — Intermediate variant annotations

Step 3: CNV Visualization and Review

Directory: Step3_SCIP_Visualization/

Purpose: Interactive R Shiny application for expert curation of prioritized CNVs. Manual review is essential due to the high false positive rate of CNV calling from short-read sequencing data.

Why Manual Review?

Automated prioritization alone cannot reliably distinguish true CNV events from technical artifacts. The visualization interface enables:

  • Read depth assessment — Confirm deletions/duplications by coverage patterns
  • Mapping quality evaluation — Exclude low-quality or ambiguous regions
  • Control comparison — Compare to NA12878 or other controls to identify common artifacts
  • Supporting evidence — Evaluate split reads and discordant pairs

Configuration

Template available: interface_config.txt.template

To get started:

cp Step3_SCIP_Visualization/interface_config.txt.template Step3_SCIP_Visualization/interface_config.txt
# Edit with your sample ID and username

Edit interface_config.txt:

LIST_NAME       <sample_id>.hg38
TEMP_FILE_DIR   ./app_temp_file/
ROOT_DIR        ./
USER            <your_username>

Launch

cd Step3_SCIP_Visualization
Rscript -e "shiny::runApp('SCIP_interface_hg38.R')"

Or in RStudio:

setwd("Step3_SCIP_Visualization")
shiny::runApp("SCIP_interface_hg38.R")

Review Interface Features

Feature Description
CNV Selector Navigate through prioritized CNVs
Read Depth Plot Visualize coverage across the CNV region
Mapping Quality Assess alignment confidence
Anomalous Reads View supporting/opposing paired-end evidence
Determination Dropdown Assign review status to each CNV

Determination Options

Category Options
Further Review Further Review - Potentially Reportable, Further Review - Not Likely Reportable
Ruled Out Quality Inadequate, Population Variation, No Gene of Interest, Incorrect Boundary, Non-intragenic DUP, Other Reasons
Deferred Recessive Gene - Look for Compound Het SNV
Other Already Interpreted, Not Evaluated

Output

All review decisions are saved to SCIP_results.txt with the following columns:

Column Description
Timestamp Unix timestamp of review
CNV Name Format: <sample_id>.<chr>.<start>.<end>.<type>
Quality Override Manual quality assessment
Determination Review decision
Comment Free-text notes
DateTime Human-readable timestamp
Username Reviewer ID

Step 4: Output Preparation for IMPACT-VIS

Directory: Step4_SCIP_to_IMPACT_outputs/

Purpose: Converts curated SCIP results into the format required by IMPACT-VIS.

Execution

cd Step4_SCIP_to_IMPACT_outputs
python3 scip_results_to_impact_splitter.py

Input

  • ../Step3_SCIP_Visualization/SCIP_results.txt

Output

One file per sample in the current directory:

  • Filename: <sample_id>_CNV_IMPACT.txt
  • Format: Tab-delimited text file containing all reviewed CNVs for that sample
  • Content: Filtered rows from SCIP_results.txt grouped by sample ID

Integration with IMPACT-VIS

The <sample_id>_CNV_IMPACT.txt files generated in Step 4 are ready for direct use with IMPACT-VIS.

IMPACT-VIS Input Files

Variant Type File Format Source Module
SNV/Indel <sample_id>_SNV_IMPACT.gds IMPACT-SNV
Structural Variants <sample_id>_SV_IMPACT.tsv IMPACT-SV
Copy Number Variants <sample_id>_CNV_IMPACT.txt IMPACT-CNV

Loading CNV Data in IMPACT-VIS

  1. Launch the IMPACT-VIS R Shiny application
  2. Upload or specify path to <sample_id>_CNV_IMPACT.txt
  3. CNVs will be displayed alongside SNVs and SVs in the integrated visualization

Visual Distinction in IMPACT-VIS

  • CNVs marked as "Further Review - Potentially Reportable" are displayed with full opacity for visual emphasis
  • CNVs with other determinations are displayed with reduced opacity

File Naming Conventions

Consistent file naming across all steps is critical for the pipeline to function correctly.

Naming Pattern

File Type Naming Convention Example
CNV VCF <sample_id>.cnv.vcf or <sample_id>.cnv.vcf.gz SAMPLE001.cnv.vcf.gz
Sample CRAM <sample_id>.cram SAMPLE001.cram
Sample CRAI <sample_id>.cram.crai or <sample_id>.crai SAMPLE001.cram.crai
Unfiltered CNV <sample_id>.unfiltered_CNV.txt SAMPLE001.unfiltered_CNV.txt
IMPACT Output <sample_id>_CNV_IMPACT.txt SAMPLE001_CNV_IMPACT.txt

Sample ID Extraction

The sample ID is extracted from the VCF filename in Step 1. Use the appropriate option to match your naming scheme:

# Filename: SAMPLE001.cnv.vcf.gz → Sample ID: SAMPLE001 (default)
python3 convert_to_scip.py

# Filename: patient_001_dragen.cnv.vcf → Sample ID: patient
python3 convert_to_scip.py --split-delim "_" --split-index 0

# Filename: WGS-2024-001.cnv.vcf → Sample ID: WGS-2024-001
python3 convert_to_scip.py --sample-regex "^(?P<id>WGS-\d{4}-\d{3})"

Troubleshooting

Common Issues

Issue Cause Solution
ERROR: SCIP_results.txt not found Step 3 not completed Complete manual review in visualization interface
No CNVs in output All CNVs filtered Check filter settings; review pipeline_summary.txt
Sample ID mismatch Inconsistent naming Verify VCF and CRAM filenames match
Visualization won't load Missing dependencies Install R packages: shiny, DT, plotrix
SCIP backend fails Incorrect paths Verify all paths in pipeline_config_hg38.txt

Validation Checklist

  • VCF files contain END= and SVTYPE= in INFO field
  • Sample IDs are consistent across VCF and CRAM files
  • All annotation files are present in hg38_files/
  • genemap2.txt downloaded from OMIM
  • Reference FASTA matches the alignment reference
  • pipeline_config_hg38.txt paths are correct

Citation

If you use IMPACT-CNV in your research, please cite:

IMPACT:

[Citation pending publication]

SCIP:

Ding, Y., et al. (2023). "SCIP: a scalable and customizable pipeline for rare CNV prioritization in clinical genome interpretation." Human Genetics, 142(4), 495–508. https://doi.org/10.1007/s00439-022-02494-1

Related Repositories

About

CNV Preprocessing for IMPACT Variant Analysis

Resources

Readme
GPL-3.0 license

Security policy

Security policy
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages