epydemix.visualization package

Submodules

epydemix.visualization.plotting module

epydemix.visualization.plotting.get_black_to_grey(n)

Generate n grayscale colors starting with pure black.

epydemix.visualization.plotting.get_timeseries_data(df_quantiles: DataFrame, column: str, quantile: float) → DataFrame

Extracts the time series data for a specific column (compartment or demographic group) and quantile.

Parameters:

• df_quantiles (pd.DataFrame) – DataFrame containing quantile data for compartments and demographic groups.

• column (str) – The name of the column to extract data for.

• quantile (float) – The quantile to extract data for.

Returns:

A DataFrame containing the time series data for the specified column and quantile.

Return type:

pd.DataFrame

epydemix.visualization.plotting.plot_contact_matrix(population: Any, layer: str, ax: Axes | None = None, cmap: str = 'YlOrRd', show_values: bool = False, title: str | None = None, show_colorbar: bool = True, fmt: str = '.1f', fontsize: int = 8, rotation: int = 45, figsize: Tuple[int, int] = (10, 8), vmin: float | None = None, vmax: float | None = None, origin: str = 'lower') → Axes

Plot a contact matrix heatmap.

Parameters:

• population – Population object containing contact matrices

• layer – Name of the contact layer to plot

• ax – Matplotlib axes to plot on. Creates new figure if None

• cmap – Colormap for the heatmap

• show_values – Whether to show numerical values in cells

• title – Plot title. If None, uses layer name

• colorbar – Whether to show the colorbar

• fmt – Format string for cell values

• fontsize – Font size for labels and values

• rotation – Rotation angle for x-axis labels

• figsize – Figure size if creating new figure

• vmin – Minimum value for colormap scaling

• vmax – Maximum value for colormap scaling

• origin – Whether to plot the matrix with the origin at the bottom left (default) or top left

Returns:

The matplotlib axes object

Return type:

plt.Axes

Raises:

KeyError – If specified layer doesn’t exist

epydemix.visualization.plotting.plot_distance_distribution(distances: ndarray | List[float] | Series, ax: Axes | None = None, kind: str = 'hist', color: str = 'dodgerblue', xlabel: str | None = None, ylabel: str | None = None, title: str | None = None, fontsize: int = 10, show_grid: bool = True, show_kde: bool = True, show_rug: bool = False, figsize: Tuple[int, int] = (10, 4), xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, stat: str = 'density', bins: int | str = 'auto', alpha: float = 0.4, vertical_lines: Dict[str, Dict[str, Any]] | None = None, **kwargs) → Axes

Plots the distribution of distances/errors from calibration.

Parameters:

• distances – Array-like object containing the distance/error values

• ax – Matplotlib axes to plot on. Creates new figure if None

• kind – Type of plot (‘hist’, ‘kde’, or ‘ecdf’)

• color – Color for the plot

• xlabel – X-axis label

• ylabel – Y-axis label

• title – Plot title

• fontsize – Base font size for labels and ticks

• show_grid – Whether to show grid lines

• show_kde – Whether to show KDE curve with histogram (only for kind=’hist’)

• show_rug – Whether to show rug plot

• figsize – Figure size if creating new figure

• xlim – Tuple of (min, max) for x-axis limits

• ylim – Tuple of (min, max) for y-axis limits

• stat – Statistic to plot for histogram (‘count’, ‘density’, ‘probability’)

• bins – Number of bins or method for histogram

• alpha – Transparency of the plot

• vertical_lines –

  Dict of vertical lines to add, format: {

  ’name’: {

  ‘x’: value, ‘color’: ‘color’, ‘linestyle’: ‘–‘, ‘label’: ‘label’

  }

  }

• **kwargs – Additional arguments passed to plotting functions

Returns:

The matplotlib axes object

Return type:

plt.Axes

Raises:

ValueError – If kind is not ‘hist’, ‘kde’, or ‘ecdf’

