WhatsHap

https://whatshap.readthedocs.io/en/latest
Admin
WhatsHap is a software for accurate read-based phasing of genomic variants using DNA sequencing...
Tokens:32,098
Snippets:124
Trust Score:8.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install WhatsHap with Conda

Source: https://whatshap.readthedocs.io/en/latest/installation

Installs WhatsHap into a new Conda environment named 'whatshap-env'. This is the recommended installation method. It ensures proper dependency management.

```bash
conda create -n whatshap-env whatshap
conda activate whatshap-env
whatshap --version
```

--------------------------------

### Install WhatsHap with pip

Source: https://whatshap.readthedocs.io/en/latest/installation

Installs WhatsHap using pip after installing necessary C++ and Python development dependencies. This method places the executable in '$HOME/.local/bin', which needs to be added to the PATH.

```bash
pip3 install --user whatshap
export PATH=$HOME/.local/bin:$PATH
whatshap --help
```

--------------------------------

### Install WhatsHap Development Version with Conda

Source: https://whatshap.readthedocs.io/en/latest/installation

Installs the latest unreleased development version of WhatsHap into a separate Conda environment. This method uses pip to install directly from a GitHub repository, ensuring it does not interfere with other installations.

```bash
conda create -n whatshap-tmp python pip gxx
conda activate whatshap-tmp
pip install git+https://github.com/whatshap/whatshap
whatshap --version
```

--------------------------------

### Progeny VCF File Example

Source: https://whatshap.readthedocs.io/en/latest/_sources/guide

An example format for a VCF file containing progeny genotype information, specifically demonstrating the required 'AD' (Allele Depth) field for phasing.

```vcf
##fileformat=VCFv4.1
#CHROM  POS  ID  REF  ALT  QUAL   FILTER  INFO FORMAT  parent1    parent2    progeny1    ...
chr1    100  .   A    T    50.0   .       .    GT:AD   0/0/0/1:.  0/0/0/0:.  0/0/0/1:75,21
chr1    200  .   C    G,A  50.0   .       .    GT:AD   0/0/0/2:.  0/0/0/1:.  0/0/1/2:53,18,22
...
```

--------------------------------

### VCF Header Example for WhatsHap

Source: https://whatshap.readthedocs.io/en/latest/_sources/guide

This example shows a VCF header format that WhatsHap can parse to identify samples. It includes basic VCF version and format information, followed by sample columns ('SampleA', 'SampleB') and their respective genotype information ('GT').

```vcf
##fileformat=VCFv4.1
#CHROM  POS  ID  REF  ALT  QUAL   FILTER  INFO FORMAT  SampleA  SampleB
chr1    100  .   A    T    50.0   .       .    GT      0/1      0/1
...
```

--------------------------------

### Getting Help for a WhatsHap Subcommand

Source: https://whatshap.readthedocs.io/en/latest/_sources/guide

This command shows how to retrieve help information for any specific WhatsHap subcommand. Replace 'SUBCOMMAND' with the actual name of the subcommand (e.g., 'phase', 'polyphase', 'stats') to view its detailed options and usage instructions.

```bash
whatshap SUBCOMMAND --help
```

--------------------------------

### BigQuery Example for PyPI Download Statistics

Source: https://whatshap.readthedocs.io/en/latest/_sources/develop

A SQL query for Google BigQuery to retrieve download counts for the 'whatshap' PyPI package, broken down by version since a specified date. Requires access to the 'the-psf:pypi.downloads' BigQuery table.

```sql
SELECT
    file.project,
    file.version,
    COUNT(*) as total_downloads,
FROM
    TABLE_DATE_RANGE(
        [the-psf:pypi.downloads],
        TIMESTAMP("20170101"),
        CURRENT_TIMESTAMP()
    )
WHERE
    file.project = 'whatshap'
GROUP BY
    file.project, file.version
```

--------------------------------

### Pedigree File Format Example

Source: https://whatshap.readthedocs.io/en/latest/_sources/guide

Specifies the required format for the pedigree file, which defines the relationships between parent and progeny samples using three whitespace-separated columns.

```text
parent_1 parent_2 progeny_1
parent_1 parent_2 progeny_2
parent_1 parent_2 progeny_3
...
```

--------------------------------

