🧬 Transcript Handling Modes

VCF files with VEP annotations often contain multiple transcript annotations per variant. Choose the strategy that fits your analysis:

🎯 Most Severe (--transcript-handling most-severe)

Best for: Clinical analysis, variant prioritization ```shell script vcf-reformatter input.vcf.gz -t most-severe

for maf output

vcf-reformatter input.vcf.gz -t most-severe --output-format maf ``` Selects the transcript with the most severe consequence (stopgained > missensevariant > synonymous, etc.)

⚡ First Only (--transcript-handling first) [Default]

Best for: Quick analysis, performance-critical workflows shell script vcf-reformatter input.vcf.gz # Uses first transcript by default

Processes only the first transcript annotation (fastest option)

📊 Split All (--transcript-handling split)

Best for: Comprehensive analysis, transcript-level studies shell script vcf-reformatter input.vcf.gz -t split Creates separate rows for each transcript (most detailed output)

📈 Performance

Benchmarks

• Small files (< 1K variants): ~5,000 variants/sec
• Medium files (1K-10K variants): ~15,000 variants/sec
• Large files (10K+ variants): ~30,000 variants/sec

Optimization Tips

```shell script

Auto-detect optimal thread count

vcf-reformatter input.vcf.gz -j 0

For files > 10K variants, use parallel processing

vcf-reformatter input.vcf.gz -t most-severe -j 0 -v

Combine with compression for large outputs

vcf-reformatter input.vcf.gz -t split -j 0 -c -v ```

📊 Output Format

File Structure

VCF Reformatter generates two files: - {prefix}_header.txt - Original VCF header and metadata - {prefix}_reformatted.tsv - Flattened tabular data

Column Types

1. Standard VCF: CHROM, POS, ID, REF, ALT, QUAL, FILTER
2. INFO Fields: INFO_DP, INFO_AF, INFO_AC, etc.
3. VEP Annotations: CSQ_Allele, CSQ_Consequence, CSQ_SYMBOL, CSQ_Gene, etc.
4. SnpEff Annotations: ANN_Allele, ANN_Annotation_Impact, ANN_Gene_Name, ANN_Distance, etc.
5. Sample Data: SAMPLE1_GT, SAMPLE1_DP, SAMPLE1_AD, etc.

Example Output VEP

CHROM POS ID REF ALT QUAL FILTER INFO_DP CSQ_Consequence CSQ_SYMBOL SAMPLE1_GT chr1 69511 . A G 1294.53 PASS 65 missense_variant OR4F5 1/1 chr1 69761 rs123 C T 892.15 PASS 42 synonymous_variant OR4F5 0/1

Example Output SnpEff

CHROM POS ID REF ALT QUAL FILTER INFO_DP ANN_Annotation ANN_Gene_Name SAMPLE1_GT chr1 69761 rs587 C T 730 PASS . 214 synonymous_variant OR4F5 0/1 chr1 924024 . A G 53 PASS . 409 5_prime_UTR_variant SAMD11 1/1

🔧 Integration Examples

With R

```textmate

Read compressed output directly

library(data.table) data <- fread("output_reformatted.tsv.gz")

Quick variant summary

summary(data$CSQ_Consequence) ```

With Python

```textmate import pandas as pd

Load and analyze

df = pd.readcsv("outputreformatted.tsv.gz", sep="\t", compression="gzip") df['CSQConsequence'].valuecounts() ```

In Workflows

```shell script

Nextflow pipeline

vcf-reformatter ${vcf} -t most-severe -j ${task.cpus} -o results/ -c

Snakemake rule

shell: "vcf-reformatter {input.vcf} -t most-severe -j {threads} -o {params.outdir} -c" ```

🐳 Container Usage

Docker

```shell script

Build once

docker build -t vcf-reformatter .

Run anywhere

docker run --rm \ -v $(pwd):/data \ vcf-reformatter \ /data/input.vcf.gz \ -t most-severe -j 4 -o /data/results/ -c ```

Singularity (HPC)

```shell script

On HPC cluster

singularity run \ --bind $PWD:/data \ --bind /scratch:/scratch \ vcf-reformatter.sif \ /data/large_cohort.vcf.gz \ -t most-severe -j 16 -o /scratch/results/ -c -v ```

🧪 Use Cases

| Use Case | Command | Why It Works | |----------|---------|--------------| | Clinical Variant Review | vcf-reformatter variants.vcf.gz -t most-severe | Prioritizes clinically relevant consequences | | Population Analysis | vcf-reformatter cohort.vcf.gz -t first -j 0 -c | Fast processing of large cohorts | | Transcript Studies | vcf-reformatter genes.vcf.gz -t split -v | Comprehensive transcript-level analysis | | Quick Data Exploration | vcf-reformatter sample.vcf.gz | Simple, fast conversion for immediate analysis | | HPC Batch Processing | vcf-reformatter huge.vcf.gz -t most-severe -j 32 -c | Optimized for high-performance computing |

🚀 What's New in v0.3.0

• ✅ MAF Output Support (in Beta⚠️) - Direct conversion to Mutation Annotation Format
• ✅ Auto-metadata Detection (in Beta⚠️) - Extracts center/sample info from VCF headers for MAF
• ✅ Memory-Efficient Processing (streaming) - Chunked streaming for large files (>>100K variants)
• ✅ Enhanced Error Handling - Better processing of malformed files
• ✅ Comprehensive Testing - 70+ test cases ensure reliability

Previous Releases

🚀 What's New in v0.2.0

• ✅ SnpEff Support - Full ANN field parsing with intelligent detection
• ✅ Smart Auto-Detection - Automatically identifies VEP vs SnpEff annotations
• ✅ Enhanced Error Handling - Better processing of malformed or headerless files

TODOs

• ~~Add SnpEff support✅~~
• ~~Output MAF format option✅~~
• Add stdin to combine with other tools, such as bcftools
• Support for multi-sample VCF files in MAF output

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Add tests for new functionality
4. Commit your changes: git commit -am 'Add feature'
5. Push to the branch: git push origin feature-name
6. Submit a pull request

Development Setup

shell script git clone https://github.com/flalom/vcf-reformatter.git cd vcf-reformatter cargo test # Run the test suite cargo run -- data/sample.vcf.gz -v # Test with sample data

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• VCF Format Contributors - For the standard that enables genomic data sharing
• VEP Team - For the powerful variant annotation framework
• Rust Community - For the incredible ecosystem that makes this possible
• Bioinformatics Community - For feedback and feature requests

Frequently Asked Questions

Q: Which transcript handling mode should I use?

• Clinical analysis: --transcript-handling most-severe
• Quick exploration: --transcript-handling first
• Comprehensive analysis: --transcript-handling split

Q: How does this compare to other VCF tools?

VCF Reformatter is specifically designed for: - Converting complex VEP/SnpEff annotations to tabular format - Handling multiple transcripts intelligently - High-performance parallel processing - Easy integration with R/Python workflows

Q: Can I use this in production pipelines?

Yes! VCF Reformatter is designed for production use with: - Comprehensive error handling - Docker/Singularity support - Automated testing - Stable CLI interface

Q: What's the difference between TSV and MAF output?

• TSV: Direct flattening of VCF fields (default)
• MAF (beta): Standardized cancer genomics format for downstream tools

Q: What if I get out-of-memory errors?

• Use TSV format instead of MAF: vcf-reformatter file.vcf.gz -j 0 -c
• Enable verbose mode to monitor: vcf-reformatter file.vcf.gz -v

📞 Support

• 📋 Issues: GitHub Issues
• 📧 Email: fl@flaviolombardo.site