curves Module#

Epidemic curve and trend visualizations.

This module provides functions for plotting epidemic curves, incidence rates, trend lines, and growth curves with doubling time annotations.

Functions#

episia.viz.curves.plot_epicurve(result=None, *, times=None, values=None, title='Epidemic Curve', xlabel='Period', ylabel='Cases', backend='plotly', theme='scientific', animate=False, config=None)[source]#

Plot an epidemic curve (cases over time) as a bar chart.

Parameters:

  • result (Any | None) – TimeSeriesResult, EpidemicCurve, or None (use times/values).

  • times (ndarray | None) – Array of time labels (used if result is None).

  • values (ndarray | None) – Array of case counts (used if result is None).

  • title (str) – Figure title.

  • xlabel (str) – X-axis label.

  • ylabel (str) – Y-axis label.

  • backend (str) – ‘plotly’ (default) or ‘matplotlib’.

  • theme (str) – Theme name.

  • animate (bool) – If True, bars build up frame by frame (Plotly only).

  • config (PlotConfig | None) – Full PlotConfig override supersedes individual args.

Returns:

plotly.graph_objects.Figure or matplotlib.figure.Figure

Return type:

Any

Examples:

# From a TimeSeriesResult
fig = plot_epicurve(result, title="Ebola 2014  Guinea")
fig.show()

# From raw arrays
fig = plot_epicurve(times=weeks, values=counts, animate=True)

# Publication export
fig = plot_epicurve(result, backend="matplotlib")
fig.savefig("figure1.pdf", dpi=300, bbox_inches="tight")
episia.viz.curves.plot_trend(result=None, *, times=None, values=None, show_observed=True, title='Trend Analysis', xlabel='Period', ylabel='Value', backend='plotly', theme='scientific', config=None)[source]#

Plot a trend line with optional observed values overlay.

Parameters:

  • result (Any | None) – TimeSeriesResult with a trend array, or raw input.

  • show_observed (bool) – If True, plot observed values as scatter points.

  • title (str) – Figure title.

  • ylabel (str) – Axis labels.

  • backend (str) – ‘plotly’ or ‘matplotlib’.

  • theme (str) – Theme name.

  • config (PlotConfig | None) – Full PlotConfig override.

  • times (ndarray | None)

  • values (ndarray | None)

  • xlabel (str)

  • ylabel

Returns:

Figure object.

Return type:

Any

Examples:

fig = plot_trend(result, show_observed=True, title="Weekly incidence trend")
episia.viz.curves.plot_incidence(result=None, *, times=None, rates=None, ci_lower=None, ci_upper=None, per=100000, title='Incidence Rate', xlabel='Period', ylabel=None, backend='plotly', theme='scientific', config=None)[source]#

Plot incidence rate over time with optional confidence interval band.

Parameters:

  • result (Any | None) – TimeSeriesResult or EpidemicCurve (rates taken from values).

  • times (ndarray | None) – Time labels array.

  • rates (ndarray | None) – Incidence rate array.

  • ci_lower (ndarray | None) – Lower CI bound array (optional).

  • ci_upper (ndarray | None) – Upper CI bound array (optional).

  • per (int) – Population denominator for ylabel label (default 100 000).

  • title (str) – Figure title.

  • xlabel (str) – X-axis label.

  • ylabel (str | None) – Y-axis label (auto-generated if None).

  • backend (str) – ‘plotly’ or ‘matplotlib’.

  • theme (str) – Theme name.

  • config (PlotConfig | None) – Full PlotConfig override.

Returns:

Figure object.

Return type:

Any

episia.viz.curves.plot_doubling(result=None, *, times=None, values=None, doubling_time=None, title='Growth Curve', xlabel='Period', ylabel='Cases (log scale)', backend='plotly', theme='scientific', config=None)[source]#

Plot cumulative cases on a log scale with doubling time annotation.

Parameters:

  • result (Any | None) – TimeSeriesResult (doubling_time read from object if present).

  • times (ndarray | None) – Time labels.

  • values (ndarray | None) – Cumulative case counts.

  • doubling_time (float | None) – Doubling time in periods (overrides result attribute).

  • ylabel (str) – Labels.

  • backend (str) – ‘plotly’ or ‘matplotlib’.

  • theme (str) – Theme name.

  • config (PlotConfig | None) – Full PlotConfig override.

  • title (str)

  • xlabel (str)

  • ylabel

Returns:

Figure object.

Return type:

Any

Examples#

Basic epidemic curve:

from episia.viz.curves import plot_epicurve
from episia.stats.time_series import epidemic_curve

# Create epidemic curve from case data
curve = epidemic_curve(dates, cases, aggregation='weekly')

# Plot with default settings
fig = plot_epicurve(curve, title="Weekly COVID-19 Cases")
fig.show()

Animated epidemic curve:

# Animated version (bars build up)
fig = plot_epicurve(
    curve,
    title="Epidemic Progression",
    animate=True,
    backend="plotly"
)
fig.show()

Trend analysis:

from episia.viz.curves import plot_trend

fig = plot_trend(
    result,  # TimeSeriesResult object
    show_observed=True,
    title="Incidence Trend with LOESS Smoothing"
)

Incidence rates with confidence bands:

from episia.viz.curves import plot_incidence

fig = plot_incidence(
    times=weeks,
    rates=incidence_rates,
    ci_lower=ci_lower,
    ci_upper=ci_upper,
    per=100000,
    title="Weekly Incidence Rate per 100,000"
)

Doubling time plot:

from episia.viz.curves import plot_doubling

fig = plot_doubling(
    times=days[:30],
    values=cumulative_cases[:30],
    doubling_time=3.2,
    title="Early Exponential Growth",
    ylabel="Cumulative Cases (log scale)"
)