plot-vcfstats

name	plot-vcfstats
description	Use when converting `bcftools stats` output into variant-QC plots, per-sample PNG panels, and optional PDF summaries.
disable-model-invocation	true
user-invocable	true

plot-vcfstats

Perl plotting helper for bcftools stats. It parses one or more .vchk files, writes an output directory with plot.py, PNG images, and intermediate .dat tables, and optionally tries to render a PDF report.

Quick Start

• Command: plot-vcfstats -p <outdir> <file.vchk>
• Local executable: /home/vimalinx/miniforge3/envs/bio/bin/plot-vcfstats
• Upstream producer: bcftools stats

When To Use This Tool

• Plotting output from bcftools stats into PDF visualizations
• Merging multiple vcfstats files into a single stream
• Generating per-sample PNG QC panels without writing custom plotting code
• Editing the auto-generated plot.py if the default aesthetics are not enough

Common Patterns

# 1) Generate stats and plot them
bcftools stats -s - calls.vcf.gz > calls.vchk
plot-vcfstats -p outdir calls.vchk

# 2) Skip PDF generation when LaTeX is unavailable
plot-vcfstats -P -p outdir calls.vchk

# 3) Merge multiple stats files instead of plotting
plot-vcfstats -m sample1.vchk sample2.vchk > merged.vchk

Recommended Workflow

1. Generate a real .vchk file with bcftools stats; this tool validates the file header and will reject hand-rolled approximations.
2. Plot into a dedicated output directory via -p.
3. If you only need PNG/data outputs, add -P to bypass PDF rendering.
4. Customize outdir/plot.py and rerun it manually if the stock plots need layout or style changes.

Guardrails

• --help works, but --version is not a real metadata path; it is treated as an unknown parameter.
• A fake .vchk file failed with Sanity check failed: was this file generated by bcftools stats?, so input validation is strict.
• In live testing, a real one-record .vchk plus -P successfully generated files such as plot.py, plot-vcfstats.log, snps_by_sample.0.png, and several *.dat tables.
• Without -P, the same run failed at the PDF stage because neither pdflatex nor tectonic was installed.
• -m/--merge skips plotting and writes merged stats to stdout instead.