Skip to contents

popgenVCF — Population Genomics Toolkit

R CMD check Scientific validation Test coverage License: MIT Documentation: Wiki DOI

popgenVCF is an R toolkit and command-line application for reproducible population-genomic analysis of diploid, biallelic SNP VCF files. It provides quality control, PCA, IBS/MDS, diversity, FST, kinship, genetic sex check, runs of homozygosity, sliding-window genome scans, DAPC, AMOVA, population structure, spatial genetics, publication outputs, and machine-readable validation evidence.

Development series: 1.0.16.9000 — active development on main toward the next release, past the current stable release 1.0.16 (released 2026-09-21; DOI 10.5281/zenodo.22867369). No development build should be treated as release-approved unless its own production dossier reports READY.

See it before you install it

Real figures and the complete PDF report from a real 160-sample, 8-population 1000 Genomes chromosome 22 run are in the Results and Interpretation wiki page and docs/examples/chr22-quickstart-report.pdf. Already have the package installed? That same dataset ships with it – vignette("quickstart", package = "popgenVCF") runs the full pipeline locally in a few minutes with no download.

Quick start with Docker

Docker is the simplest evaluation path:

docker pull ghcr.io/duceppemo/popgenvcf:latest

docker run --rm --user "$(id -u):$(id -g)" \
  -e HOME=/tmp -v "$PWD:/data" \
  ghcr.io/duceppemo/popgenvcf:latest \
  --write-config /data/analysis.yml

The generated file records the logical CPUs and memory visible to the container. It lists every built-in analysis enabled; analyses needing population or geographic metadata skip themselves automatically when that metadata isn’t available, while optional ancestry backends stay disabled until explicitly requested since they need an external tool. Backend threads: auto values inherit compute.threads.

Edit analysis.yml to use container paths such as /data/cohort.vcf.gz (see the Configuration Reference’s Input/Output sections), then run:

docker run --rm --user "$(id -u):$(id -g)" \
  -e HOME=/tmp -v "$PWD:/data" \
  ghcr.io/duceppemo/popgenvcf:latest \
  --config /data/analysis.yml

Use an immutable image digest from a GitHub Release for a reproducible production analysis.

Local installation

System requirements include R 4.3 or newer, BCFtools, and HTSlib:

git clone https://github.com/duceppemo/popgenVCF.git
cd popgenVCF
Rscript install_popgenVCF.R

Create and run a configuration through the R entry point:

Rscript -e 'popgenVCF::cli_main(c("--write-config", "analysis.yml"))'
Rscript -e 'popgenVCF::cli_main(c("--config", "analysis.yml"))'

Conda/Mamba, Apptainer, HPC, ancestry-backend, and development installation paths are covered in the wiki.

Documentation

Choose the section that matches your role:

Audience Start here
Users Getting started · User guide · Results and interpretation
Deployers Containers, HPC, and troubleshooting
Validators and scientific reviewers Validation and scientific review
Developers and contributors Developer guide
Maintainers and release owners Release and governance

Contributing and citation

See CONTRIBUTING.md before proposing a change. Scientific changes require estimator definitions, independent validation, and retained evidence appropriate to their risk.

Citation metadata are available in CITATION.cff. popgenVCF 1.0.16 is archived on Zenodo at 10.5281/zenodo.22867369 (concept DOI 10.5281/zenodo.21747067, which always resolves to the latest version). popgenVCF is licensed under the MIT License.