epydemix.visualization.plotting.plot_population(population: Any, ax: Axes | None = None, title: str | None = None, color: str = 'dodgerblue', show_perc: bool = False, fontsize: int = 10, rotation: int = 45, figsize: Tuple[int, int] = (10, 6), bar_width: float = 0.8, show_grid: bool = True, ylabel: str | None = None, xlabel: str = 'Demographic group', show_values: bool = True, fmt: str | None = None, value_fontsize: int | None = None) → Axes

Plot the population distribution across demographic groups.

Parameters:

• population – Population object containing demographic data

• ax – Matplotlib axes to plot on. Creates new figure if None

• title – Plot title. If None, uses default title

• color – Color for the bars

• show_perc – Whether to show population as percentages

• fontsize – Base font size for labels and ticks

• rotation – Rotation angle for x-axis labels

• figsize – Figure size if creating new figure

• bar_width – Width of the bars (between 0 and 1)

• show_grid – Whether to show grid lines

• ylabel – Y-axis label. If None, uses default based on show_perc

• xlabel – X-axis label

• show_values – Whether to show values above bars

• fmt – Format string for values. If None, uses “.1f%” for percentages and human-readable suffixes (K/M/B) for absolute numbers.

• value_fontsize – Font size for bar values. If None, uses fontsize

Returns:

The matplotlib axes object

Return type:

plt.Axes

epydemix.visualization.plotting.plot_posterior_distribution(posterior: DataFrame, parameter: str, ax: Axes | None = None, xlabel: str | None = None, ylabel: str | None = None, kind: str = 'hist', color: str = 'dodgerblue', xlim: Tuple[float, float] | None = None, prior: Any | None = None, prior_range: bool = False, title: str | None = None, fontsize: int = 10, show_grid: bool = True, show_kde: bool = True, show_rug: bool = False, figsize: Tuple[int, int] = (10, 4), stat: str = 'density', bins: int | str = 'auto', alpha: float = 0.4, vertical_lines: Dict[str, Dict[str, Any]] | None = None, **kwargs) → Axes

Plots the distribution of a parameter.

Parameters:

• posterior – DataFrame containing the parameter values

• parameter – The parameter to plot

• ax – Matplotlib axes to plot on. Creates new figure if None

• xlabel – X-axis label. If None, uses parameter name

• ylabel – Y-axis label

• kind – Type of plot (‘hist’, ‘kde’, or ‘ecdf’)

• color – Color for the plot

• xlim – Tuple of (min, max) for x-axis limits

• prior – Prior distribution object with ppf method

• prior_range – Whether to set x-axis limits to prior range

• title – Plot title. If None, auto-generates

• fontsize – Base font size for labels and ticks

• show_grid – Whether to show grid lines

• show_kde – Whether to show KDE curve with histogram (only for kind=’hist’)

• show_rug – Whether to show rug plot

• figsize – Figure size if creating new figure

• stat – Statistic to plot (‘count’, ‘density’, ‘probability’)

• bins – Number of bins or method for histogram

• alpha – Transparency of the plot

• vertical_lines –

  Dict of vertical lines to add, format: {

  ’name’: {

  ‘x’: value, ‘color’: ‘color’, ‘linestyle’: ‘–‘, ‘label’: ‘label’

  }

  }

• **kwargs – Additional arguments passed to plotting functions

Returns:

The matplotlib axes object

Return type:

plt.Axes

Raises:

• ValueError – If kind is not ‘hist’, ‘kde’, or ‘ecdf’

• ValueError – If prior_range is True but no prior is provided

epydemix.visualization.plotting.plot_posterior_distribution_2d(posterior: DataFrame, parameter_x: str, parameter_y: str, ax: Axes | None = None, xlabel: str | None = None, ylabel: str | None = None, kind: str = 'hist', palette: str = 'Blues', xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, prior_x: Any | None = None, prior_y: Any | None = None, prior_range: bool = False, title: str | None = None, fontsize: int = 10, cmap: str | None = None, show_grid: bool = True, levels: int = 10, figsize: Tuple[int, int] = (6, 6), scatter: bool = False, scatter_alpha: float = 0.5, scatter_size: int = 20, scatter_color: str = 'k', **kwargs) → Axes

