Run your first popgenVCF analysis

This guide takes a new analysis from input preparation to a reproducible result directory. It uses the command-line interface because the same workflow works in Docker, Podman, Apptainer, and a local R installation.

1. Choose the analysis mode

popgenVCF determines which analyses are scientifically available from the supplied inputs.

Mode	Required input	Analyses that can become available
VCF only	Diploid VCF (any variant types; only biallelic SNPs are retained, automatically)	QC, filtering, LD pruning, PCA, IBS/MDS, kinship (KING-robust), genetic sex check, runs of homozygosity, and configured ancestry engines
Sample metadata	VCF plus exact sample identifiers	VCF-only analyses with descriptive annotations
Population metadata	Complete population values	Diversity, FST, genome scans, DAPC, AMOVA, and population summaries
Spatial metadata	Usable latitude and longitude values	Mantel, isolation-by-distance, maps, and spatial analyses

Missing metadata does not make a VCF-only analysis invalid. Modules whose requirements are not met are skipped transparently and recorded in analysis_capabilities.tsv.

2. Prepare the VCF and metadata

A raw VCF straight off a variant caller does not need pre-filtering. VCF-to-GDS conversion (SNPRelate::snpgdsVCF2GDS(..., method = "biallelic.only")) automatically retains only biallelic SNPs, silently dropping indels, multiallelic sites, structural variants, and MNPs before any of this package’s own analysis code runs (monomorphic records pass through and are instead removed by this package’s own MAF filter). 00_vcf_variant_types.tsv shows exactly how many records were retained versus dropped, and why.

The VCF sample names are immutable sample keys. When metadata are supplied, the sample column must match every VCF sample name exactly, once and only once. An optional alias supplies a clearer public label without renaming the VCF/GDS identity.

sample  alias   population  latitude    longitude   location
Sample01    Ottawa_01   North   45.4215 -75.6972    Ottawa
Sample02    NA  North   45.4200 -75.6900    Ottawa
Sample03    Montreal_01 South   45.5019 -73.5674    Montreal
Sample04    Montreal_02 South   NA  NA  Montreal

Use signed decimal degrees: latitude is positive north/negative south and longitude is positive east/negative west. Use NA for missing optional values. A missing alias falls back to sample; incomplete coordinates exclude only that sample from spatial calculations. In contrast, any missing population value disables population-dependent modules. Never omit a sample row: the metadata and VCF sample sets must match exactly.

See the complete metadata guide for accepted columns, identity fields, coordinate ranges, missing-data rules, and validation checks.

The input VCF may be uncompressed, ordinary gzip-compressed, or BGZF-compressed. popgenVCF reuses a valid index and otherwise creates a sorted BGZF copy and Tabix index in the analysis cache. Preserve the original input and record its checksum before analysis.

3. Select an executable environment

For exploratory work, define an image variable once:

export POPGENVCF_IMAGE="ghcr.io/duceppemo/popgenvcf:latest"

For a publication or archive, replace latest with the immutable digest recorded by the corresponding GitHub Release:

export POPGENVCF_IMAGE="ghcr.io/duceppemo/popgenvcf@sha256:<digest>"

A local package installation can use the same CLI arguments through Rscript inst/cli/popgenVCF.R.

4. Generate and edit the configuration

From the directory containing the VCF and metadata:

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

--write-config detects the logical CPUs and memory available to the current process, including Docker CPU affinity/quota and memory limits when present. The generated YAML lists every built-in analysis. Population- and geography-dependent analyses are initially set to no; PCA, IBS, and the neighbour-joining tree remain available from VCF sample IDs alone. Optional external ancestry backends are listed but disabled.

Edit at least the input and output sections:

input:
  vcf: /data/cohort.vcf.gz
  metadata: /data/metadata.tsv
  metadata_header: auto

output:
  directory: /data/results
  figure_formats: [pdf, png]
  dpi: 600
  figure_style: accessibility-first
  base_font_size: 11
  label_samples: auto

compute:
  threads: 8
  memory_mb: 32768
  seed: 42

qc:
  maf: 0.05
  max_sample_missing: 0.20

