`plot2insights`¶

plot2insights is the unified plotting command for In-Sight.

It supports two modes:

BAM mode Primary user-facing mode.
CSV mode Advanced mode for debugging or rerendering from normalized tables.

Show Help¶

plot2insights --help

List Layouts¶

plot2insights --list-layouts

Current built-in layouts:

base
base-points
base-hsnp
bulkmonster
plain
workflow-better
workflow-barcode

BAM Mode¶

Minimal example:

plot2insights \
  --layout base \
  --bam sample.bam \
  --reference-fasta reference.fa \
  --region chr1:100-180 \
  --output result.pdf

Multiple regions:

plot2insights \
  --layout base \
  --bam sample.bam \
  --reference-fasta reference.fa \
  --region chr1:100-180 \
  --region chr1:220-260 \
  --output result.pdf

Barcode-aware layout:

plot2insights \
  --layout workflow-barcode \
  --bam sample.bam \
  --reference-fasta reference.fa \
  --region chr1:100-180 \
  --barcode-tag CB \
  --umi-tag UB \
  --output result.png

CSV Mode¶

CSV mode is useful if you already have standardized plotting tables.

plot2insights \
  --layout plain \
  --base-df base.csv \
  --read-df read.csv \
  --reference-df reference.csv \
  --output result.pdf

Mutation annotation example:

plot2insights \
  --layout base-hsnp \
  --base-df base.csv \
  --read-df read.csv \
  --reference-df reference.csv \
  --output result.pdf \
  --mut-start 101 \
  --mut-end 103 \
  --mut-type mismatch \
  --start-axis 0

Discover The Bundled R Script¶

Each layout maps to a bundled R script. You can inspect the exact resolved path:

plot2insights --layout base --show-r-script

This is useful when you want to understand or customize how a layout is rendered.

Use Your Own R Script¶

Inspect the built-in script:

plot2insights --layout base --show-r-script

Copy that script to your own location.
Modify it.
Pass it back through --r-script.

Example:

plot2insights \
  --layout base \
  --r-script ./my_plot_base.R \
  --bam sample.bam \
  --reference-fasta reference.fa \
  --region chr1:100-180 \
  --output result.pdf

Dry Run¶

Use --dry-run to inspect what will happen without actually running plotting.

CSV mode:

plot2insights \
  --layout plain \
  --base-df base.csv \
  --read-df read.csv \
  --reference-df reference.csv \
  --output result.pdf \
  --dry-run

BAM mode:

plot2insights \
  --layout base \
  --bam sample.bam \
  --reference-fasta reference.fa \
  --region chr1:100-180 \
  --output result.pdf \
  --dry-run

Tested Examples¶

Use the repository demo dataset in demo_data/.

CSV mode succeeded with:

plot2insights \
  --layout base \
  --base-df demo_data/example_base.csv \
  --read-df demo_data/example_read.csv \
  --reference-df demo_data/example_reference.csv \
  --output /tmp/insight-demo-base.png

BAM mode also succeeded after the pysam compatibility fix with:

plot2insights \
  --layout base \
  --bam demo_data/example_chr1_91150_91252.bam \
  --reference-fasta demo_data/example_chr1_1_91252.fa \
  --region 1:91150-91252 \
  --output /tmp/insight-demo-bam.pdf

For a dedicated walkthrough, see Demo Data.

plot2insights¶