# VCF Preprocessing User Guide

This vignette shows how to preprocess individual trio VCFs (proband, father, mother) into a clean trio VCF suitable for UPDhmm.

## Inputs

You should have one VCF (e.g. oputput from GATK) per family member:

- `proband.vcf.gz`
- `mother.vcf.gz`
- `father.vcf.gz`

Each file should be bgzipped (`.vcf.gz`) and indexed with tabix (`.tbi`).

## 0. Normalize and Left-Align Variants (optional)

For this step you will need a reference genome FASTA indexed with `samtools faidx`.

    bcftools norm -m-any -f reference.fa proband.vcf.gz -Oz -o proband.norm.vcf.gz
    bcftools norm -m-any -f reference.fa mother.vcf.gz  -Oz -o mother.norm.vcf.gz
    bcftools norm -m-any -f reference.fa father.vcf.gz  -Oz -o father.norm.vcf.gz

    tabix -p vcf proband.norm.vcf.gz
    tabix -p vcf mother.norm.vcf.gz
    tabix -p vcf father.norm.vcf.gz

## 1. Remove Extra Annotations

Keep only essential fields (drop INFO/FORMAT annotations not required downstream). The resulting VCFs are lighter.

    # Keep only GT, AD, DP, and GQ fields (remove all other INFO)
    bcftools annotate -x INFO,^FORMAT/GT,FORMAT/AD,FORMAT/DP,FORMAT/GQ \
      proband.norm.vcf.gz -Oz -o proband.clean.vcf.gz

    bcftools annotate -x INFO,^FORMAT/GT,FORMAT/AD,FORMAT/DP,FORMAT/GQ \
      mother.norm.vcf.gz  -Oz -o mother.clean.vcf.gz

    bcftools annotate -x INFO,^FORMAT/GT,FORMAT/AD,FORMAT/DP,FORMAT/GQ \
      father.norm.vcf.gz  -Oz -o father.clean.vcf.gz

    # Index the cleaned VCFs
    tabix -p vcf proband.clean.vcf.gz
    tabix -p vcf mother.clean.vcf.gz
    tabix -p vcf father.clean.vcf.gz

## 2. Merge Trio into a Single VCF

Goal:

- Combine the proband, mother, and father into a single VCF.
- Retain only biallelic and informative variants.
- Remove positions where all trio members are homozygous for the reference (0/0).

If the input files are gVCFs, you can directly merge them, as they already include all genomic positions.
If they are standard VCFs, merge the files first and then remove missing genotypes (`./.`) to keep only fully called variants.

    #--------------------------------------------------------------
    # Option 1: For standard VCFs
    #--------------------------------------------------------------

    # Merge the three individuals
    bcftools merge \
      proband.clean.vcf.gz \
      mother.clean.vcf.gz \
      father.clean.vcf.gz \
     -Oz -o trio_merged_raw.vcf.gz

    # Retain only biallelic variants
    bcftools view -m2 -M2 trio_merged_raw.vcf.gz -Oz -o trio_merged_biallelic.vcf.gz

    # Remove sites where all genotypes are homozygous reference (0/0)
    bcftools view \
      -i 'COUNT(FORMAT/GT="0/0") != 3' \
      trio_merged_biallelic.vcf.gz -Oz -o trio_merged_nohom.vcf.gz

    # Remove missing genotypes (./.) to keep only fully called variants
    bcftools view \
      -e 'GT="./."' \
      trio_merged_nohom.vcf.gz -Oz -o trio_merged_clean.vcf.gz

    #--------------------------------------------------------------
    # Option 2: For gVCFs
    #--------------------------------------------------------------

    # gVCFs already include all genomic sites, so intersection is not needed
    bcftools merge \
      proband.clean.vcf.gz \
      mother.clean.vcf.gz \
      father.clean.vcf.gz \
      -Oz -o trio_merged_raw.vcf.gz

    # Retain only biallelic variants
    bcftools view -m2 -M2 trio_merged_raw.vcf.gz -Oz -o trio_merged_biallelic.vcf.gz

    # Remove sites where all are 0/0 (non-informative for UPD analysis)
    bcftools view \
      -i 'COUNT(FORMAT/GT="0/0") != 3' \
      trio_merged_biallelic.vcf.gz -Oz -o trio_merged_clean.vcf.gz

    #--------------------------------------------------------------
    # Normalize and index the merged VCF
    #--------------------------------------------------------------

    # Normalize (split multi-allelics if any remain and remove duplicates)
    bcftools norm -m -both -d all -Oz -o trio_merged_norm.vcf.gz trio_merged_clean.vcf.gz

    # Index for downstream tools
    tabix -p vcf trio_merged_norm.vcf.gz

## 3. Mask Structural Variant Regions

Before detecting UPD events, it is recommended to exclude genomic regions prone to alignment artifacts or abnormal variant density — such as centromeres, segmental duplications, and immune complex regions (e.g., HLA and KIR).
These regions can lead to false-positive signals due to mapping ambiguity or high polymorphism.

To simplify this step, a curated set of BED masks is available in the following Zenodo repository:
🔗 Zenodo – UPDhmm Excluded Regions

The repository provides BED files for both reference genome builds:

- `hg19_excluded_regions.bed`
- `hg38_excluded_regions.bed`

These files include merged genomic intervals covering:

- Centromeric and telomeric regions
- Segmental duplications
- HLA and KIR loci
- Low-mappability or highly repetitive regions

Download the appropriate BED file for your genome build and use it to mask excluded regions from the merged trio VCF:

    # Mask problematic regions
    bcftools view -T ^merged_mask.bed \
      trio_merged_norm.vcf.gz -Oz -o trio_masked.vcf.gz

    # Index the masked VCF
    tabix -p vcf trio_masked.vcf.gz

# Session Info

    sessionInfo()

    ## R version 4.6.0 (2026-04-24)
    ## Platform: x86_64-pc-linux-gnu
    ## Running under: Ubuntu 24.04.4 LTS
    ##
    ## Matrix products: default
    ## BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    ## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    ##
    ## locale:
    ##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    ##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
    ##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    ##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    ##  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    ## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    ##
    ## time zone: Etc/UTC
    ## tzcode source: system (glibc)
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] BiocStyle_2.40.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] digest_0.6.39       R6_2.6.1            fastmap_1.2.0
    ##  [4] xfun_0.57           maketools_1.3.2     cachem_1.1.0
    ##  [7] knitr_1.51          htmltools_0.5.9     rmarkdown_2.31
    ## [10] buildtools_1.0.0    lifecycle_1.0.5     cli_3.6.6
    ## [13] sass_0.4.10         jquerylib_0.1.4     compiler_4.6.0
    ## [16] sys_3.4.3           tools_4.6.0         evaluate_1.0.5
    ## [19] bslib_0.10.0        yaml_2.3.12         BiocManager_1.30.27
    ## [22] jsonlite_2.0.0      rlang_1.2.0