### BAM/CRAM Header Example for WhatsHap

Source: https://whatshap.readthedocs.io/en/latest/_sources/guide

This example illustrates the relevant parts of a BAM/CRAM header that WhatsHap uses to link reads to samples. It shows the read group (RG) ID and the associated sample name (SM). Multiple read groups can be assigned to the same sample.

```samheader
@HD     VN:1.4  SO:coordinate
@SQ     SN:...  LN:...
...
@RG   ID:1  SM:SampleA
@RG   ID:2  SM:SampleB
```

```samheader
@RG   ID:1a  SM:SampleA
@RG   ID:1b  SM:SampleA
@RG   ID:2   SM:SampleB
```

--------------------------------

### VCF Genotype Field Example

Source: https://whatshap.readthedocs.io/en/latest/guide

An example of a VCF file snippet illustrating the GT and PS fields for a specific variant. This format is used by `whatshap haplotag` to determine haplotype assignments.

```text
#CHROM	POS	ID	REF	ALT	QUAL	FILTER	INFO	FORMAT	NA12878
chr1	1069577	.	G	A	.	PASS	.	GT:PS	1|0:1069577

```

--------------------------------

### BigQuery SQL for PyPI Download Statistics

Source: https://whatshap.readthedocs.io/en/latest/develop

This SQL query retrieves download counts from PyPI for the 'whatshap' project, broken down by version, starting from a specified date. It utilizes Google BigQuery's `TABLE_DATE_RANGE` function and requires access to the 'the-psf:pypi.downloads' table.

```sql
SELECT
    file.project,
    file.version,
    COUNT(*) as total_downloads,
FROM
    TABLE_DATE_RANGE(
        [the-psf:pypi.downloads],
        TIMESTAMP("20170101"),
        CURRENT_TIMESTAMP()
    )
WHERE
    file.project = 'whatshap'
GROUP BY
    file.project, file.version

```

--------------------------------

### VCF Phasing with PS Tag Format

Source: https://whatshap.readthedocs.io/en/latest/guide

Example VCF file showing phasing representation using the PS (phase set) tag. This format groups variants into phase sets identified by position numbers, with multiple phase sets allowed in a single file. Variants in the same phase set share a unique identifier indicating they were phased relative to each other.

```text
##fileformat=VCFv4.1
#CHROM  POS  ID  REF  ALT  QUAL   FILTER  INFO FORMAT     sample1      sample2
chr1    100  .   A    T    50.0   .       .    GT:PS:PQ   0|1:100:22   0/1:.:.
chr1    150  .   C    G    50.0   .       .    GT:PS:PQ   1|0:100:18   0/1:.:.
chr1    300  .   G    T    50.0   .       .    GT:PS:PQ   1|0:300:23   0/1:.:.
chr1    350  .   T    A    50.0   .       .    GT:PS:PQ   0|1:300:42   0/1:.:.
chr1    500  .   A    G    50.0   .       .    GT:PS:PQ   0|1:100:12   0/1:.:.
```

--------------------------------

### BAM/CRAM File Header with Read Group Configuration

Source: https://whatshap.readthedocs.io/en/latest/guide

Example BAM/CRAM file header showing proper read group (@RG) configuration with sample names (SM attribute). Each read group links to a sample, and individual alignments are tagged with corresponding read group IDs. This metadata structure is required for WhatsHap to correctly associate reads with samples.

```sam
@HD     VN:1.4  SO:coordinate
@SQ     SN:...  LN:...
...
@RG   ID:1  SM:SampleA
@RG   ID:2  SM:SampleB
```

--------------------------------

### Compute Phasing Statistics with whatshap stats

Source: https://whatshap.readthedocs.io/en/latest/guide

Calculate and display phasing statistics from a VCF file using WhatsHap's stats subcommand. Provides summary metrics on phasing quality and coverage. Simple single-argument command that processes the input VCF file.

```bash
whatshap stats input.vcf
```

--------------------------------

### Basic WhatsHap Phasing Command

Source: https://whatshap.readthedocs.io/en/latest/guide

This is the fundamental command for running WhatsHap to phase variants. It takes an input VCF and BAM/CRAM file, uses a reference genome, and outputs a phased VCF file. Ensure the reference FASTA is provided for optimal results, especially with error-prone reads.

