growthcurves.plot module

growthcurves.plot module#

Plotting functions for growth curve analysis using Plotly.

This module provides modular functions for creating and annotating growth curve plots.

growthcurves.plot.add_N0_line(fig: Figure, N0: float, scale: str = 'linear', line_color: str = 'gray', line_dash: str = 'dot', line_width: float = 2, line_opacity: float = 0.5, name: str = 'N0', row: int | None = None, col: int | None = None) → Figure[source]#

Add horizontal line at initial OD value (N0).

Parameters:

  • fig (gplotly.graph_objectso.Figure) – Plotly figure to annotate

  • N0 (float) – Initial OD value

  • scale (str, optional) – ‘linear’ or ‘log’ - determines y-axis transformation (default: ‘linear’)

  • line_color (str, optional) – Color of horizontal line (default: ‘gray’)

  • line_dash (str, optional) – Dash style for horizontal line (default: ‘dot’)

  • line_width (float, optional) – Width of horizontal line (default: 2)

  • line_opacity (float, optional) – Opacity of horizontal line (default: 0.5)

  • name (str, optional) – Legend name (default: ‘N0’)

  • row (int, optional) – Subplot row (for subplots)

  • col (int, optional) – Subplot column (for subplots)

Returns:

Updated figure with N0 horizontal line

Return type:

plotly.graph_objects.Figure

growthcurves.plot.add_exponential_phase(fig: Figure, exp_start: float, exp_end: float, color: str = 'lightgreen', opacity: float = 0.25, name: str = 'Exponential phase', row: int | None = None, col: int | None = None) → Figure[source]#

Add shaded region for exponential growth phase.

Parameters:

  • fig (plotly.graph_objects.Figure) – Plotly figure to annotate

  • exp_start (float) – Start time of exponential phase

  • exp_end (float) – End time of exponential phase

  • color (str, optional) – Color for shaded region (default: ‘lightgreen’)

  • opacity (float, optional) – Opacity of shaded region (default: 0.25)

  • name (str, optional) – Legend name (default: ‘Exponential phase’)

  • row (int, optional) – Subplot row (for subplots)

  • col (int, optional) – Subplot column (for subplots)

Returns:

Updated figure with exponential phase shading

Return type:

plotly.graph_objects.Figure

growthcurves.plot.add_fitted_curve(fig: Figure, time_fit: ndarray, N_fit: ndarray, name: str = 'Fitted curve', color: str = 'blue', line_width: int = 5, window_start: float | None = None, window_end: float | None = None, scale: str | None = 'linear', row: int | None = None, col: int | None = None) → Figure[source]#

Add fitted curve to the plot, optionally constrained to a window.

Parameters:

  • fig (plotly.graph_objects.Figure) – Plotly figure to annotate

  • time_fit (numpy.ndarray) – Time points for fitted curve

  • N_fit (numpy.ndarray) – Fitted y values

  • name (str, optional) – Legend name for fitted curve (default: ‘Fitted curve’)

  • color (str, optional) – Color of fitted curve (default: ‘blue’)

  • line_width (int, optional) – Width of fitted curve line (default: 5)

  • window_start (float, optional) – Start of fitting window (if specified, only show curve in this range)

  • window_end (float, optional) – End of fitting window (if specified, only show curve in this range)

  • scale (str, optional) – ‘linear’ or ‘log’ - determines y-axis transformation (default: ‘linear’)

  • row (int, optional) – Subplot row (for subplots)

  • col (int, optional) – Subplot column (for subplots)

Returns:

Updated figure with fitted curve

Return type:

plotly.graph_objects.Figure

growthcurves.plot.add_od_max_line(fig: Figure, od_max: float, scale: str = 'linear', line_color: str = 'black', line_dash: str = 'dot', line_width: float = 2, line_opacity: float = 0.5, name: str = 'ODmax', row: int | None = None, col: int | None = None) → Figure[source]#

Add horizontal line at maximum OD value.

Parameters:

  • fig (plotly.graph_objects.Figure) – Plotly figure to annotate

  • od_max (float) – Maximum OD value

  • scale (str, optional) – ‘linear’ or ‘log’ - determines y-axis transformation (default: ‘linear’)

  • line_color (str, optional) – Color of horizontal line (default: ‘red’)

  • line_dash (str, optional) – Dash style for horizontal line (default: ‘dash’)

  • line_width (float, optional) – Width of horizontal line (default: 1)

  • line_opacity (float, optional) – Opacity of horizontal line (default: 0.5)

  • name (str, optional) – Legend name (default: ‘ODmax’)

  • row (int, optional) – Subplot row (for subplots)

  • col (int, optional) – Subplot column (for subplots)

