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.1

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.1
File Size Uploaded Provenance Actions
pav3-3.0.1.tar.gz 3.1 MB Without provenance Details for pav3-3.0.1.tar.gz

Built distribution (wheel)

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

Total release size: 6.1 MB

Release files / pav3-3.0.1.tar.gz

Download URL pav3-3.0.1.tar.gz
Size 3.1 MB
Tags Source
SHA-256 checksum
How to use checksums
66c5efb3a21a5eb13a1829980842804a43576ec8df926c6c758afa42bc77d802
BLAKE2b-256 checksum
How to use checksums
9495a333949b16a2b6c1db9fe046b9593c89c3b6e42dda1267499a72f0ea8c8e
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.1-py3-none-any.whl

Download URL pav3-3.0.1-py3-none-any.whl
Size 3.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
ede948808344898861683280a1372cd3707a207e2b13302922a4512e755c2bd5
BLAKE2b-256 checksum
How to use checksums
d5da21f2c3ac3ac8199efbba890c2060238a8aa176f5ee26dceaf295f580638d
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.1

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