Skip to main content

Phased Assembly Variant Caller


Variant caller for assembled genomes.

Install

PAV runs from a container or from a Python environment.

Containers

Public container images include PAV and all of its dependencies.

Docker:

docker pull ghcr.io/becklaboratory/pav3:latest

docker run --rm -v "$PWD:$PWD" -w "$PWD" --user "$(id -u):$(id -g)" \
    ghcr.io/becklaboratory/pav3:latest batch

Apptainer (or Singularity):

apptainer pull pav3.sif oras://ghcr.io/becklaboratory/pav3-sif:latest

apptainer run pav3.sif batch

The container runs pav3, so arguments after the image are the same as on the command line (batch, --help, and so on).

Both examples give PAV access to the current directory only. If the reference or the assemblies are in another directory, add -v /path:/path (Docker) or --bind /path (Apptainer), replacing /path with that directory.

Replace latest with a version (e.g. 3.0.0) to pin a release.

Install locally

pip install pav3

PAV requires Python 3.12 or newer and minimap2 in the PATH. The tracks targets also require bedToBigBed (UCSC executable downloads). The containers include both. All other dependencies are Python packages installed with PAV.

Configuration

PAV runs in a directory with a configuration file (pav.yaml) and an assembly table (assemblies.csv), and writes its output to the same directory.

Configuration file

pav.yaml sets PAV options. The only required option is reference, the path to the reference FASTA file. All other options have defaults.

reference: /path/to/hg38.no_alt.fa.gz

PAV also reads pav.yml, or pav.json if no YAML file exists. If both a YAML and a JSON file exist, PAV prints a warning and uses the YAML file. pav3 batch --config FILE reads the configuration from another path.

Reference genome

Use a primary assembly of chromosome scaffolds, including unplaced and unlocalized contigs if it has them (GRCh/hg references). Do not use references with ALT, PATCH, or decoy scaffolds. The redundant sequence in these contigs may increase callset errors.

Suitable references:

Assembly table

The assembly table lists the input assemblies, one row per assembly. PAV uses the first of these files it finds in the run directory:

  1. assemblies.csv
  2. assemblies.xlsx
  3. assemblies.tsv

To use another file, set its path with the assembly_table option in pav.yaml. It may be CSV, Excel, TSV, or Parquet, and CSV and TSV files may be gzipped.

Columns:

  • name: Assembly or sample name.
  • hap_*: One column per haplotype, named for the haplotype (e.g. hap_h1 or hap_mat).
  • config (optional): Configuration options for this assembly (see Per-assembly configuration).

Example with two haplotypes:

name hap_h1 hap_h2
sample1 /path/to/sample1_hap1.fa /path/to/sample1_hap2.fa
sample2 /path/to/sample2_hap1.fa /path/to/sample2_hap2.fa

Haplotype names are labels and do not change how input is processed. An assembly may have any number of haplotypes, and a blank entry means the assembly does not have that haplotype. Each VCF genotype has one allele per haplotype with an input path, in table column order. With the table above, 0|1 means the variant is in h2 but not h1.

Haplotype input formats

Each hap_* entry is a path to a FASTA, FASTQ, GFA, or FOFN (file of file names) file. Separate multiple files with semicolons (e.g. file1.fa.gz;file2.fa.gz); file types may be mixed. A FOFN may list files of any of these types, including other FOFNs (nesting is not recommended, but cycles are detected and broken).

PAV is fastest with a single indexed FASTA file, uncompressed or bgzipped. For any other input, PAV first writes and indexes a FASTA file for the haplotype, which adds to the run time.

Per-assembly configuration

The optional config column sets options for one assembly, overriding pav.yaml and PAV defaults. It holds semicolon-separated key=value pairs (e.g. min_mapq=30;lc_model=default). reference can only be set in pav.yaml.

Run

From the directory with pav.yaml and the assembly table:

pav3 batch

If the pav3 command is not on the PATH, run python -m pav3 batch.

Use -c N to limit PAV to N cores, -n for a dry run, and --profile DIR to pass a Snakemake profile (e.g. for cluster execution). pav3 batch --help lists all options.

Output

For each assembly NAME:

  • NAME.vcf.gz: Variant calls, indexed (NAME.vcf.gz.csi).
  • results/NAME/call/: Variant tables merged across haplotypes.
  • results/NAME/call_hap/: Variant tables for each haplotype, and callable regions in reference (callable_ref) and assembly (callable_qry) coordinates.
  • results/NAME/align/: Alignment tables.

Tables are in Parquet format (pav3 maketable converts them to BED, CSV, TSV, or Excel).

Targets

