plotting

this module provides functions for generating some basic figures. The code can be used as is, or serve as an example for writing your own code.

ema_workbench.analysis.plotting.envelopes(experiments, outcomes, outcomes_to_show=None, group_by=None, grouping_specifiers=None, density=None, fill=False, legend=True, titles={}, ylabels={}, log=False)

Make envelop plots.

An envelope shows over time the minimum and maximum value for a set of runs over time. It is thus to be used in case of time series data. The function will try to find a result labeled “TIME”. If this is present, these values will be used on the X-axis. In case of Vensim models, TIME is present by default.

Parameters:

  • experiments (DataFrame)

  • outcomes (OutcomesDict)

  • outcomes_to_show

  • str (list of)

  • str

  • optional

  • group_by (str, optional) – name of the column in the experimentsto group results by. Alternatively, index can be used to use indexing arrays as the basis for grouping.

  • grouping_specifiers (iterable or dict, optional) – set of categories to be used as a basis for grouping by. Grouping_specifiers is only meaningful if group_by is provided as well. In case of grouping by index, the grouping specifiers should be in a dictionary where the key denotes the name of the group.

  • density ({None, HIST, KDE, VIOLIN, BOXPLOT}, optional)

  • fill (bool, optional)

  • legend (bool, optional)

  • titles (dict, optional) – a way for controlling whether each of the axes should have a title. There are three possibilities. If set to None, no title will be shown for any of the axes. If set to an empty dict, the default, the title is identical to the name of the outcome of interest. If you want to override these default names, provide a dict with the outcome of interest as key and the desired title as value. This dict need only contain the outcomes for which you want to use a different title.

  • ylabels (dict, optional) – way for controlling the ylabels. Works identical to titles.

  • log (bool, optional) – log scale density plot

Returns:

  • Figure (Figure instance)

  • axes (dict) – dict with outcome as key, and axes as value. Density axes’ are indexed by the outcome followed by _density.

Note

the current implementation is limited to seven different categories in case of group_by, categories, and/or discretesize. This limit is due to the colors specified in COLOR_LIST.

Examples

>>> import util as util
>>> data = util.load_results(r'1000 flu cases.cPickle')
>>> envelopes(data, group_by='policy')

will show an envelope for three three different policies, for all the outcomes of interest. while

>>> envelopes(data, group_by='policy', categories=['static policy',
              'adaptive policy'])

will only show results for the two specified policies, ignoring any results associated with ‘no policy’.

ema_workbench.analysis.plotting.kde_over_time(experiments, outcomes, outcomes_to_show=None, group_by=None, grouping_specifiers=None, colormap='viridis', log=True)

Plot a KDE over time. The KDE is is visualized through a heatmap

Parameters:

  • experiments (DataFrame)

  • outcomes (OutcomesDict)

  • outcomes_to_show (list of str, optional) – list of outcome of interest you want to plot. If empty, all outcomes are plotted. Note: just names.

  • group_by (str, optional) – name of the column in the cases array to group results by. Alternatively, index can be used to use indexing arrays as the basis for grouping.

  • grouping_specifiers (iterable or dict, optional) – set of categories to be used as a basis for grouping by. Grouping_specifiers is only meaningful if group_by is provided as well. In case of grouping by index, the grouping specifiers should be in a dictionary where the key denotes the name of the group.

  • colormap (str, optional) – valid matplotlib color map name

  • log (bool, optional)

Returns:

  • list of Figure instances – a figure instance for each group for each outcome

  • dict – dict with outcome as key, and axes as value. Density axes’ are indexed by the outcome followed by _density

ema_workbench.analysis.plotting.lines(experiments, outcomes, outcomes_to_show=[], group_by=None, grouping_specifiers=None, density='', legend=True, titles={}, ylabels={}, experiments_to_show=None, show_envelope=False, log=False)

This function takes the results from perform_experiments() and visualizes these as line plots. It is thus to be used in case of time series data. The function will try to find a result labeled “TIME”. If this is present, these values will be used on the X-axis. In case of Vensim models, TIME is present by default.

