Plotting library¶

The plotting API(s)¶

There are three ways to use the pyam plotting library.

Using the plot feature as an attribute of the IamDataFrame:
```
IamDataFrame.plot.<kind>(**kwargs)
```
Using the plot feature as a function with a kind keyword argument:
```
IamDataFrame.plot(kind='<kind>', **kwargs)
```
This function defaults to the pyam.plotting.line() type.
Calling any function of either the plotting or the figures module directly via
```
pyam.<module>.<kind>(df, **kwargs)
```
where df is either an IamDataFrame or a suitable pandas.DataFrame.

Check out the Plotting Gallery for examples!

The RunControl configuration¶

The pyam plotting library provides a thin RunControl wrapper around a Python dictionary for plotting-style defaults, like setting colors or linestyles for certain model or scenario names.

pyam.run_control()[source]¶: Global run control for user-defined plotting style defaults

Input can be provided as nested dictionaries of the structure type > dimension > name > value, e.g.,

pyam.run_control().update(
    {'color': {'scenario': {'test_scenario': 'black'}}}
)

or as the path to a yaml file with a similar structure:

pyam.run_control().update(<file.yaml>)

See this example from the AR6 WG1 using pyam plotting via a yaml file.

The IamDataFrame.categorize() function also appends any style arguments to the RunControl.

Plotting functions¶

pyam.plotting.line(df, x=None, y='value', order=None, legend=None, title=True, color=None, marker=None, linestyle=None, fill_between=None, final_ranges=None, rm_legend_label=[], ax=None, cmap=None, **kwargs)[source]¶

Plot data as lines with or without markers.

Parameters:

dfpyam.IamDataFrame, pandas.DataFrame: Data to be plotted
xstring, optional: The coordinates or column of the data points for the horizontal axis; defaults to the time domain (if df is IamDataFrame) or ‘year’.
ystring, optional: The column to use as y-axis
orderdict or list, optional: The order of lines and the legend as {<column>: [<order>]} or a list of columns where ordering should be applied. If not specified, order by run_control()['order'][<column>] (where available) or alphabetical.
legendbool or dictionary, optional: Include a legend. By default, show legend only if less than 13 entries. If a dictionary is provided, it will be used as keyword arguments in creating the legend.
titlebool or string, optional: Text to use for the title, display a default if True.
colorstring, optional: A valid matplotlib color or column name. If a column name, common values will be provided the same color.
markerstring, optional: A valid matplotlib marker or column name. If a column name, common values will be provided the same marker.
linestylestring, optional: A valid matplotlib linestyle or column name. If a column name, common values will be provided the same linestyle.
fill_betweenboolean or dict, optional: Fill lines between minima/maxima of the ‘color’ argument. This can only be used if also providing a ‘color’ argument. If this is True, then default arguments will be provided to ax.fill_between(). If this is a dictionary, those arguments will be provided instead of defaults.
final_rangesboolean or dict, optional: Add vertical line between minima/maxima of the ‘color’ argument in the last period plotted. This can only be used if also providing a ‘color’ argument. If this is True, then default arguments will be provided to ax.axvline(). If this is a dictionary, those arguments will be provided instead of defaults.
rm_legend_labelstring or list, optional: Remove the color, marker, or linestyle label in the legend.
axmatplotlib.axes.Axes, optional
cmapstring, optional: The name of a registered colormap.
kwargs: Additional arguments passed to pandas.DataFrame.plot().

Returns:

axmatplotlib.axes.Axes: Modified ax or new instance

pyam.plotting.stack(df, x=None, y='value', stack='variable', order=None, total=None, legend=True, title=True, ax=None, cmap=None, **kwargs)[source]¶

Plot a stacked area chart of timeseries data

Parameters:

dfpyam.IamDataFrame, pandas.DataFrame: Data to be plotted
xstring, optional: The coordinates or column of the data points for the horizontal axis; defaults to the time domain (if df is IamDataFrame) or ‘year’.
ystring, optional: The coordinates or column of the data points for the vertical axis.
stackstring, optional: The column to use for stack groupings
orderlist, optional: The order to plot the stack levels and the legend. If not specified, order by run_control()['order'][<stack>] (where available) or alphabetical.
totalbool or dict, optional: If True, plot a total line with default pyam settings. If a dict, then plot the total line using the dict key-value pairs as keyword arguments to matplotlib.axes.Axes.plot(). If None, do not plot the total line.
legendbool, optional: Include a legend.
titlebool or string, optional: Text to use for the title, display a default if True.
axmatplotlib.axes.Axes, optional
cmapstring, optional: The name of a registered colormap.
kwargs: Additional arguments passed to pandas.DataFrame.plot()