Plots the 2D joint distribution of two parameters.

Parameters:

• posterior – DataFrame containing the parameter values

• parameter_x – Parameter to plot on x-axis

• parameter_y – Parameter to plot on y-axis

• ax – Matplotlib axes to plot on. Creates new figure if None

• xlabel – X-axis label. If None, uses parameter_x

• ylabel – Y-axis label. If None, uses parameter_y

• kind – Plot type (‘hist’, ‘kde’, or ‘scatter’)

• palette – Color palette for histogram/kde

• xlim – Tuple of (min, max) for x-axis limits

• ylim – Tuple of (min, max) for y-axis limits

• prior_x – Prior distribution object for x parameter

• prior_y – Prior distribution object for y parameter

• prior_range – Whether to set axis limits to prior ranges

• title – Plot title. If None, auto-generates

• fontsize – Base font size for labels and ticks

• cmap – Colormap for 2D histogram/kde

• show_grid – Whether to show grid lines

• levels – Number of contour levels for kde

• figsize – Figure size if creating new figure

• scatter – Whether to overlay scatter plot on kde

• scatter_alpha – Alpha value for scatter points

• scatter_size – Size of scatter points

• scatter_color – Color for scatter points

• **kwargs – Additional arguments passed to sns.histplot/kdeplot

Returns:

The matplotlib axes object

Return type:

plt.Axes

Raises:

• ValueError – If kind is not ‘hist’, ‘kde’, or ‘scatter’

• ValueError – If prior_range is True but priors are not provided

epydemix.visualization.plotting.plot_quantiles(df_quantiles: DataFrame, columns: List[str] | str, data: DataFrame | None = None, data_date_column: str = 'date', ax: Axes | None = None, lower_q: float = 0.05, upper_q: float = 0.95, show_median: bool = True, show_data: bool = False, ci_alpha: float = 0.3, title: str = '', ylabel: str = '', xlabel: str = '', show_legend: bool = True, legend_loc: str = 'upper left', palette: str = 'Dark2', colors: List[str] | str | None = None, labels: List[str] | str | None = None, y_scale: str = 'linear', show_grid: bool = True) → Axes

Plots quantiles for compartments over time with optional observed data.

Parameters:

• df_quantiles – DataFrame with columns: ‘date’, ‘quantile’, and data columns

• columns – Column name(s) to plot

• data – Optional DataFrame containing observed data

• data_date_column – Column name for date in data

• ax – Matplotlib axes to plot on

• lower_q – Lower quantile value (0.05 = 5th percentile)

• upper_q – Upper quantile value (0.95 = 95th percentile)

• show_median – Whether to show median line

• show_data – Whether to show observed data points

• ci_alpha – Alpha value for confidence interval shading

• title – Plot title

• ylabel – Y-axis label

• xlabel – X-axis label

• show_legend – Whether to show legend

• legend_loc – Legend location

• palette – Color palette name

• colors – Custom colors for lines

• labels – Custom labels for legend

• y_scale – Scale for y-axis (‘linear’ or ‘log’)

• show_grid – Whether to show grid lines

Returns:

The matplotlib axes object

Return type:

plt.Axes

epydemix.visualization.plotting.plot_selected_trajectories(calibration_results, ax=None, show_data=True, columns='data', lower_q=0.05, upper_q=0.95, show_median=True, ci_alpha=0.3, title='', show_legend=True, ylabel='', palette='Dark2')

TODO

epydemix.visualization.plotting.plot_spectral_radius(epimodel: Any, ax: Axes | None = None, title: str | None = None, color: str = 'k', show_perc: bool = False, layer: str = 'overall', show_interventions: bool = True, interventions_palette: str = 'Dark2', interventions_colors: List[str] | None = None, fontsize: int = 10, date_format: str = '%Y-%m-%d', ylabel: str | None = None, xlabel: str = 'Date', show_grid: bool = True, alpha: float = 0.2, legend_loc: str = 'upper left') → Axes