report:
  enabled: true
  title: Population genomic analysis
  author: Analyst name

Container paths must be visible inside the container. With the bind mount above, host files under the current directory appear under /data.

The default accessibility-first figure style uses colour-vision-aware palettes and redundant point shapes where the plot geometry permits them. Use grayscale-safe for monochrome publication, and add svg to figure_formats when you need editable vector artwork. See the publication figure styles guide for export and palette details.

5. Run the analysis

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

On an HPC system, use the equivalent Apptainer command from the containers and HPC guide. Generate the template inside the allocation when possible, and set compute.threads and compute.memory_mb no higher than the scheduler allocation.

6. Inspect the execution evidence first

Before interpreting figures, review the machine-readable control files in the result root:

File	Purpose
pipeline.log	Ordered operational log and failures
analysis_capabilities.tsv	Available and skipped modules with reasons
analysis_execution_plan.tsv	Dependency-resolved execution plan
analysis_execution_ledger.tsv	Success, failure, blocking, retry, or timeout state
analysis_module_contracts.tsv	Registered module requirements and contracts
analysis_artifacts.tsv	Produced artifact manifest when artifacts exist
analysis_validation.tsv	Module validation outcomes when validation records exist
analysis_summary.tsv	Stable analysis summary
report/population_genomics_report.html	Portable human-readable report with tables and embedded figures
report/population_genomics_report.pdf	Compact, email-friendly report using vector figures when available
analysis_results.rds	Complete serialized analysis object for R-based reproducibility and report regeneration
sessionInfo.txt	R and package environment

The tables/ directory begins with sample identity and QC evidence, including 01_sample_QC.tsv, 02_sample_metadata_match.tsv, variant-QC tables, and the exact LD-pruned SNP list. Module-specific tables and figures depend on capability and configuration.

Open report/population_genomics_report.html in a standard web browser or use report/population_genomics_report.pdf for email, printing, and document review. Both reports are self-contained and can be copied without the RDS file or the figures/ directory. The PDF prefers the existing vector figure files, which usually makes it substantially smaller than the HTML report. The RDS file is not intended to be opened by a general-purpose document viewer.

After updating popgenVCF, an existing completed analysis can be converted to the new report format without rerunning the scientific analyses:

popgenVCF::render_report(
  "results/analysis_results.rds",
  "results/report",
  title = "Population genomics analysis"
)

Both formats are requested by default. Pass formats = "pdf" to generate only the compact PDF, or formats = "html" to generate only the browser report. PDF generation requires XeLaTeX, LuaLaTeX, or pdfLaTeX in the execution environment. When no supported LaTeX engine is available, popgenVCF records a warning, skips the PDF, and still produces the HTML report.

For many high-resolution plots, the self-contained HTML can be tens of megabytes and may take a few minutes to generate. This is expected because the images are embedded in the report for portability.

7. Inspect the result from R

analysis <- readRDS("results/analysis_results.rds")
summary(analysis)
popgenVCF::list_analyses(popgenVCF::default_analysis_registry())
popgenVCF::get_analysis_result(analysis, "pca")

Do not assume that a missing result is a software error. Confirm whether the module was unavailable, skipped, blocked by a failed dependency, or explicitly not selected.

8. Validate before interpretation

A completed command is not by itself scientific validation. Check that:

1. sample identities and metadata alignment are correct;
2. retained sample and variant counts are plausible;
3. module validation records pass;
4. no required module is failed, blocked, or timed out;
5. external-tool results record the executable and version actually used;
6. diagnostic-only comparisons are not presented as release-gating equivalence evidence.

Use the interpretation guide for analysis-specific cautions.

9. Archive the analysis

Retain together:

• the original VCF and metadata checksums;
• analysis.yml;
• the exact package version, source commit, or OCI digest;
• the complete result directory;
• external-tool versions and commands;
• scheduler resources, thread count, and random seed;
• validation, benchmark, and provenance evidence relevant to the analysis.

The 0.10.0 software contracts support canonical validation and release evidence, but users must not describe a production baseline, external concordance suite, or release certificate as approved unless the corresponding approval records are present.