phase.md

December 18, 2025 · View on GitHub

Phase command

SNP-only phasing

For SNP-only phasing, the input of LongPhase-TO consists of SNPs in VCF (e.g., SNP.vcf), an indexed reference in Fasta (e.g., reference.fasta, reference.fasta.fai), and one (or multiple) indexed read-to-reference alignment in BAM (e.g., alignment1.bam, alignment1.bai, alignment2.bam, ...) (see Input Preparation). An example of SNP phasing usage is shown below.

longphase-to phase \
-s SNP.vcf \
-b alignment1.bam \
-b alignment2.bam \
-r reference.fasta \
-t 8 \
-o phased_prefix \
--pon-file pon1.vcf,pon2.vcf \
--strict-pon-file pon3.vcf,pon4.vcf

SNP and indel co-phasing

When the SNP.vcf file contains both SNP and small insertion/deletion variations (indels), use the --indels parameter for co-phasing SNPs and indels.

longphase-to phase \
-s SNP.vcf \
-b alignment.bam \
-r reference.fasta \
-t 8 \
-o phased_prefix \
--indels

Complete list of phase parameters

Usage:  phase [OPTION] ... READSFILE
   --help                                 display this help and exit.

require arguments:
   -s, --snp-file=NAME                    input SNP vcf file, or a VCF file with both SNPs and indels.
   -b, --bam-file=NAME                    input bam file.
   -r, --reference=NAME                   reference fasta.   -c, --caller=NAME                      variant caller name.
                                          options: clairs_to_ss, clairs_to_ssrs, deepsomatic_to

optional arguments:
   -t, --threads=Num                      number of thread. default:1
   -o, --out-prefix=NAME                  prefix of phasing result. default: result
   --indels                               phase small indel. default: False
   --dot                                  each contig/chromosome will generate dot file.
   --loh                                  output LOH results. default: False

somatic arguments:
   --purity=[0~1]                         set sample purity directly; if omitted, estimate automatically.
   --disable-calling                      disable longphase-to calling mode. default: False
   --disable-pon-tag                      disable reading the VCF FILTER field PON to determine germline variants. default: False
   --disable-refine-somatic               do not modify VCF FILTER based on somatic refinement. default: False
   --pon-file=NAME                        input PON VCF file. determines germline variants using position-based matching.
                                          input format: A.vcf,B.vcf
   --strict-pon-file=NAME                 input PON VCF file. determines germline variants using both position and ALT allele matching.
                                          input format: A.vcf,B.vcf
   --somaticConnectAdjacent=Num           connect adjacent N SNPs. default:6

parse alignment arguments:
   -q, --mappingQuality=Num               filter alignment if mapping quality is lower than threshold. default:1
   -x, --mismatchRate=Num                 mark reads as false if mismatchRate of them are higher than threshold. default:3

phasing graph arguments:
   -p, --baseQuality=[0~90]               change edge's weight to --edgeWeight if base quality is lower than the threshold. default:12
   -e, --edgeWeight=[0~1]                 if one of the bases connected by the edge has a quality lower than --baseQuality
                                          its weight is reduced from the normal 1. default:0.1
   -a, --connectAdjacent=Num              connect adjacent N SNPs. default:35
   -d, --distance=Num                     phasing two variant if distance less than threshold. default:300000
   -1, --edgeThreshold=[0~1]              give up SNP-SNP phasing pair if the number of reads of the 
                                          two combinations are similar. default:0.7
   -L, --overlapThreshold=[0~1]           filtering different alignments of the same read if there is overlap. default:0.2 

haplotag read correction arguments:
   -m, --readConfidence=[0.5~1]           The confidence of a read being assigned to any haplotype. default:0.65
   -n, --snpConfidence=[0.5~1]            The confidence of assigning two alleles of a SNP to different haplotypes. default:0.75

Phased Genotype Output Format

The genotype (GT) uses the | delimiter to represent phased alleles on two haplotypes. The format is A|B, where:

  • A represents the allele on the first haplotype
  • B represents the allele on the second haplotype
  • | indicates phasing (i.e., the alleles are ordered and assigned to specific haplotypes)

Allele

  • 0 reference allele
  • 1 alternate allele
  • . denotes an unknown or undetermined allele

This format is extended with GT2 and GT3 fields to enable detailed modeling of somatic variation, phasing complexity, and loss of heterozygosity (LOH) — crucial for applications in cancer genomics.

To facilitate understanding of how different types of variants—such as germline and somatic variants—are represented in phased genotypes, the following two examples are provided:

Germline variant GT:GT2:GT3 0|1:./.:./.
Somatic  variant GT:GT2:GT3 0|0:.|1:./.

GT (Germline and Primary Somatic Phasing)

1. Germline heterozygosity
  • 0|1: haplotype 1 is reference; haplotype 2 is alternate
  • 1|0: haplotype 1 is alternate; haplotype 2 is reference