Plots the spectral radius of the contact matrices over time.

Parameters:

• epimodel – The EpiModel object containing contact matrices and interventions

• ax – Matplotlib axes to plot on. Creates new figure if None

• title – Plot title. If None, uses default title

• color – Color of the spectral radius line

• show_perc – Whether to show as percentage change with respect to the initial value

• layer – Contact matrix layer to analyze

• show_interventions – Whether to show intervention periods

• interventions_palette – Color palette for interventions

• interventions_colors – Custom colors for interventions

• fontsize – Base font size for labels and ticks

• date_format – Format string for date labels

• ylabel – Y-axis label. If None, auto-generated based on normalize/show_perc

• xlabel – X-axis label

• show_grid – Whether to show grid lines

• alpha – Transparency for intervention highlights

• legend_loc – Location of the legend

Returns:

The matplotlib axes object

Return type:

plt.Axes

Raises:

ValueError – If no contact matrices are defined or layer doesn’t exist

epydemix.visualization.plotting.plot_trajectories(stacked: Dict[str, ndarray], columns: List[str] | str, data: DataFrame | None = None, ax: Axes | None = None, show_data: bool = False, alpha: float = 0.1, title: str = '', ylabel: str = '', xlabel: str = '', show_legend: bool = True, legend_loc: str = 'upper left', palette: str = 'Dark2', colors: List[str] | str | None = None, labels: List[str] | str | None = None, y_scale: str = 'linear', show_grid: bool = True, dates: ndarray | None = None) → Axes

Plots individual trajectories over time with optional observed data.

Parameters:

• stacked – Dictionary mapping column names to arrays of shape (n_simulations, timesteps)

• columns – Column name(s) to plot

• data – Optional DataFrame containing observed data

• ax – Matplotlib axes to plot on

• show_data – Whether to show observed data points

• alpha – Alpha value for individual trajectories

• title – Plot title

• ylabel – Y-axis label

• xlabel – X-axis label

• show_legend – Whether to show legend

• legend_loc – Legend location

• palette – Color palette name

• colors – Custom colors for lines

• labels – Custom labels for legend

• y_scale – Scale for y-axis (‘linear’ or ‘log’)

• show_grid – Whether to show grid lines

• dates – Array of dates for x-axis. If None, uses range(timesteps)

Returns:

The matplotlib axes object

Return type:

plt.Axes

Module contents

epydemix.visualization.plot_contact_matrix(population: Any, layer: str, ax: Axes | None = None, cmap: str = 'YlOrRd', show_values: bool = False, title: str | None = None, show_colorbar: bool = True, fmt: str = '.1f', fontsize: int = 8, rotation: int = 45, figsize: Tuple[int, int] = (10, 8), vmin: float | None = None, vmax: float | None = None, origin: str = 'lower') → Axes

Plot a contact matrix heatmap.

Parameters:

• population – Population object containing contact matrices

• layer – Name of the contact layer to plot

• ax – Matplotlib axes to plot on. Creates new figure if None

• cmap – Colormap for the heatmap

• show_values – Whether to show numerical values in cells

• title – Plot title. If None, uses layer name

• colorbar – Whether to show the colorbar

• fmt – Format string for cell values

• fontsize – Font size for labels and values

• rotation – Rotation angle for x-axis labels

• figsize – Figure size if creating new figure

• vmin – Minimum value for colormap scaling

• vmax – Maximum value for colormap scaling

• origin – Whether to plot the matrix with the origin at the bottom left (default) or top left

Returns:

The matplotlib axes object

Return type:

plt.Axes

Raises:

KeyError – If specified layer doesn’t exist

