Plotting library

The plotting API(s)

There are three ways to use the pyam plotting library.

  1. Using the plot feature as an attribute of the IamDataFrame:

    IamDataFrame.plot.<kind>(**kwargs)

  2. 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.

  3. 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