2. Germline homozygosity or LOH
  • .|1: haplotype 1 unknown (potential LOH); haplotype 2 is alternate
  • 1|.: haplotype 1 is alternate; haplotype 2 unknown (potential LOH)
3. Somatic mutation not in LOH
  • 0|0: both haplotypes are reference
4. Somatic mutation in LOH
  • .|0: haplotype 1 unknown; haplotype 2 is reference
  • 0|.: haplotype 1 is reference; haplotype 2 unknown

GT2 and GT3 (Somatic Phasing and LOH Resolution)

These fields provide finer resolution for subclonal or ambiguous somatic phasing, especially in LOH contexts.

1. Somatic mutations not in LOH
  • GT2 .|1, GT3 ./.: hp1-1 unknown; hp2-1 is alternate (somatic-derived)
  • GT2 1|., GT3 ./.: hp1-1 is alternate (somatic-derived); hp2-1 unknown
  • GT2 1|1, GT3 ./.: Ambiguous somatic haplotype (hp3); both alleles are alternate
2. Somatic mutations in LOH regions
  • GT2 0|., GT3 1|.: hp1-1-1 is reference; hp1-1-2 is alternate
  • GT2 1|., GT3 0|.: hp1-1-1 is alternate; hp1-1-2 is reference
  • GT2 1|., GT3 1|.: Ambiguous somatic haplotype (hp3); both alleles are alternate
  • GT2 .|0, GT3 .|1: hp1-2-1 is reference; hp1-2-2 is alternate
  • GT2 .|1, GT3 .|0: hp1-2-1 is alternate; hp1-2-2 is reference
  • GT2 .|1, GT3 .|1: Ambiguous somatic haplotype (hp3); both alleles are alternate

Haplotype-Aware Variant Re-Calling Output Format

When performing haplotype-aware variant re-calling, LongPhase-TO refines the VCF FILTER field based on somatic variant analysis. By default, LongPhase-TO may correct non-PASS variants to PASS or revert PASS variants to non-PASS. The --disable-refine-somatic option disables this refinement, retaining the original FILTER values. Variants with FILTER value PASS indicate they passed LongPhase-TO's somatic variant analysis. LongPhase-TO adds two FILTER tags: LP_nonSomatic for non-somatic variants and LP_PON for variants found in the panel of normals. For example:

##FILTER=<ID=LP_nonSomatic,Description="Non-somatic variant tagged by longphase-to">
##FILTER=<ID=LP_PON,Description="PON variant tagged by longphase-to">
#CHROM  POS     ID      REF     ALT     QUAL    FILTER        INFO    FORMAT  SAMPLE
chr1    10864   .       G       A       23.2667 PASS          ...     ...     ...
chr1    14695   .       C       T       17.3507 LP_nonSomatic ...     ...     ...
chr1    34932   .       T       C       2.8045  LP_PON        ...     ...     ...

If the --disable-refine-somatic option is used, variants can be filtered using the following command:

awk '/^#/ || /0\|0/ || /\.|0/ || /0\|./' <vcf_path> > <output_path>

Output files of Purity

When performing purity estimation, LongPhase-TO outputs the tumor purity estimate in the VCF header as a double. It uses the tag tumor_purity. For example:

##tumor_purity=0.6
#CHROM  POS     ID      REF     ALT     QUAL    FILTER  INFO    FORMAT  SAMPLE

Output files of SNP and indel phasing

When phasing SNPs alone, LongPhase-TO outputs the results into a VCF file. The alleles of the two haplotypes are stored in the GT field (e.g., 1|0), whereas the left and right alleles of the vertical bar represent the paternal or maternal haplotypes. The last PS field (e.g., 16809) represents the identifier of the block. For instance, the following example illustrates two haplotypes of five-phased SNPs, CCCCC and GATGT, in the same block 16809. The output of phased indels is similar and in the same VCF.

##FORMAT=<ID=GT,Number=1,Type=String,Description="Genotype">
##FORMAT=<ID=PS,Number=1,Type=Integer,Description="Phase set identifier">
#CHROM  POS     ID      REF     ALT     QUAL    FILTER  INFO    FORMAT  default
1       16809   .       C       G       8.4     PASS    .       GT:GQ:DP:AD:VAF:PL:PS   1|0:8:79:51,28:0.35443:7,0,16:16809
1       16949   .       A       C       8.4     PASS    .       GT:GQ:DP:AD:VAF:PL:PS   0|1:8:67:43,21:0.313433:7,0,25:16809
1       21580   .       C       T       13.9    PASS    .       GT:GQ:DP:AD:VAF:PL:PS   1|0:14:75:50,24:0.32:13,0,30:16809
1       23359   .       C       G       13.2    PASS    .       GT:GQ:DP:AD:VAF:PL:PS   1|0:13:52:24,18:0.346154:13,0,42:16809
1       24132   .       C       T       11.1    PASS    .       GT:GQ:DP:AD:VAF:PL:PS   1|0:11:63:41,17:0.269841:10,0,29:16809