epydemix.visualization.plot_distance_distribution(distances: ndarray | List[float] | Series, ax: Axes | None = None, kind: str = 'hist', color: str = 'dodgerblue', xlabel: str | None = None, ylabel: str | None = None, title: str | None = None, fontsize: int = 10, show_grid: bool = True, show_kde: bool = True, show_rug: bool = False, figsize: Tuple[int, int] = (10, 4), xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, stat: str = 'density', bins: int | str = 'auto', alpha: float = 0.4, vertical_lines: Dict[str, Dict[str, Any]] | None = None, **kwargs) → Axes

Plots the distribution of distances/errors from calibration.

Parameters:

• distances – Array-like object containing the distance/error values

• ax – Matplotlib axes to plot on. Creates new figure if None

• kind – Type of plot (‘hist’, ‘kde’, or ‘ecdf’)

• color – Color for the plot

• xlabel – X-axis label

• ylabel – Y-axis label

• title – Plot title

• fontsize – Base font size for labels and ticks

• show_grid – Whether to show grid lines

• show_kde – Whether to show KDE curve with histogram (only for kind=’hist’)

• show_rug – Whether to show rug plot

• figsize – Figure size if creating new figure

• xlim – Tuple of (min, max) for x-axis limits

• ylim – Tuple of (min, max) for y-axis limits

• stat – Statistic to plot for histogram (‘count’, ‘density’, ‘probability’)

• bins – Number of bins or method for histogram

• alpha – Transparency of the plot

• vertical_lines –

  Dict of vertical lines to add, format: {

  ’name’: {

  ‘x’: value, ‘color’: ‘color’, ‘linestyle’: ‘–‘, ‘label’: ‘label’

  }

  }

• **kwargs – Additional arguments passed to plotting functions

Returns:

The matplotlib axes object

Return type:

plt.Axes

Raises:

ValueError – If kind is not ‘hist’, ‘kde’, or ‘ecdf’

epydemix.visualization.plot_population(population: Any, ax: Axes | None = None, title: str | None = None, color: str = 'dodgerblue', show_perc: bool = False, fontsize: int = 10, rotation: int = 45, figsize: Tuple[int, int] = (10, 6), bar_width: float = 0.8, show_grid: bool = True, ylabel: str | None = None, xlabel: str = 'Demographic group', show_values: bool = True, fmt: str | None = None, value_fontsize: int | None = None) → Axes

Plot the population distribution across demographic groups.

Parameters:

• population – Population object containing demographic data

• ax – Matplotlib axes to plot on. Creates new figure if None

• title – Plot title. If None, uses default title

• color – Color for the bars

• show_perc – Whether to show population as percentages

• fontsize – Base font size for labels and ticks

• rotation – Rotation angle for x-axis labels

• figsize – Figure size if creating new figure

• bar_width – Width of the bars (between 0 and 1)

• show_grid – Whether to show grid lines

• ylabel – Y-axis label. If None, uses default based on show_perc

• xlabel – X-axis label

• show_values – Whether to show values above bars

• fmt – Format string for values. If None, uses “.1f%” for percentages and human-readable suffixes (K/M/B) for absolute numbers.

• value_fontsize – Font size for bar values. If None, uses fontsize

Returns:

The matplotlib axes object

Return type:

plt.Axes

epydemix.visualization.plot_posterior_distribution(posterior: DataFrame, parameter: str, ax: Axes | None = None, xlabel: str | None = None, ylabel: str | None = None, kind: str = 'hist', color: str = 'dodgerblue', xlim: Tuple[float, float] | None = None, prior: Any | None = None, prior_range: bool = False, title: str | None = None, fontsize: int = 10, show_grid: bool = True, show_kde: bool = True, show_rug: bool = False, figsize: Tuple[int, int] = (10, 4), stat: str = 'density', bins: int | str = 'auto', alpha: float = 0.4, vertical_lines: Dict[str, Dict[str, Any]] | None = None, **kwargs) → Axes

Plots the distribution of a parameter.

Parameters:

• posterior – DataFrame containing the parameter values

• parameter – The parameter to plot

• ax – Matplotlib axes to plot on. Creates new figure if None

