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='year', y='value', 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
dfpd.DataFrame

Data to plot as a long-form data frame

xstring, optional

The column to use for x-axis values

ystring, optional

The column to use for y-axis values

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

Display a default or custom title.

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, 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='year', 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 column to use for x-axis values

ystring, optional

The column to use for y-axis values

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

Display a default or custom 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.plotting.bar(df, x='year', 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 column to use for x-axis values

ystring, optional

The column to use for y-axis values

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

Display a default or custom 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.plotting.box(df, y='value', x='year', 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 column to use for x-axis points, i.e. the number of boxes the plot will have

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

Display a default or custom title.

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

column to be plotted on the x-axis

ystr

column to be plotted on the y-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

Display a custom title.

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=True, 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.

titlebool or string, optional

Display a default or custom 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