Returns:

Updated figure with od_max horizontal line

Return type:

plotly.graph_objects.Figure

growthcurves.plot.annotate_plot(fig: Figure, fit_result: Dict[str, Any] | None = None, stats: Dict[str, Any] | None = None, show_fitted_curve: bool = True, show_phase_boundaries: bool = True, show_crosshairs: bool = True, show_od_max_line: bool = True, show_n0_line: bool = True, show_umax_marker: bool = True, show_tangent: bool = True, scale: str = 'linear', fitted_curve_color: str = '#8dcde0', fitted_curve_width: int = 5, row: int | None = None, col: int | None = None) → Figure[source]#

Add annotations to a growth curve plot.

Parameters:

  • fig (plotly.graph_objects.Figure) – Plotly figure to annotate

  • fit_result (dict, optional) – Fit result dictionary from fit_parametric() or fit_non_parametric()

  • stats (dict, optional) – Statistics dictionary from extract_stats()

  • show_fitted_curve (bool, optional) – Whether to show the fitted curve (default: True)

  • show_phase_boundaries (bool, optional) – Whether to show exponential phase boundaries (default: True)

  • show_crosshairs (bool, optional) – Whether to show crosshairs to umax point (default: True)

  • show_od_max_line (bool, optional) – Whether to show horizontal line at maximum OD (default: True)

  • show_n0_line (bool, optional) – Whether to show horizontal line at initial OD (default: True)

  • show_umax_marker (bool, optional) – Whether to show marker at umax point (default: True)

  • show_tangent (bool, optional) – Whether to show tangent line at umax (default: True)

  • scale (str, optional) – ‘linear’ or ‘log’ for y-axis scale (default: ‘linear’)

  • fitted_curve_color (str, optional) – Color of the fitted model curve (default: ‘#8dcde0’)

  • fitted_curve_width (int, optional) – Line width of the fitted model curve (default: 5)

  • row (int, optional) – Subplot row for subplots

  • col (int, optional) – Subplot column for subplots

Returns:

Updated figure with annotations

Return type:

plotly.graph_objects.Figure

growthcurves.plot.create_base_plot(t: ndarray, N: ndarray, scale: str = 'linear', xlabel: str = 'Time (hours)', ylabel: str | None = None, marker_size: int = 5, marker_opacity: float = 0.3, marker_color: str = 'gray') → Figure[source]#

Create a base plot with raw N points.

Parameters:

  • t (numpy.ndarray) – Time points

  • N (numpy.ndarray) – OD measurements or other growth N

  • scale (str, optional) – ‘linear’ or ‘log’ scale for y-axis (default: ‘linear’)

  • xlabel (str, optional) – X-axis label (default: ‘Time (hours)’)

  • ylabel (str, optional) – Y-axis label. If None, automatically set based on scale

  • marker_size (int, optional) – Size of N point markers (default: 5)

  • marker_opacity (float, optional) – Opacity of N point markers (default: 0.3)

  • marker_color (str, optional) – Color of N point markers (default: ‘gray’)

Returns:

Plotly figure object with raw N

Return type:

plotly.graph_objects.Figure

growthcurves.plot.plot_derivative_metric(t: ndarray, N: ndarray, metric: str = 'mu', fit_result: Dict[str, Any] | None = None, sg_window: int = 11, sg_poly: int = 2, phase_boundaries: Tuple[float, float] | None = None, title: str | None = None, raw_line_width: int = 1, smoothed_line_width: int = 2, fitted_line_width: int = 2) → Figure[source]#

Plot either dN/dt or μ (specific growth rate) for a growth curve.

This function generates up to three traces: 1. Raw N metric (light grey) 2. Smoothed N metric (main trace, pink/red) 3. Model fit metric (dashed blue line, if fit_result provided)

Parameters:

  • t (numpy.ndarray) – Time array

  • N (numpy.ndarray) – OD600 values (baseline-corrected)

  • metric (str, optional) – Either “dndt” for dN/dt or “mu” for μ (default: “mu”)

  • fit_result (dict, optional) – Fit result dictionary from fit_parametric() or fit_non_parametric(). If provided, the fitted model’s derivative will be shown. Should contain ‘model_type’ and ‘params’ keys.

  • sg_window (int, optional) – Savitzky-Golay window size for smoothing (default: 11)

  • sg_poly (int, optional) – Savitzky-Golay polynomial order for smoothing (default: 2)

  • phase_boundaries (tuple of (float, float), optional) – Tuple of (exp_start, exp_end) for exponential phase boundaries. If provided, adds shading for the phase.

  • title (str, optional) – Plot title. If None, automatically generated based on metric.

  • raw_line_width (int, optional) – Line width of the raw metric trace (default: 1)

  • smoothed_line_width (int, optional) – Line width of the smoothed metric trace (default: 2)

  • fitted_line_width (int, optional) – Line width of the fitted model metric trace (default: 2)

Returns:

Plotly figure with derivative metric plot

Return type:

plotly.graph_objects.Figure

Examples

>>> import numpy as np
>>> from growthcurves import plot_derivative_metric, fit_non_parametric
>>>
>>> # Generate some example N
>>> t = np.linspace(0, 24, 100)
>>> N = 0.05 * np.exp(0.5 * t) / (1 + (0.05/2.0) * (np.exp(0.5 * t) - 1))
>>>
>>> # Plot specific growth rate without fit
>>> fig = plot_derivative_metric(t, N, metric="mu")
>>>
>>> # Plot with fitted model
>>> fit_result = fit_non_parametric(t, N, umax_method="spline")
>>> fig = plot_derivative_metric(
...     t, N,
...     metric="mu",
...     fit_result=fit_result,
...     phase_boundaries=(5, 15)
... )
growthcurves.plot.plot_growth_stats_comparison(stats_dict: Dict[str, Dict[str, Any]], title: str = 'Growth Statistics Comparison', metric_order: list | None = None) → Figure[source]#

Create a multi-panel bar chart comparing growth statistics across methods.

Parameters:

  • stats_dict (dict) – Dictionary mapping method names to their growth statistics dictionaries. Each stats dict should contain keys like ‘mu_max’, ‘doubling_time’, etc.

  • title (str, optional) – Overall title for the figure (default: “Growth Statistics Comparison”)

  • metric_order (list, optional) – List of metric keys to plot in specific order. If None, uses default order.

Returns:

Plotly figure with subplots showing each metric comparison

Return type:

plotly.graph_objects.Figure

Examples

>>> # Compare multiple fitting methods
>>> stats_dict = {
...     'logistic': stats_logistic,
...     'gompertz': stats_gompertz,
...     'spline': stats_spline
... }
>>> fig = plot_growth_stats_comparison(
...     stats_dict,
...     title="Model Comparison"
... )
>>> fig.show()
growthcurves.plot.prepare_fitted_curve(fitted_model: Dict[str, Any], n_points: int = 200) → Tuple[ndarray, ndarray] | None[source]#

Convert a fitted model dictionary to curve data for plotting.

Parameters:

  • fitted_model (dict) – Fit result dictionary from fit_parametric() or fit_non_parametric()

  • n_points (int, optional) – Number of points to generate for the curve (default: 200)

Returns:

(time_points, od_values) ready for plotting, or None if invalid

Return type:

tuple of (np.ndarray, np.ndarray) or None

growthcurves.plot.prepare_tangent_line(umax: float, time_umax: float, od_umax: float, fig: Figure, scale: str | None = 'linear', n_points: int | None = 100) → Tuple[ndarray, ndarray] | None[source]#

Calculate tangent line at maximum growth rate point.

Parameters:

  • umax (float) – Maximum growth rate (μ_max)

  • time_umax (float) – Time at maximum growth rate

  • od_umax (float) – OD value at maximum growth rate

  • fig (plotly.graph_objects.Figure) – Figure to extract data range from

  • scale (str, optional) – ‘linear’ or ‘log’ for determining data range (default: ‘linear’)

  • n_points (int, optional) – Number of points to generate for tangent line (default: 100)

Returns:

(time_points, od_values) for tangent line, or None if invalid

Return type:

tuple of (numpy.ndarray, numpy.ndarray) or None

Contents