• xlabel – X-axis label. If None, uses parameter name

• ylabel – Y-axis label

• kind – Type of plot (‘hist’, ‘kde’, or ‘ecdf’)

• color – Color for the plot

• xlim – Tuple of (min, max) for x-axis limits

• prior – Prior distribution object with ppf method

• prior_range – Whether to set x-axis limits to prior range

• title – Plot title. If None, auto-generates

• fontsize – Base font size for labels and ticks

• show_grid – Whether to show grid lines

• show_kde – Whether to show KDE curve with histogram (only for kind=’hist’)

• show_rug – Whether to show rug plot

• figsize – Figure size if creating new figure

• stat – Statistic to plot (‘count’, ‘density’, ‘probability’)

• bins – Number of bins or method for histogram

• alpha – Transparency of the plot

• vertical_lines –

  Dict of vertical lines to add, format: {

  ’name’: {

  ‘x’: value, ‘color’: ‘color’, ‘linestyle’: ‘–‘, ‘label’: ‘label’

  }

  }

• **kwargs – Additional arguments passed to plotting functions

Returns:

The matplotlib axes object

Return type:

plt.Axes

Raises:

• ValueError – If kind is not ‘hist’, ‘kde’, or ‘ecdf’

• ValueError – If prior_range is True but no prior is provided

epydemix.visualization.plot_posterior_distribution_2d(posterior: DataFrame, parameter_x: str, parameter_y: str, ax: Axes | None = None, xlabel: str | None = None, ylabel: str | None = None, kind: str = 'hist', palette: str = 'Blues', xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, prior_x: Any | None = None, prior_y: Any | None = None, prior_range: bool = False, title: str | None = None, fontsize: int = 10, cmap: str | None = None, show_grid: bool = True, levels: int = 10, figsize: Tuple[int, int] = (6, 6), scatter: bool = False, scatter_alpha: float = 0.5, scatter_size: int = 20, scatter_color: str = 'k', **kwargs) → Axes

Plots the 2D joint distribution of two parameters.

Parameters:

• posterior – DataFrame containing the parameter values

• parameter_x – Parameter to plot on x-axis

• parameter_y – Parameter to plot on y-axis

• ax – Matplotlib axes to plot on. Creates new figure if None

• xlabel – X-axis label. If None, uses parameter_x

• ylabel – Y-axis label. If None, uses parameter_y

• kind – Plot type (‘hist’, ‘kde’, or ‘scatter’)

• palette – Color palette for histogram/kde

• xlim – Tuple of (min, max) for x-axis limits

• ylim – Tuple of (min, max) for y-axis limits

• prior_x – Prior distribution object for x parameter

• prior_y – Prior distribution object for y parameter

• prior_range – Whether to set axis limits to prior ranges

• title – Plot title. If None, auto-generates

• fontsize – Base font size for labels and ticks

• cmap – Colormap for 2D histogram/kde

• show_grid – Whether to show grid lines

• levels – Number of contour levels for kde

• figsize – Figure size if creating new figure

• scatter – Whether to overlay scatter plot on kde

• scatter_alpha – Alpha value for scatter points

• scatter_size – Size of scatter points

• scatter_color – Color for scatter points

• **kwargs – Additional arguments passed to sns.histplot/kdeplot

Returns:

The matplotlib axes object

Return type:

plt.Axes

Raises:

• ValueError – If kind is not ‘hist’, ‘kde’, or ‘scatter’

• ValueError – If prior_range is True but priors are not provided

epydemix.visualization.plot_quantiles(df_quantiles: DataFrame, columns: List[str] | str, data: DataFrame | None = None, data_date_column: str = 'date', ax: Axes | None = None, lower_q: float = 0.05, upper_q: float = 0.95, show_median: bool = True, show_data: bool = False, ci_alpha: float = 0.3, title: str = '', ylabel: str = '', xlabel: str = '', show_legend: bool = True, legend_loc: str = 'upper left', palette: str = 'Dark2', colors: List[str] | str | None = None, labels: List[str] | str | None = None, y_scale: str = 'linear', show_grid: bool = True) → Axes

