marmot.plottingmodules.plotutils.plot_library.SetupSubplot#

class SetupSubplot(nrows: int = 1, ncols: int = 1, figsize: Tuple[int, int] = (6, 4), sharey: bool = False, squeeze: bool = True, ravel_axs: bool = False, **kwargs)[source]#

Bases: object

Sets up the main figure and subplots for use in Marmot and expands the functionality of matplotlib by adding further methods to quickly build plots.

Defines the dimensions (nrows, ncols) of a figure and its subplots. Builds on top of matplotlib.pyplot.subplots and preserves all functionality of that function.

All arguments are optional and by default calling SetupSubplot() or PlotLibrary() which inherits SetupSubplot, will create a 1x1 figure with a figsize defined in the config.yml file. The following are some common values to pass when creating various plots.

  • 1x1 figure: SetupSubplot()

  • 1xN figure: SetupSubplot(nrows=1, ncols=N, sharey=True)

  • MxN figure: SetupSubplot(nrows=M, ncols=N, sharey=True, squeeze=False, ravel_axs=True)

Plotting defaults are also set in this class, which are defined in the config.yml file.

Parameters

  • nrows (int, optional) – Number of rows of the subplot grid. Defaults to 1.

  • ncols (int, optional) – Number of columns of the subplot grid. Defaults to 1.

  • figsize (Tuple[int, int], optional) – The x,y dimension of each subplot. Defaults set in config.yml

  • sharey (bool, optional) – share the y-axis across all subplots. Defaults to False.

  • squeeze (bool, optional) – If True, extra dimensions are squeezed out from the returned axs objects if 1x1 figure or 1xN figure. Defaults to True.

  • ravel_axs (bool, optional) – If True the returned axs object is a 1D numpy object array of Axes objects. This can be used to convert MxN figure axs objects to 1D. Defaults to False.

  • **kwargs – These parameters will be passed to matplotlib.pyplot.subplots function.

Methods

add_barplot_load_lines_and_use(load_and_use_df)

Adds load lines to barplots and unserved energy if present.

add_facet_labels([xlabels_bottom, xlabels, ...])

Adds labels to outside of facet plot.

add_legend([handles, labels, loc, ncol, ...])

Adds a legend to the desired location on the figure.

add_main_title(label, **kwargs)

Adds a title centered above the main figure

add_property_annotation(df, prop[, sub_pos, ...])

Adds a property annotation to the subplot.

get_figure()

Returns the matplotlib figure and Axes objects.

remove_excess_axs(excess_axs, grid_size)

Removes excess axes spins and tick marks.

set_barplot_xticklabels(labels[, rotate, ...])

Set the xticklabels on bar plots and determine whether they will be rotated.

set_subplot_timeseries_format([minticks, ...])

Auto sets timeseries format of subplot.

set_yaxis_major_tick_format([tick_format, ...])

Sets the y axis major tick format of numbers.
get_figure() → Tuple[matplotlib.figure.Figure, Union[matplotlib.axes._axes.Axes, List[matplotlib.axes._axes.Axes]]][source]#

Returns the matplotlib figure and Axes objects.

axes can be either a single Axes object or an array of Axes objects depending on the figure dimensions defined.

Returns

matplotlib figure and axes objects

Return type

Tuple[Figure, Union[Axes, List[Axes]]]

add_legend(handles=None, labels: Optional[List[str]] = None, loc='lower right', ncol=1, reverse_legend: bool = False, sort_by: Optional[list] = None, bbox_to_anchor=None, **kwargs) → None[source]#

Adds a legend to the desired location on the figure.

Wrapper around matplotlib.axes.Axes.legend

The location and number of columns to create can be set through the config.yml file. The available default options are:

  • ‘lower right’

  • ‘center right’

  • ‘upper right’

  • ‘upper center’

  • ‘lower center’

  • ‘lower left’

  • ‘center left’

  • ‘upper left’

The default options will place the legend outside the main figure subplots to avoid any overlaps of elements. Custom placement is still possible through the loc and bbox_to_anchor arguments but is not advised as this will hard code the placement.

Passing handles and labels is not required as these are obtained from the axs objects. Any duplicate label and their handle will be removed.