Returns:

axmatplotlib.axes.Axes: Modified ax or new instance

pyam.plotting.bar(df, x=None, y='value', bars='variable', order=None, bars_order=None, orient='v', legend=True, title=True, ax=None, cmap=None, **kwargs)[source]¶

Plot data as a stacked or grouped bar chart

Parameters:

dfpyam.IamDataFrame, pandas.DataFrame: Data to be plotted
xstring, optional: The coordinates or column of the data points for the horizontal axis; defaults to the time domain (if df is IamDataFrame) or ‘year’.
ystring, optional: The coordinates or column of the data points for the vertical axis.
barsstring, optional: The column to use for bar groupings
order, bars_orderlist, optional: The order to plot the levels on the x-axis and the bars (and legend). If not specified, order by run_control()['order'][<stack>] (where available) or alphabetical.
orientstring, optional: Vertical or horizontal orientation.
legendbool, optional: Include a legend.
titlebool or string, optional: Text to use for the title, display a default if True.
axmatplotlib.axes.Axes, optional
cmapstring, optional: The name of a registered colormap.
kwargs: Additional arguments passed to pandas.DataFrame.plot()

Returns:

axmatplotlib.axes.Axes: Modified ax or new instance

pyam.plotting.box(df, y='value', x=None, by=None, legend=True, title=None, ax=None, **kwargs)[source]¶

Plot boxplot of data using seaborn.boxplot

Parameters:

dfpyam.IamDataFrame, pandas.DataFrame: Data to be plotted
ystring, optional: The column to use for y-axis values representing the distribution within the boxplot
xstring, optional: The coordinates or column of the data points for the horizontal axis; defaults to the time domain (if df is IamDataFrame) or ‘year’.
bystring, optional: The column for grouping y-axis values at each x-axis point, i.e. a 3rd dimension. Data should be categorical, not a contiuous variable.
legendbool, optional: Include a legend.
titlebool or string, optional: Text to use for the title, display a default if True.
axmatplotlib.axes.Axes, optional
kwargs: Additional arguments passed to pandas.DataFrame.plot().

Returns:

axmatplotlib.axes.Axes: Modified ax or new instance

pyam.plotting.scatter(df, x, y, legend=None, title=None, color=None, marker='o', linestyle=None, groupby=['model', 'scenario'], with_lines=False, ax=None, cmap=None, **kwargs)[source]¶

Plot data as a scatter chart.

Parameters:

dfclass:pyam.IamDataFrame: Data to be plotted
xstr: The coordinates or columns of the data points for the horizontal axis.
ystr: The coordinates or columns of the data points for the vertical axis.
legendbool, optional: Include a legend. By default, show legend only if less than 13 entries. If a dictionary is provided, it will be used as keyword arguments in creating the legend.
titlebool or string, optional: Text to use for the title, display a default if True.
colorstring, optional: A valid matplotlib color or column name. If a column name, common values will be provided the same color.
markerstring: A valid matplotlib marker or column name. If a column name, common values will be provided the same marker.
linestylestring, optional: A valid matplotlib linestyle or column name. If a column name, common values will be provided the same linestyle. default: None
groupbylist-like, optional: Data grouping for plotting.
with_linesbool, optional: Make the scatter plot with lines connecting common data.
axmatplotlib.axes.Axes, optional
cmapstring, optional: The name of a registered colormap.
kwargs: Additional arguments passed to pandas.DataFrame.plot().

Returns:

axmatplotlib.axes.Axes: Modified ax or new instance

pyam.plotting.pie(df, value='value', category='variable', legend=False, title=None, ax=None, cmap=None, **kwargs)[source]¶

Plot data as a pie chart.

Parameters:

dfpyam.IamDataFrame, pandas.DataFrame: Data to be plotted
valuestring, optional: The column to use for data values
categorystring, optional: The column to use for labels
legendbool, optional: Include a legend.
titlestring, optional: Text to use for the title.
axmatplotlib.axes.Axes, optional
cmapstring, optional: The name of a registered colormap.
kwargs: Additional arguments passed to pandas.DataFrame.plot().

Returns:

axmatplotlib.axes.Axes: Modified ax or new instance

pyam.figures.sankey(df, mapping)[source]¶

Plot a sankey diagram

It is currently only possible to create this diagram for single years.

Parameters:

dfpyam.IamDataFrame

Data to be plotted

mappingdict

Assigns the source and target component of a variable

{
    variable: (source, target),
}

Returns:

figplotly.graph_objects.Figure