# Plot Vcfstats

> Use when converting `bcftools stats` output into variant-QC plots, per-sample PNG panels, and optional PDF summaries.

- Skill: `vimalinx/plot-vcfstats` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add vimalinx/plot-vcfstats`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vimalinx/plot-vcfstats/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: vimalinx (https://skillmd.com/u/vimalinx)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/vimalinx/plot-vcfstats

---


# 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

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

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

```bash
# 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.