Sorting of legend is advised when plotting multiple subplots as original order cannot be guaranteed. This can be done by passing a list to the sort_by argument, values will then be sorted by the order they appear in the list.

Parameters

  • handles (Artists sequence, optional) – A list of Artists (lines, patches) to be added to the legend. Use this together with labels, if you need full control on what is shown in the legend and the automatic mechanism described above is not sufficient. The length of handles and labels should be the same in this case. If they are not, they are truncated to the smaller length. Defaults to None.

  • labels (List[str], optional) – A list of labels to show next to the artists. Use this together with handles, if you need full control on what is shown in the legend and the automatic mechanism described above is not sufficient. Defaults to None.

  • loc (str or pair of floats, optional) – The location of the legend. Defaults set in config.yml.

  • ncol (int, optional) – The number of columns that the legend has. Defaults set in config.yml.

  • reverse_legend (bool, optional) – Revereses the legend order. Defaults to False.

  • sort_by (list, optional) – A list to sort the legend by, list can contain more or less entries than the legend, entries with no matches are not sorted and added to end of legend. Defaults to None.

  • bbox_to_anchor (2-tuple, or 4-tuple of floats, optional) – Box that is used to position the legend in conjunction with loc. This argument allows arbitrary placement of the legend. Defaults to None.

  • **kwargs – These parameters will be passed to matplotlib.axes.Axes.legend function.

add_property_annotation(df: pandas.core.frame.DataFrame, prop: str, sub_pos: Union[int, Tuple[int, int]] = 0, curtailment_name: str = 'Curtailment', energy_unit: str = 'MW', re_gen_cat: Optional[list] = None, gen_cols: Optional[list] = None) → pandas._libs.tslibs.timestamps.Timestamp[source]#

Adds a property annotation to the subplot.

New in version 0.10.0.

The current supported properties are:

  • Peak Demand

  • Min Net Load

  • Peak RE

  • Peak Unserved Energy

  • Peak Curtailment

Based on the property selected this method will locate the timestamp and corresponding value of the property. The value and an arrow pointing to the location of the property will be annotated.

Parameters

  • df (pd.DataFrame) – Dataframe with datetime index

  • prop (str) – property

  • sub_pos (Union[int, Tuple[int, int]], optional) – Position of subplot, can be either a integer or a tuple of 2 integers depending on how SetupSubplot was instantiated. Defaults to 0

  • curtailment_name (str, optional) – Name of curtailment column. Defaults to ‘Curtailment’.

  • energy_unit (str, optional) – units to add to prop annotation. Defaults to ‘MW’.

  • re_gen_cat (list, optional) – list of re techs, needed to for ‘Peak RE’ property. Defaults to None.

  • gen_cols (list, optional) – list of gen columns, needed for ‘Peak RE’ and ‘Peak Curtailmnet’ property. Defaults to None.

Returns

timstamp of property

Return type

pd.Timestamp

add_main_title(label: str, **kwargs) → None[source]#

Adds a title centered above the main figure

Wrapper around matplotlib.axes.Axes.set_title

Parameters

  • label (str) – Title of figure.

  • **kwargs – These parameters will be passed to matplotlib.axes.Axes.set_title function.

set_yaxis_major_tick_format(tick_format: str = 'standard', decimal_accuracy: int = 1, sub_pos: Union[int, Tuple[int, int]] = 0) → None[source]#

Sets the y axis major tick format of numbers.

The decimal point accuracy of the numbers can be further adjusted using the config file “y_axes_decimalpt” input.

Parameters

  • tick_format (str, optional) –

    Format options. Opinions available are:

    • standard (1000 values seperated by ‘,’)

    • percent (Adds % symbal to axis values)

    • log

    Defaults to ‘standard’.

  • decimal_accuracy (int, optional) – Number of decimal points to use. Default set in config file.

  • sub_pos (Union[int, Tuple[int, int]], optional) – Position of subplot, can be either a integer or a tuple of 2 integers depending on how SetupSubplot was instantiated. Defaults to 0

set_subplot_timeseries_format(minticks: int = 4, maxticks: int = 8, sub_pos: Union[int, Tuple[int, int]] = 0, zero_formats_1: str = '%b\n %Y', zero_formats_2: str = '%d\n %b', zero_formats_3: str = '%H:%M\n %d-%b') → None[source]#