Plots quantiles for compartments over time with optional observed data.

Parameters:

• df_quantiles – DataFrame with columns: ‘date’, ‘quantile’, and data columns

• columns – Column name(s) to plot

• data – Optional DataFrame containing observed data

• data_date_column – Column name for date in data

• ax – Matplotlib axes to plot on

• lower_q – Lower quantile value (0.05 = 5th percentile)

• upper_q – Upper quantile value (0.95 = 95th percentile)

• show_median – Whether to show median line

• show_data – Whether to show observed data points

• ci_alpha – Alpha value for confidence interval shading

• title – Plot title

• ylabel – Y-axis label

• xlabel – X-axis label

• show_legend – Whether to show legend

• legend_loc – Legend location

• palette – Color palette name

• colors – Custom colors for lines

• labels – Custom labels for legend

• y_scale – Scale for y-axis (‘linear’ or ‘log’)

• show_grid – Whether to show grid lines

Returns:

The matplotlib axes object

Return type:

plt.Axes

epydemix.visualization.plot_spectral_radius(epimodel: Any, ax: Axes | None = None, title: str | None = None, color: str = 'k', show_perc: bool = False, layer: str = 'overall', show_interventions: bool = True, interventions_palette: str = 'Dark2', interventions_colors: List[str] | None = None, fontsize: int = 10, date_format: str = '%Y-%m-%d', ylabel: str | None = None, xlabel: str = 'Date', show_grid: bool = True, alpha: float = 0.2, legend_loc: str = 'upper left') → Axes

Plots the spectral radius of the contact matrices over time.

Parameters:

• epimodel – The EpiModel object containing contact matrices and interventions

• ax – Matplotlib axes to plot on. Creates new figure if None

• title – Plot title. If None, uses default title

• color – Color of the spectral radius line

• show_perc – Whether to show as percentage change with respect to the initial value

• layer – Contact matrix layer to analyze

• show_interventions – Whether to show intervention periods

• interventions_palette – Color palette for interventions

• interventions_colors – Custom colors for interventions

• fontsize – Base font size for labels and ticks

• date_format – Format string for date labels

• ylabel – Y-axis label. If None, auto-generated based on normalize/show_perc

• xlabel – X-axis label

• show_grid – Whether to show grid lines

• alpha – Transparency for intervention highlights

• legend_loc – Location of the legend

Returns:

The matplotlib axes object

Return type:

plt.Axes

Raises:

ValueError – If no contact matrices are defined or layer doesn’t exist

epydemix.visualization.plot_trajectories(stacked: Dict[str, ndarray], columns: List[str] | str, data: DataFrame | None = None, ax: Axes | None = None, show_data: bool = False, alpha: float = 0.1, title: str = '', ylabel: str = '', xlabel: str = '', show_legend: bool = True, legend_loc: str = 'upper left', palette: str = 'Dark2', colors: List[str] | str | None = None, labels: List[str] | str | None = None, y_scale: str = 'linear', show_grid: bool = True, dates: ndarray | None = None) → Axes

Plots individual trajectories over time with optional observed data.

Parameters:

• stacked – Dictionary mapping column names to arrays of shape (n_simulations, timesteps)

• columns – Column name(s) to plot

• data – Optional DataFrame containing observed data

• ax – Matplotlib axes to plot on

• show_data – Whether to show observed data points

• alpha – Alpha value for individual trajectories

• title – Plot title

• ylabel – Y-axis label

• xlabel – X-axis label

• show_legend – Whether to show legend

• legend_loc – Legend location

• palette – Color palette name

• colors – Custom colors for lines

• labels – Custom labels for legend

• y_scale – Scale for y-axis (‘linear’ or ‘log’)

• show_grid – Whether to show grid lines

• dates – Array of dates for x-axis. If None, uses range(timesteps)

Returns:

The matplotlib axes object

Return type:

plt.Axes