Skip to content

CLI Reference

The fastdpplot console script (entry-point cli.main:main) provides two sub-commands: bin (binary matrix + two FASTA files) and plot (Parquet or delimited-text input).

fastdpplot <subcommand> [options]

Backward-compatible invocation

When no sub-command is given, fastdpplot automatically routes to the bin sub-command. So the following two calls are equivalent:

fastdpplot bin --matrix m.bin --fasta-a a.fasta --fasta-b b.fasta --dp-path path.txt --output out.png
fastdpplot     --matrix m.bin --fasta-a a.fasta --fasta-b b.fasta --dp-path path.txt --output out.png

bin — Binary DP matrix + two FASTA files

fastdpplot bin --matrix <file> --fasta-a <file> --fasta-b <file> --dp-path <file> [options]

Required

Flag Description
--matrix FILE Path to the raw binary .bin scoring matrix.
--fasta-a FILE Query FASTA file (rows of the matrix).
--fasta-b FILE Subject FASTA file (columns of the matrix).
--dp-path FILE DP traceback path file (.txt). Two whitespace-separated non-negative integer columns per line, no header. Column 1 = sequence A position (X-axis), column 2 = sequence B position (Y-axis).

Optional — rendering

Flag Default Description
--output FILE (required without --serve) Output .png or .svg path.
--width N 4000 Canvas width in pixels.
--height N 4000 Canvas height in pixels.
--dpi N 600 Output DPI (PNG only).
--serve false Launch interactive Panel server.
--port N 5006 TCP port for the Panel server.
--xlim X_MIN X_MAX (full range) Clip the static export to this x-axis window.
--ylim Y_MIN Y_MAX (full range) Clip the static export to this y-axis window.

Viewport-bounded export

--xlim and --ylim are appended automatically by the GUI when the interactive viewer is open, so the exported PNG/SVG exactly matches the current zoom level. You can also pass them manually on the command line to export a specific region without launching the viewer.

Examples

# Static PNG from data/ directory
fastdpplot bin \
    --matrix   data/dp_matrix.bin \
    --fasta-a  data/query.fasta \
    --fasta-b  data/subject.fasta \
    --dp-path  data/dp_path.txt \
    --output   dotplot.png

# Custom output size
fastdpplot bin \
    --matrix   data/dp_matrix.bin \
    --fasta-a  data/query.fasta \
    --fasta-b  data/subject.fasta \
    --dp-path  data/dp_path.txt \
    --width    6000 --height 6000 \
    --output   dotplot_large.png

# Export only a specific region
fastdpplot bin \
    --matrix   data/dp_matrix.bin \
    --fasta-a  data/query.fasta \
    --fasta-b  data/subject.fasta \
    --dp-path  data/dp_path.txt \
    --xlim 100 800 --ylim 0 600 \
    --output   region.png

# Interactive server
fastdpplot bin \
    --matrix  data/dp_matrix.bin \
    --fasta-a data/query.fasta \
    --fasta-b data/subject.fasta \
    --dp-path data/dp_path.txt \
    --serve   --port 5006

Transposed matrices

If the matrix rows/columns are swapped relative to the FASTA lengths, fastdpplot automatically retries with the dimensions transposed and prints a warning: warning: matrix appears transposed; swapping query/subject axes.

--output is required when not using --serve

If you forget --output without --serve, the tool exits with an error rather than silently discarding the rendered image.

plot — Parquet or delimited text

fastdpplot plot --input <file> [options]

Required

Flag Description
--input FILE Path to a .parquet file or a delimited text file.

Optional — data parsing (text files)

Flag Default Description
--sep SEP \t Field separator character for text input.
--x-col N 0 Zero-based column index for the X coordinate.
--y-col N 1 Zero-based column index for the Y coordinate.
--val-col N (none) Zero-based column index for the value/score. Omit to give every point value=1.0.

Optional — rendering

Flag Default Description
--output FILE (required without --serve) Output .png or .svg path.
--width N 4000 Canvas width in pixels.
--height N 4000 Canvas height in pixels.
--dpi N 600 Output DPI (PNG only).
--serve false Launch interactive Panel server instead of saving a file.
--port N 5006 TCP port for the Panel server.
--xlim X_MIN X_MAX (full range) Clip the static export to this x-axis window.
--ylim Y_MIN Y_MAX (full range) Clip the static export to this y-axis window.

Examples

# Parquet input → static PNG
fastdpplot plot --input hits.parquet --output plot.png

# Tab-separated BLAST tabular output, identity in column 2
fastdpplot plot \
    --input hits.txt \
    --x-col 6 --y-col 8 --val-col 2 \
    --output dotplot.png

# Export only a zoomed-in region
fastdpplot plot \
    --input hits.parquet \
    --xlim 200 900 --ylim 50 750 \
    --output region.png

# Interactive server
fastdpplot plot --input hits.parquet --serve --port 8080