Auto sets timeseries format of subplot.

Parameters

  • minticks (int, optional) – Minimum tick marks. Defaults to mconfig.parser(“axes_options”,”x_axes_minticks”).

  • maxticks (int, optional) – Max tick marks. Defaults to mconfig.parser(“axes_options”,”x_axes_maxticks”).

  • sub_pos (Union[int, Tuple[int, int]], optional) – Position of subplot, can be either a integer or a tuple of 2 integers depending on how SetupSubplot was instantiated. Defaults to 0.

  • zero_formats_1 (str, optional) – Sets the zero_fromats[1] format. Defaults to ‘%bn %Y’.

  • zero_formats_2 (str, optional) – Sets the zero_formats[2] format. Defaults to ‘%dn %b’.

  • zero_formats_3 (str, optional) – Sets the zero_formats[3] format. Defaults to ‘%H:%Mn %d-%b’.

remove_excess_axs(excess_axs: int, grid_size: int) → None[source]#

Removes excess axes spins and tick marks.

Parameters

  • excess_axs (int) – # of excess axes.

  • grid_size (int) – Size of facet grid.

set_barplot_xticklabels(labels: list, rotate: bool = True, num_labels: int = 7, angle: float = 45, sub_pos: Union[int, Tuple[int, int]] = 0, **kwargs) → None[source]#

Set the xticklabels on bar plots and determine whether they will be rotated.

Wrapper around matplotlib.axes.Axes.set_xticklabels

Checks to see if the number of labels is greater than or equal to the default number set in config.yml. If this is the case, rotate specify whether or not to rotate the labels and angle specifies what angle they should be rotated to.

Parameters

  • labels (list) – Labels to apply to xticks

  • rotate (bool, optional) – rotate labels True/False. Defaults to mconfig.parser(“axes_label_options”, “rotate_x_labels”).

  • num_labels (int, optional) – Number of labels to rotate at. Defaults to mconfig.parser(“axes_label_options”, “rotate_at_num_labels”).

  • angle (float, optional) – Angle of rotation. Defaults to mconfig.parser(“axes_label_options”, “rotation_angle”).

  • sub_pos (Union[int, Tuple[int, int]], optional) – Position of subplot, can be either a integer or a tuple of 2 integers depending on how SetupSubplot was instantiated. Defaults to 0.

  • **kwargs – These parameters will be passed to matplotlib.axes.Axes.set_xticklabels function.

add_facet_labels(xlabels_bottom: bool = True, xlabels: Optional[list] = None, ylabels: Optional[list] = None, **kwargs) → None[source]#

Adds labels to outside of facet plot.

Parameters

  • xlabels_bottom (bool, optional) – If True labels are placed under bottom axis. Defaults to True.

  • xlabels (list, optional) – list of xlabels. Defaults to None.

  • ylabels (list, optional) – list of ylabels. Defaults to None.

  • **kwargs – These parameters will be passed to matplotlib.axes.Axes.set_xlabel and matplotlib.axes.Axes.set_ylabel functions.

add_barplot_load_lines_and_use(load_and_use_df: pandas.core.frame.DataFrame, include_charging_line: bool = True, load_legend_names: dict = {'demand': 'Demand', 'load': 'Demand +\nStorage Charging'}, sub_pos: Union[int, Tuple[int, int]] = 0, **kwargs) → None[source]#

Adds load lines to barplots and unserved energy if present.

Parameters

  • load_and_use_df (pd.DataFrame) – Dataframe containing load line data

  • include_charging_line (bool, optional) – Add storage charging line True/False. Defaults to mconfig.parser(“plot_data”, “include_barplot_load_storage_charging_line”).

  • load_legend_names (dict, optional) – Dictionary of load legend names. Must have keys ‘load’ and ‘demand’. Defaults to mconfig.parser(“load_legend_names”).

  • sub_pos (Union[int, Tuple[int, int]], optional) – Position of subplot, can be either a integer or a tuple of 2 integers depending on how SetupSubplot was instantiated. Defaults to 0.

Raises

KeyError – Raised if either ‘Total Load’ or ‘Total Demand’ are missing in from the load_and_use_df