pav3 batch builds the VCF for every assembly. To build other outputs or stop at an earlier step, name a target:

pav3 batch tracks
  • vcf (default): VCF for each assembly (NAME.vcf.gz).
  • call_tables: Variant tables merged across haplotypes (results/NAME/call/). Stops before writing the VCF.
  • call_tables_hap: Variant tables for each haplotype (results/NAME/call_hap/). Stops before merging haplotypes.
  • callable: Callable regions for each haplotype in reference and assembly coordinates (results/NAME/call_hap/callable_*).
  • align: Alignment tables (results/NAME/align/). Stops before calling variants.
  • data_init: Reference files shared by all assemblies (data/ref/).
  • tracks: All UCSC tracks (tracks_var and tracks_align). Requires bedToBigBed.
  • tracks_var: Variant tracks for each haplotype (tracks/call_hap/).
  • tracks_align: Alignment tracks (tracks/align/).

A target can also be an output file. To run each assembly as an independent job, run data_init once, then run one job per assembly in the same directory. These jobs can run at the same time without locking each other:

pav3 batch data_init

pav3 batch sample1.vcf.gz
pav3 batch sample2.vcf.gz

Without data_init first, each job tries to build the shared reference files, and Snakemake stops the later jobs with a "Directory cannot be locked" error.

Other commands

  • pav3 lift: Lift regions from reference to assembly coordinates, or from assembly to reference coordinates with -r. Uses the alignments in a PAV run directory (-d, default: the current directory; requires the align target) or a SAM, BAM, or CRAM file (-a).
  • pav3 subseq: Lift regions as pav3 lift does and output their sequences: assembly sequences by default, or reference sequences with -r.
  • pav3 maketable: Convert a PAV Parquet table to BED, CSV, TSV, or Excel.
  • pav3 license: Print the PAV license (brief, full, or spdx).
  • pav3 call: Deprecated. Prints a warning and runs pav3 batch.

Run pav3 COMMAND --help for the options of each command.

PAV versions

PAV follows Python's packaging version scheme (https://packaging.python.org/en/latest/discussions/versioning/) with three fields:

  • Major: Large changes or new features.
  • Minor: Small changes that may affect the PAV API or command-line interface.
  • Patch: Bug fixes and small features. Patch releases do not break API or command-line compatibility, but may change results.

Pre-release versions have a suffix: development (".devN"), alpha ("aN"), beta ("bN"), or release candidate ("rcN"), where "N" is an integer greater than 0. For example, "3.0.0.dev1" is a development version before 3.0.0.

Reporting bugs

Please report problems on the issues page.

Thank you for your bug reports and feedback. They really do help improve PAV!

Cite PAV

Cite PAV 3 with the bioRxiv preprint:

Peter Audano, Carolyn Paisie, The Human Genome Structural Variation Consortium (HGSVC), and Christine Beck. 2024. “Large Complex Structural Rearrangements in Human Genomes Harbor Cryptic Structures.” In bioRxiv. December 22. https://doi.org/10.1101/2024.12.19.629504.

PAV 1 & 2

Cite earlier versions of PAV as:

Ebert et al., “Haplotype-Resolved Diverse Human Genomes and Integrated Analysis of Structural Variation,” Science, February 25, 2021, eabf7117, https://doi.org/10.1126/science.abf7117 (PMID: 33632895).

License

PAV is released under the MIT License. See LICENSE.

Metadata

Release files for pav3 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pav3 3.0.0
File Size Uploaded Provenance Actions
pav3-3.0.0.tar.gz 3.1 MB Without provenance Details for pav3-3.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pav3 3.0.0
File Interpreter ABI Platform Actions
pav3-3.0.0-py3-none-any.whl Python 3 none any Details for pav3-3.0.0-py3-none-any.whl

Total release size: 6.1 MB

Release files / pav3-3.0.0.tar.gz

Download URL pav3-3.0.0.tar.gz
Size 3.1 MB
Tags Source
SHA-256 checksum
How to use checksums
328bed534d1a5bf3127d7e954c484657aea744b30b92e3ef50fb1b1935203df5
BLAKE2b-256 checksum
How to use checksums
2d6e6141b6fb06aac5a8b858c09d0c9340baf63301616f3e71288a55ca31bfbc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / pav3-3.0.0-py3-none-any.whl

Download URL pav3-3.0.0-py3-none-any.whl
Size 3.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
5cb93496b1b81a6f15d192f2a260decd5521246d8a7f30ad3404676370b593ad
BLAKE2b-256 checksum
How to use checksums
bb8969ee91c3de683570f3c7ac6a868300259430fe5db6aeaf22a35be6b80003
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Security for pav3 3.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page