plotly_plotter Module#

Plotly rendering backend for Episia.

This is the default backend, producing interactive HTML figures suitable for notebooks, web applications, and standalone HTML exports.

Class#

class episia.viz.plotters.plotly_plotter.PlotlyPlotter(config=None)[source]#

Bases: BasePlotter

Plotly rendering backend.

Returns plotly.graph_objects.Figure objects. Call .show() to display, .to_json() to serialize for React/JS.

Animations supported – FRAME_BY_FRAME : plot_epicurve, plot_forest, plot_diagnostic CONTINUOUS : plot_model, plot_roc PLAY_PAUSE : plot_epicurve, plot_model SLIDER : plot_model

Parameters:

config (Optional[PlotConfig])

BACKEND_NAME: str = 'plotly'#

Human-readable backend name used in error messages.

SUPPORTED_ANIMATIONS: Tuple[AnimationType, ...] = (AnimationType.FRAME_BY_FRAME, AnimationType.CONTINUOUS, AnimationType.PLAY_PAUSE, AnimationType.SLIDER)#

AnimationTypes this backend can handle.

plot_association(result, config=None)[source]#

Single association measure horizontal CI plot with reference line. Static (no animation by design).

Parameters:
Return type:

Any

plot_contingency(result, config=None)[source]#

2x2 contingency table annotated heatmap with risk summary. Static (no animation by design).

Parameters:
Return type:

Any

plot_diagnostic(result, config=None)[source]#

Diagnostic test dashboard: confusion matrix heatmap + metrics bars.

Animation (FRAME_BY_FRAME):

Metric bars fill in one by one.

Parameters:
Return type:

Any

plot_epicurve(result, config=None)[source]#

Epidemic curve bar chart of cases over time.

Animation (FRAME_BY_FRAME / PLAY_PAUSE):

Bars build up period by period from left to right.

Parameters:
Return type:

Any

plot_forest(result, config=None)[source]#

Forest plot for stratified (MH) or regression results.

Animation (FRAME_BY_FRAME):

Rows appear one by one from top to bottom.

Parameters:
Return type:

Any

plot_model(result, config=None)[source]#

Compartmental model trajectories (SIR / SEIR / SEIRD…).

Animation (CONTINUOUS / PLAY_PAUSE / SLIDER):

Lines draw from t=0 forward, one frame per time step. SLIDER adds an interactive time scrubber.

Parameters:
Return type:

Any

plot_roc(result, config=None)[source]#

ROC curve with AUC annotation and optimal threshold marker.

Animation (CONTINUOUS):

The curve traces itself from (0,0) to (1,1) point by point, simulating a threshold sweep from high to low.

Parameters:
Return type:

Any

save(fig, path, fmt=OutputFormat.PNG, dpi=150)[source]#

Save a Plotly figure to disk.

Supports: PNG, SVG, PDF (via kaleido), HTML, JSON.

Parameters:
Return type:

str

Animation Support#

The Plotly backend supports:

  • FRAME_BY_FRAME: Bars/build-up for epidemic curves and forest plots

  • CONTINUOUS: Smooth line drawing for model trajectories and ROC curves

  • PLAY_PAUSE: Auto-play with controls

  • SLIDER: Interactive time slider for model simulations

Examples#

Basic usage:

from episia.viz.plotters import get_plotter

# Get Plotly backend (default)
plotter = get_plotter("plotly")

# Plot with default settings
fig = plotter.plot_epicurve(result)
fig.show()

# Plot with custom configuration
from episia.viz.plotters.base_plotter import PlotConfig

config = PlotConfig.dark(title="Ebola Outbreak 2014")
fig = plotter.plot_model(result, config=config)

Animated plots:

from episia.viz.plotters.base_plotter import AnimationConfig

# Create animated epidemic curve
anim_config = PlotConfig(
    title="Weekly Cases Buildup",
    animation=AnimationConfig.frame_buildup(n_frames=52)
)
fig = plotter.plot_epicurve(result, config=anim_config)

# Smooth trajectory animation
smooth_config = PlotConfig(
    title="SEIR Model Simulation",
    animation=AnimationConfig.smooth(duration_ms=5000)
)
fig = plotter.plot_model(result, config=smooth_config)

Saving figures:

from episia.viz.plotters.base_plotter import OutputFormat

# Save as interactive HTML
plotter.save(fig, "output.html", fmt=OutputFormat.HTML)

# Save as static image (requires kaleido)
plotter.save(fig, "figure", fmt=OutputFormat.PNG, dpi=300)

Web integration:

# Serialize for React/JavaScript
import json
fig_json = fig.to_json()

# Or use browser utilities
from episia.viz.plotters.browser_plotter import to_react_props

props = to_react_props(fig)
# Pass props['data'] and props['layout'] to react-plotly.js