Command-Line Interface

pycmplot exposes a full command-line interface that mirrors the Python API. After installation, the pycmplot command is available in your PATH.

pycmplot -h    # print full help

Input / output options

Flag	Default	Description
-s, --sum_stats	required	Comma-separated list of summary statistics files (gzip supported).
-l, --labels	required	Comma-separated track labels, one per file in --sum_stats.
-od, --output_dir	.	Output directory. Created if it does not exist.
-of, --output_format	png	Output image format: png, pdf, svg, or jpg.
--dpi	300	Resolution in dots per inch (raster formats only).

Column auto-detection options

pycmplot infers column names automatically. Use these flags only if your column names fall outside the recognised defaults.

Flag	Default	Description
-chr, --chrom_column	auto	Name of the chromosome column.
-pos, --pos_column	auto	Name of the base-pair position column.
-snp, --snp_column	auto	Name of the variant/marker ID column.
-p, --pval_column	auto	Name of the p-value (or test statistic) column.
-d, --delim	auto	Field delimiter (tab, space, comma, colon, semi-colon). Auto-detected when omitted.
-bc, --build_column	auto	Name of an in-file genome build column (values: hg18, hg19, hg38).
-b, --build	none	Comma-separated list of per-file genome builds in the same order as --sum_stats, used when the files have no build column (e.g. hg19,hg38,hg18). hg18 and hg19 coordinates are lifted to hg38 automatically before plotting.

Plotting behaviour options

Flag	Default	Description
-m, --mode	lm	Plot mode: lm (linear) or cm (circular).
--logp	off	Plot –log₁₀(p) instead of raw p-values.
-sig, --signif_threshold	off	Draw a genome-wide significance threshold line (auto 0.05/N).
-sigl, --signif_line	5e-8	Explicit significance threshold value; overrides --signif_threshold.
-sug, --suggest_threshold	off	Draw a suggestive significance threshold line.
-hl, --highlight	off	Highlight significant loci with a distinct colour.
-hc, --highlight_color	brown	Colour for highlighted variants.
-hll, --highlight_line	off	Draw a vertical dashed line through each highlighted locus.
-hlc, --highlight_line_color	grey	Colour of the highlight line.
-ht, --highlight_thresh	5e-8	P-value threshold for highlighting.
-a, --annotate	SNP	Annotate significant hits with SNP IDs, nearest GENE names, or any column available in the hits table (e.g. top_gene, nearest_upstream_gene).
-tp, --trim_pval	off	Exclude variants with p-value above this threshold (e.g. 0.01) before plotting. Strongly recommended for large files.
-st, --sort_track	input order	Sort tracks by label (alphabetical) or chrom_len (chromosome length, longest first).
--plot_title	(none)	Title string printed above the plot.

QQ plot options

Flag	Default	Description
-qq, --qq_plot	off	Generate QQ plot(s) alongside the Manhattan plot.
-qq_sep, --qq_separate	off	Save one QQ-plot file per summary statistics file.
-qq_ov, --qq_overlay	off	Overlay all sumstats on a single shared QQ axes, with λ in the legend.
-qq_cols, --qq_ncols	3	Number of columns in the combined QQ-plot grid.
-qq_thin, --qq_thin	off	Enable log-uniform p-value thinning for fast QQ plotting.
-thin_below, --thin_below	0.01	P-value threshold below which all points are kept (points above are downsampled when thinning is enabled).
-qq_max_pts, --qq_max_points	50000	Maximum points plotted per QQ track after thinning.

Example commands

Single-trait linear Manhattan plot

pycmplot \
  --sum_stats HbF.tsv.gz \
  --labels HbF \
  --logp \
  --signif_line \
  --highlight \
  --annotate GENE \
  --output_dir ./results \
  --output_format png \
  --dpi 300

Three-trait stacked linear Manhattan plot

pycmplot \
  --sum_stats HbF.tsv.gz,MCV.txt.gz,MCH.tsv.gz \
  --labels HbF,MCV,MCH \
  --logp \
  --signif_line \
  --highlight \
  --annotate GENE \
  --trim_pval 0.01 \
  --output_dir ./results

Circular Manhattan plot

pycmplot \
  --sum_stats HbF.tsv.gz,MCV.tsv.gz \
  --labels HbF,MCV \
  --mode cm \
  --trim_pval 0.01 \
  --logp \
  --signif_threshold \
  --plot_title "RBC Traits" \
  --output_dir ./results

Manhattan plot with companion QQ plots

pycmplot \
  --sum_stats HbF.tsv.gz,MCV.tsv.gz,MCH.tsv.gz \
  --labels HbF,MCV,MCH \
  --logp \
  --signif_line \
  --annotate GENE \
  --qq_plot \
  --qq_thin \
  --qq_ncols 3 \
  --output_dir ./results

Supplying per-file genome builds

When summary statistics files do not carry a BUILD column, supply the builds in the same order as --sum_stats:

pycmplot \
  --sum_stats hg19_study.tsv.gz,hg38_study.tsv.gz \
  --labels Study_A,Study_B \
  --build hg19,hg38 \
  --logp \
  --annotate GENE \
  --output_dir ./results