```bash
whatshap phase -o phased.vcf --reference=reference.fasta input.vcf input.bam

```

--------------------------------

### Run WhatsHap Polyphase for Polyploid Phasing

Source: https://whatshap.readthedocs.io/en/latest/guide

This command executes the polyphase algorithm for phasing polyploid samples. It requires an input VCF file, an input BAM file, the ploidy level, and an optional reference FASTA file, outputting the phased results to a VCF file. The ploidy argument must match the VCF's ploidy and significantly impacts runtime.

```bash
whatshap polyphase input.vcf input.bam --ploidy p --reference ref.fasta -o output.vcf
```

--------------------------------

### PED File Format - Define Quartet

Source: https://whatshap.readthedocs.io/en/latest/guide

Example of a PED file format defining a quartet (two children with same parents). Multiple consecutive spaces in delimiters are acceptable. WhatsHap processes both rows to establish family relationships for phasing.

```text
# Fields: family, individual_id, paternal_id, maternal_id, sex, phenotype
FAMILY01 one_child   father mother 0 1
FAMILY01 other_child father mother 0 1
```

--------------------------------

### Create Phased FASTA References with bcftools

Source: https://whatshap.readthedocs.io/en/latest/guide

Generate two separate haplotype FASTA files from a phased VCF using bcftools consensus. Requires compressed and indexed VCF input. WhatsHap VCF output must be bgzipped and indexed with tabix before processing. Produces separate FASTA files for each haplotype.

```bash
bgzip phased.vcf
tabix phased.vcf.gz
bcftools consensus -H 1 -f reference.fasta phased.vcf.gz > haplotype1.fasta
bcftools consensus -H 2 -f reference.fasta phased.vcf.gz > haplotype2.fasta
```

--------------------------------

### WhatsHap Split - Split FASTQ Reads by Haplotype

Source: https://whatshap.readthedocs.io/en/latest/_sources/guide

Splits unmapped reads from a FASTQ file according to their haplotype assignments. Reads haplotype information from a tab-separated values (TSV) file created by whatshap haplotag with --output-haplotag-list option. The output format matches the input format (FASTQ in this example).

```bash
whatshap split --output-h1 h1.fastq.gz --output-h2 h2.fastq.gz reads.fastq.gz haplotypes.tsv
```

--------------------------------

### BAM/CRAM Header with Multiple Read Groups per Sample

Source: https://whatshap.readthedocs.io/en/latest/guide

Example showing multiple read groups assigned to the same sample. This configuration allows combining reads from different sequencing runs or libraries while maintaining proper sample identification. WhatsHap uses the SM (sample name) attribute to group read groups belonging to the same sample.

```sam
@RG   ID:1a  SM:SampleA
@RG   ID:1b  SM:SampleA
@RG   ID:2   SM:SampleB
```

--------------------------------

### PED File Format for Pedigree Definition

Source: https://whatshap.readthedocs.io/en/latest/_sources/guide

PLINK-compatible PED file format for specifying family relationships in WhatsHap pedigree phasing. Requires at minimum six columns with family ID, individual ID, paternal ID, maternal ID, sex, and phenotype. WhatsHap uses columns 2-4 for phasing relationships. Lines starting with # are comments and are ignored.

```ped
# Fields: family, individual_id, paternal_id, maternal_id, sex, phenotype
FAMILY01 the_child father mother 0 1
```

--------------------------------

### Write Haplotype Blocks to GTF

Source: https://whatshap.readthedocs.io/en/latest/_sources/guide

Creates a GTF file describing haplotype blocks from a phased VCF. This format can represent interleaved or nested blocks as exons and connecting lines.

```shell
whatshap stats --gtf=phased.gtf phased.vcf
```

--------------------------------

### Basic WhatsHap Phasing Command

Source: https://whatshap.readthedocs.io/en/latest/_sources/guide

This command demonstrates the fundamental usage of WhatsHap for phasing diploid variants. It takes an input VCF and BAM file, phases the variants using sequencing reads, and outputs the phased variants into a new VCF file. Providing a reference FASTA is highly recommended for better phasing quality, especially with error-prone reads.

```bash
whatshap phase -o phased.vcf --reference=reference.fasta input.vcf input.bam
```
Tokens:
Raw