Parameters:

  • experiments (DataFrame)

  • outcomes (OutcomesDict)

  • outcomes_to_show (list of str, optional) – list of outcome of interest you want to plot. If empty, all outcomes are plotted. Note: just names.

  • group_by (str, optional) – name of the column in the cases array to group results by. Alternatively, index can be used to use indexing arrays as the basis for grouping.

  • grouping_specifiers (iterable or dict, optional) – set of categories to be used as a basis for grouping by. Grouping_specifiers is only meaningful if group_by is provided as well. In case of grouping by index, the grouping specifiers should be in a dictionary where the key denotes the name of the group.

  • density ({None, HIST, KDE, VIOLIN, BOXPLOT}, optional)

  • legend (bool, optional)

  • titles (dict, optional) – a way for controlling whether each of the axes should have a title. There are three possibilities. If set to None, no title will be shown for any of the axes. If set to an empty dict, the default, the title is identical to the name of the outcome of interest. If you want to override these default names, provide a dict with the outcome of interest as key and the desired title as value. This dict need only contain the outcomes for which you want to use a different title.

  • ylabels (dict, optional) – way for controlling the ylabels. Works identical to titles.

  • experiments_to_show (ndarray, optional) – indices of experiments to show lines for, defaults to None.

  • show_envelope (bool, optional) – show envelope of outcomes. This envelope is the based on the minimum at each column and the maximum at each column.

  • log (bool, optional) – log scale density plot

Returns:

  • fig (Figure instance)

  • axes (dict) – dict with outcome as key, and axes as value. Density axes’ are indexed by the outcome followed by _density.

Note

the current implementation is limited to seven different categories in case of group_by, categories, and/or discretesize. This limit is due to the colors specified in COLOR_LIST.

ema_workbench.analysis.plotting.multiple_densities(experiments, outcomes, points_in_time=None, outcomes_to_show=None, group_by=None, grouping_specifiers=None, density=Density.KDE, legend=True, titles={}, ylabels={}, experiments_to_show=None, plot_type=PlotType.ENVELOPE, log=False, **kwargs)

Make an envelope plot with multiple density plots over the run time

Parameters:

  • experiments (DataFrame)

  • outcomes (OutcomesDict)

  • points_in_time (list) – a list of points in time for which you want to see the density. At the moment up to 6 points in time are supported

  • outcomes_to_show (list of str, optional) – list of outcome of interest you want to plot. If empty, all outcomes are plotted. Note: just names.

  • group_by (str, optional) – name of the column in the cases array to group results by. Alternatively, index can be used to use indexing arrays as the basis for grouping.

  • grouping_specifiers (iterable or dict, optional) – set of categories to be used as a basis for grouping by. Grouping_specifiers is only meaningful if group_by is provided as well. In case of grouping by index, the grouping specifiers should be in a dictionary where the key denotes the name of the group.

  • density ({Density.KDE, Density.HIST, Density.VIOLIN, Density.BOXPLOT},) – optional

  • legend (bool, optional)

  • titles (dict, optional) – a way for controlling whether each of the axes should have a title. There are three possibilities. If set to None, no title will be shown for any of the axes. If set to an empty dict, the default, the title is identical to the name of the outcome of interest. If you want to override these default names, provide a dict with the outcome of interest as key and the desired title as value. This dict need only contain the outcomes for which you want to use a different title.

  • ylabels (dict, optional) – way for controlling the ylabels. Works identical to titles.

  • experiments_to_show (ndarray, optional) – indices of experiments to show lines for, defaults to None.

  • plot_type ({PlotType.ENVELOPE, PlotType.ENV_LIN, PlotType.LINES}, optional)

  • log (bool, optional)

Returns:

  • fig (Figure instance)

  • axes (dict) – dict with outcome as key, and axes as value. Density axes’ are indexed by the outcome followed by _density.

Note

the current implementation is limited to seven different categories in case of group_by, categories, and/or discretesize. This limit is due to the colors specified in COLOR_LIST.

Note

the connection patches are for some reason not drawn if log scaling is used for the density plots. This appears to be an issue in matplotlib itself.