out_plot.PlotRenderer.line

tools.out_plot.PlotRenderer.line(
    geo,
    time,
    quantity,
    *,
    label_format='{n}: {q}',
    legend='auto',
    line_kwargs=None,
    ordering='location',
    time_format='auto',
    title=None,
    transform=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 = “{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: (auto, on, off, outside) = “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

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: (location, quantity) = “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: (auto, date, day) = “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

a title to draw on the plot

transform: Callable[[pd.DataFrame], pd.DataFrame] = 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