Skip to content

epymorph.tools.out_plot

Tools for rendering graphs from epymorph simulation output data.

OrderingOption module-attribute 

OrderingOption = Literal['location', 'quantity']

Options for plot line ordering.

TimeFormatOption module-attribute 

TimeFormatOption = Literal['auto', 'date', 'day']

Options for the plot's time-axis format.

LegendOption module-attribute 

LegendOption = Literal['on', 'off', 'outside', 'auto']

Options for the plot's legend display.

PlotRenderer 

PlotRenderer(output: Output)

Provides methods for rendering an output in plot form.

Most commonly, you will use PlotRenderer starting from a simulation output object that supports it:

1
2
3
4
5
6
7
out = BasicSimulation(rume).run()
out.plot.line(...)

Parameters
----------
output :
    The output the renderer will use.

output instance-attribute 

output: Output = output

The output the renderer will use.

line 

line(
    geo: GeoSelection | GeoAggregation,
    time: TimeSelection | TimeAggregation,
    quantity: QuantitySelection | QuantityAggregation,
    *,
    label_format: str = "{n}: {q}",
    legend: LegendOption = "auto",
    line_kwargs: list[dict] | None = None,
    ordering: OrderingOption = "location",
    time_format: TimeFormatOption = "auto",
    title: str | None = None,
    transform: Callable[[DataFrame], DataFrame]
    | None = None,
) -> None

Renders a line plot using matplotlib showing the given selections.

The plot will be immediately rendered by this function by calling plt.show(). This is intended as a quick plotting method to cover most casual use-cases. If you want more control over how the plot is drawn, see method line_plt().

Parameters:

  • geo (GeoSelection | GeoAggregation) –

    The geographic selection to make on the output data.

  • time (TimeSelection | TimeAggregation) –

    The time selection to make on the output data.

  • quantity (QuantitySelection | QuantityAggregation) –

    The quantity selection to make on the output data.

  • label_format (str, default: '{n}: {q}' ) –

    A format for the items displayed in the legend; the string will be used in a call to format() with the replacement variables {n} for the name of the geo node and {q} for the name of the quantity.

  • legend (LegendOption, default: 'auto' ) –

    Whether and how to draw the plot legend.

    • "auto" will draw the legend unless it would be too large
    • "on" forces the legend to be drawn
    • "off" forces the legend to not be drawn
    • "outside" forces the legend to be drawn next to the plot area (instead of inside it)
  • line_kwargs (list[dict] | None, default: None ) –

    A list of keyword arguments to be passed to the matplotlib function that draws each line. If the list contains less items than there are lines, we will cycle through the list as many times as needed. Lines are drawn in the order defined by the ordering parameter. See matplotlib documentation for the supported options.

  • ordering (OrderingOption, default: 'location' ) –

    Controls the order in which lines will be drawn; both location and quantity are used to sort the resulting rows, this just decides which gets priority.

  • time_format (TimeFormatOption, default: 'auto' ) –

    Controls the formatting of the time axis (the horizontal axis); "auto" will use the format defined by the grouping of the time parameter, "date" attempts to display calendar dates, "day" attempts to display days numerically indexed from the start of the simulation with the first day being 0. If the system cannot convert to the requested time format, this argument may be ignored.

  • title (str | None, default: None ) –

    A title to draw on the plot.

  • transform (Callable[[DataFrame], DataFrame] | None, default: None ) –

    Allows you to specify an arbitrary transform function for the source dataframe before we plot it, e.g., to rescale the values. The function will be called once per geo/quantity group -- once per line, essentially -- with a dataframe that contains just the data for that group. The dataframe given as the argument is the result of applying all selections and the projection if specified. You should return a dataframe with the same format, where the values of the data column have been modified for your purposes.

    Dataframe columns:

    • "time": the time series column
    • "geo": the node ID (same value per group)
    • "quantity": the label of the quantity (same value per group)
    • "value": the data column

line_plt 

line_plt(
    ax: Axes,
    geo: GeoSelection | GeoAggregation,
    time: TimeSelection | TimeAggregation,
    quantity: QuantitySelection | QuantityAggregation,
    *,
    label_format: str = "{n}: {q}",
    line_kwargs: list[dict] | None = None,
    ordering: OrderingOption = "location",
    time_format: TimeFormatOption = "auto",
    transform: Callable[[DataFrame], DataFrame]
    | None = None,
) -> list[Line2D]

Draws lines onto the given matplotlib Axes to show the given selections. This is a variant of the method line() that gives you more control over the rendering of a plot by letting you do most of the work with matplotlib's API.

Parameters:

  • ax (Axes) –

    The plot axes on which to draw lines.

  • geo (GeoSelection | GeoAggregation) –

    The geographic selection to make on the output data.

  • time (TimeSelection | TimeAggregation) –

    The time selection to make on the output data.

  • quantity (QuantitySelection | QuantityAggregation) –

    The quantity selection to make on the output data.

  • label_format (str, default: '{n}: {q}' ) –

    A format for the items displayed in the legend; the string will be used in a call to format() with the replacement variables {n} for the name of the geo node and {q} for the name of the quantity.

  • line_kwargs (list[dict] | None, default: None ) –

    A list of keyword arguments to be passed to the matplotlib function that draws each line. If the list contains less items than there are lines, we will cycle through the list as many times as needed. Lines are drawn in the order defined by the ordering parameter. See matplotlib documentation for the supported options.

  • ordering (OrderingOption, default: 'location' ) –

    Controls the order in which lines will be drawn; both location and quantity are used to sort the resulting rows, this just decides which gets priority.

  • time_format (TimeFormatOption, default: 'auto' ) –

    Controls the formatting of the time axis (the horizontal axis); "auto" will use the format defined by the grouping of the time parameter, "date" attempts to display calendar dates, "day" attempts to display days numerically indexed from the start of the simulation with the first day being 0. If the system cannot convert to the requested time format, this argument may be ignored.

  • transform (Callable[[DataFrame], DataFrame] | None, default: None ) –

    Allows you to specify an arbitrary transform function for the source dataframe before we plot it, e.g., to rescale the values. The function will be called once per geo/quantity group -- one per line, essentially -- with a dataframe that contains just the data for that group. The dataframe given as the argument is the result of applying all selections and the projection if specified. You should return a dataframe with the same format, where the values of the data column have been modified for your purposes.

    Dataframe columns:

    • "time": the time series column
    • "geo": the node ID (same value per group)
    • "quantity": the label of the quantity (same value per group)
    • "value": the data column

Returns:

  • list[Line2D] –

    The Line2D object for each line drawn; you can use this to have finer control over the presentation of the lines.

PlotRendererMixin

Bases: Output

Mixin class that adds a convenient method for rendering plots from an output.

plot property 

plot: PlotRenderer

Render a plot from this output.