Plotting

Matplotlib-based visualisation utilities. All functions return a Figure object — the caller controls output (display, save, etc.).

Requires the plot optional dependency:

uv add "craeft[plot]"

plotting

Static plotting with matplotlib for publication-quality figures.

This module is decoupled from domain objects - it accepts only numpy arrays.

plot_sir

plot_sir(
    t: NDArray[float64],
    s_mean: NDArray[float64],
    i_mean: NDArray[float64],
    r_mean: NDArray[float64],
    s_std: NDArray[float64] | None = None,
    i_std: NDArray[float64] | None = None,
    r_std: NDArray[float64] | None = None,
    confidence: float = 1.0,
) -> Figure

Plot all three SIR compartments.

Parameters:

Name	Type	Description	Default
t	NDArray[float64]	Time array.	required
s_mean	NDArray[float64]	Mean susceptible counts.	required
i_mean	NDArray[float64]	Mean infected counts.	required
r_mean	NDArray[float64]	Mean recovered counts.	required
s_std	NDArray[float64] | None	Optional std for confidence band.	None
i_std	NDArray[float64] | None	Optional std for confidence band.	None
r_std	NDArray[float64] | None	Optional std for confidence band.	None
confidence	float	Number of standard deviations for bands.	1.0

Returns:

Type	Description
Figure	Matplotlib Figure.

plot_trajectories

plot_trajectories(
    t_grid: NDArray[float64],
    trajectories: NDArray[float64],
    mean: NDArray[float64] | None = None,
    compartment: Compartment = "I",
    trajectory_alpha: float = 0.1,
    trajectory_color: str = "grey",
    mean_color: str | None = None,
) -> Figure

Plot individual trajectories with optional mean overlay (spaghetti plot).

Parameters:

Name	Type	Description	Default
t_grid	NDArray[float64]	Common time grid for all trajectories.	required
trajectories	NDArray[float64]	Array of shape (n_runs, n_points) with interpolated values.	required
mean	NDArray[float64] | None	Optional pre-computed mean. If None, computed from trajectories.	None
compartment	Compartment	Compartment label for y-axis and mean color.	'I'
trajectory_alpha	float	Transparency for individual lines.	0.1
trajectory_color	str	Color for individual lines.	'grey'
mean_color	str | None	Color for mean line (defaults to compartment color).	None

Returns:

Type	Description
Figure	Matplotlib Figure.

plot_prevalence_comparison

plot_prevalence_comparison(
    results: list[
        tuple[
            str,
            NDArray[float64],
            NDArray[float64],
            NDArray[float64] | None,
        ]
    ],
    colors: list[str] | None = None,
    confidence: float = 1.0,
) -> Figure

Plot prevalence (I) curves for multiple networks on the same axes.

Useful for comparing epidemic dynamics across networks with different structural properties (e.g., different clustering coefficients).

Parameters:

Name	Type	Description	Default
results	list[tuple[str, NDArray[float64], NDArray[float64], NDArray[float64] | None]]	List of (label, t, i_mean, i_std) tuples. Each tuple contains: - label: Legend label for this curve - t: Time array - i_mean: Mean infected counts - i_std: Optional standard deviation for confidence band	required
colors	list[str] | None	Optional list of colors (one per result). Defaults to a colorblind-friendly palette.	None
confidence	float	Number of standard deviations for confidence bands.	1.0

Returns:

Type	Description
Figure	Matplotlib Figure.

Example

results = [ ... ("φ=0.0", t1, i_mean1, i_std1), ... ("φ=0.3", t2, i_mean2, i_std2), ... ] fig = plot_prevalence_comparison(results)