FFPE Mutation Analysis Pipeline

A comprehensive pipeline for analyzing FFPE (Formalin-Fixed Paraffin-Embedded) tissue mutation data, including VCF processing, mutation counting, and signature analysis.

📋 Table of Contents

• Overview
• Prerequisites
• Installation
• Usage
• Scripts
• Output
• Testing
• Example Workflow
• Contributing
• License
• References

🔍 Overview

This pipeline processes VCF files containing mutation data from FFPE samples and performs:

• VCF format conversion and validation
• Mutation counting and analysis
• FFPE signature analysis for both repaired and unrepaired samples
• Generation of mutation matrices and visualizations

🛠️ Prerequisites

Before running the pipeline, ensure you have the following installed:

System Dependencies

# Install htslib for VCF processing
brew install htslib

# Install wget for downloading reference genomes
brew install wget

Python Environment

# Create and activate Python 3.10 environment
conda create -n py310env python=3.10
conda activate py310env

# Install required Python packages
conda install -c bioconda pyfaidx
conda install -c bioconda cyvcf2
conda install -c bioconda pandas
conda install -c bioconda numpy
conda install -c bioconda scipy
conda install -c bioconda matplotlib
conda install -c bioconda seaborn
conda install -c conda-forge scikit-learn
conda install -c bioconda scikit-image

Download Reference Genome

# Download hg19 reference genome
wget http://hgdownload.cse.ucsc.edu/goldenPath/hg19/bigZips/hg19.fa.gz
gunzip hg19.fa.gz

Optional: GDC Client Setup

# Download GDC client for TCGA data access
wget https://gdc.cancer.gov/files/public/file/gdc-client_v1.6.0_Ubuntu_x64.zip
unzip gdc-client_v1.6.0_Ubuntu_x64.zip
chmod +x gdc-client

🚀 Usage

1. VCF Conversion (optional)

Convert your VCF files to the required format:

python convert_vcf.py input.vcf output_adj.vcf

2. Mutation Analysis

Process VCF files to generate mutation counts:

python scripts/mutation.py --input input.vcf --reference genome_files/hg19.fa --output output_counts.tsv

3. FFPE Signature Analysis

Single Sample Analysis

Run signature analysis for a unrepaired sample:

python scripts/FFPEsig.py -i mutation_matrix.csv -o mutation_corrected_outputs_unrepaired/ -s sample_name -l Unrepaired

Run signature analysis for a single repaired sample:

python scripts/FFPEsig.py -i mutation_matrix.csv -o mutation_corrected_outputs_repaired/ -s sample_name -l Repaired

Batch Processing (All Samples)

Process all samples in the mutation matrix automatically:

For Unrepaired Samples:

python scripts/FFPEsig_batch.py -i results/mutation_matrix.csv -l Unrepaired -o mutation_corrected_outputs_unrepaired

For Repaired Samples:

python scripts/FFPEsig_batch.py -i results/mutation_matrix.csv -l Repaired -o mutation_corrected_outputs_repaired

📁 Scripts

Core Analysis Scripts

• mutation.py: Main mutation counting and analysis script
• FFPEsig.py: FFPE signature analysis for single samples (repaired/unrepaired)
• FFPEsig_batch.py: Batch FFPE signature analysis for all samples in a matrix
• convert_vcf.py: VCF format conversion and validation
• combine_mutation_counts.py: Combine multiple mutation count files

Utility Scripts to get more FFPE data from TCGA (which requires authorization)

• get_tcga.py: Download TCGA data
• vcfdownload.py: Download VCF files

📊 Output

The pipeline generates several types of output:

Mutation Counts

• Individual sample mutation count files (.tsv format)
• Combined mutation matrix (mutation_matrix.csv)

Signature Analysis

• Unrepaired samples: mutation_corrected_outputs_unrepaired/
• Repaired samples: mutation_corrected_outputs_repaired/

Batch Processing Output

When using FFPEsig_batch.py, the following files are generated for each sample:

• {sample_id}_corrected_profile.csv - Corrected mutation profile
• {sample_id}_all_solutions.csv - All optimization solutions
• {sample_id}_before_correction.pdf - Plot of original profile
• {sample_id}_after_correction.pdf - Plot of corrected profile
• all_samples_corrected_matrix.csv - Combined corrected matrix for all samples

Visualizations

• Heatmaps (heatmap.png) generated by heatmap.py

🧪 Testing

The pipeline includes comprehensive test suites to validate functionality:

Running Tests

# Run the main test suite using the sample file provided by the FFPE author
# The test compares the results of VCF to mutation count conversion to results by the author
# Test to make sure that mutation counts are handled the same way as the Nature paper
python test_vcf_pipeline.py

Test Coverage

The test_vcf_pipeline.py file includes tests for:

• VCF format conversion: Validates VCF file structure and conversion
• Mutation counting: Tests mutation counting functionality (requires reference genome)
• Command line interfaces: Tests CLI functionality of all scripts
• Complete workflow: End-to-end pipeline testing
• VCF validation: Format and structure validation

Test Requirements

• Test data: Located in test_data/ directory
• Reference genome: genome_files/hg19.fa (for full mutation counting tests)
• Dependencies: All required Python packages (cyvcf2, pyfaidx, biopython, etc.)

Test Results

Tests will gracefully handle missing dependencies and provide helpful error messages:

• ✅ Available modules: Tests will run normally
• ⚠️ Missing dependencies: Tests will be skipped with installation instructions
• ❌ Missing files: Tests will be skipped with file location information

📝 Example Workflow

Here's a complete example workflow (processing BRP dataset):

# 1. Generate mutation counts from VCF files in BRP dataset
/Users/tarafriedrich/Documents/GitHub/ffpe_code/scripts/combine_mutation_counts.py 

# 2. Run signature analysis (single sample)
python scripts/FFPEsig.py -i mutation_matrix.csv -o mutation_corrected_outputs_unrepaired/ -s BRP_24_G_13 -l Unrepaired
python scripts/FFPEsig.py -i mutation_matrix.csv -o mutation_corrected_outputs_repaired/ -s BRP_24_G_13 -l Repaired

# 3. Run batch signature analysis (all samples)
python scripts/FFPEsig_batch.py -i results/mutation_matrix.csv -l Unrepaired -o mutation_corrected_outputs_unrepaired
python scripts/FFPEsig_batch.py -i results/mutation_matrix.csv -l Repaired -o mutation_corrected_outputs_repaired

🤝 Contributing

This pipeline is designed for FFPE mutation analysis. Please ensure your input VCF files are properly formatted and contain the required mutation information.

📄 License

This project is for research purposes. Please cite appropriately if used in publications.

📚 References

Data Sources

• FFPE Mutation Analysis Paper - Genome Biology publication on FFPE mutation analysis
• BRP FFPE Dataset - Figshare dataset containing BRP FFPE VCF files and panel bed files

FFPE Signature Analysis

• FFPE Signature Paper - Nature Communications publication on FFPE signatures
• FFPEsig GitHub Repository - Original FFPEsig tool implementation