Skip to content

fastdpplot.plot — Rendering

Source: fastdpplot/plot.py

Three rendering modes are provided:

Function Mode Output
render_static Offline rasterisation PNG or SVG file
serve_interactive Live Panel server Browser window
show Jupyter inline Notebook cell

render_static(df, output_path, …)

Rasterise a dot-point DataFrame with matplotlib and save to a PNG or SVG file. Each point is coloured according to its value using a diverging red → gray → green colormap anchored at zero.

Parameters

Parameter Type Default Description
df pd.DataFrame — DataFrame with columns x, y, value.
output_path str — Destination file path. Extension determines format (.png or .svg).
width int 4000 Canvas width in pixels (retained for API compatibility).
height int 4000 Canvas height in pixels (retained for API compatibility).
dpi int 150 Output DPI (PNG only).
x_label str \| None None X-axis label.
y_label str \| None None Y-axis label.
x_range tuple — Required. (x_min, x_max) axis limits. Pass result['x_range'] or the data-derived range.
y_range tuple — Required. (y_min, y_max) axis limits. Pass result['y_range'] or the data-derived range.

x_range and y_range are required

Omitting either argument raises ValueError. For .bin pipelines, pass result["x_range"] and result["y_range"] from load_bin. For Parquet/text inputs, derive them from the DataFrame: 

x_range = (float(df["x"].min()), float(df["x"].max()))
y_range = (float(df["y"].min()), float(df["y"].max()))

Examples

from fastdpplot.io import load_bin
from fastdpplot.plot import render_static

result = load_bin("data/dp_matrix.bin", "data/q.fasta", "data/s.fasta")

render_static(
    result["df"],
    output_path="dotplot.png",
    width=6000,
    height=6000,
    x_label=result["x_label"],
    y_label=result["y_label"],
    x_range=result["x_range"],
    y_range=result["y_range"],
)

Axis off when no labels

When both x_label and y_label are None, matplotlib's axes are hidden (ax.axis("off")) to produce a clean image without tick marks.

serve_interactive(df, port, title, …)

Launch a Panel/Bokeh server backed by the Rust binning engine.

On every pan/zoom event the visible viewport is re-binned in Rust (fastdpplot._rs.bin_points_py) and a small DataFrame is reconstructed for datashader. This allows interactive exploration of matrices with hundreds of millions of points.

The server also exposes a lightweight HTTP endpoint:

GET /range

which returns the live viewport as JSON:

{"x_range": [120.0, 850.0], "y_range": [0.0, 600.0]}

The GUI queries this endpoint before exporting a static image so that --xlim/--ylim are set to exactly what the user sees.

Parameters

Parameter Type Default Description
df pd.DataFrame — Full dot-point DataFrame.
port int 5006 TCP port for the Panel server.
title str "fastdpplot" Browser tab title.
x_label str \| None None X-axis label.
y_label str \| None None Y-axis label.
x_range tuple \| None None Initial X viewport. Defaults to full data range.
y_range tuple \| None None Initial Y viewport. Defaults to full data range.

Examples

from fastdpplot.io import load_bin
from fastdpplot.plot import serve_interactive

result = load_bin("data/dp_matrix.bin", "data/q.fasta", "data/s.fasta")

serve_interactive(
    result["df"],
    port=5006,
    x_label=result["x_label"],
    y_label=result["y_label"],
    x_range=result["x_range"],
    y_range=result["y_range"],
)

Rust-free fallback

If fastdpplot._rs is not available, serve_interactive falls back to filtering the full DataFrame on each zoom event instead of re-binning in Rust. This is slower but functional for small datasets.

Blocking call

serve_interactive calls panel.serve(…, show=False), which blocks the current thread. Run it in a dedicated script or notebook cell.

show(df, width, height, …)

Display a datashaded dotplot inline in a Jupyter notebook. Points are aggregated via ds.mean("value") and coloured using the same diverging red → gray → green colormap as render_static.

Parameters

Parameter Type Default Description
df pd.DataFrame — DataFrame with columns x, y, value.
width int 800 Canvas width in pixels.
height int 800 Canvas height in pixels.
x_label str \| None None X-axis label.
y_label str \| None None Y-axis label.
x_range tuple \| None None (x_min, x_max) axis limits.
y_range tuple \| None None (y_min, y_max) axis limits.

Returns

A renderable HoloViews / datashader object that Jupyter displays automatically.

Examples

from fastdpplot.io import load_bin
from fastdpplot.plot import show

result = load_bin("data/dp_matrix.bin", "data/q.fasta", "data/s.fasta")

show(
    result["df"],
    width=1000,
    height=1000,
    x_label=result["x_label"],
    y_label=result["y_label"],
)