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 thefigures
module directly viapyam.<module>.<kind>(df, **kwargs)
where df is either an
IamDataFrame
or a suitablepandas.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.
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.
- ax
matplotlib.axes.Axes
, optional - cmapstring, optional
The name of a registered colormap.
- kwargs
Additional arguments passed to
pandas.DataFrame.plot()
.
- Returns
- ax
matplotlib.axes.Axes
Modified ax or new instance
- ax
-
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
- df
pyam.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 tomatplotlib.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.
- ax
matplotlib.axes.Axes
, optional - cmapstring, optional
The name of a registered colormap.
- kwargs
Additional arguments passed to
pandas.DataFrame.plot()
- df
- Returns
- ax
matplotlib.axes.Axes
Modified ax or new instance
- ax
-
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
- df
pyam.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.
- ax
matplotlib.axes.Axes
, optional - cmapstring, optional
The name of a registered colormap.
- kwargs
Additional arguments passed to
pandas.DataFrame.plot()
- df
- Returns
- ax
matplotlib.axes.Axes
Modified ax or new instance
- ax
-
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
- df
pyam.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.
- ax
matplotlib.axes.Axes
, optional - kwargs
Additional arguments passed to
pandas.DataFrame.plot()
.
- df
- Returns
- ax
matplotlib.axes.Axes
Modified ax or new instance
- ax
-
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.
- ax
matplotlib.axes.Axes
, optional - cmapstring, optional
The name of a registered colormap.
- kwargs
Additional arguments passed to
pandas.DataFrame.plot()
.
- Returns
- ax
matplotlib.axes.Axes
Modified ax or new instance
- ax
-
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
- df
pyam.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.
- ax
matplotlib.axes.Axes
, optional - cmapstring, optional
The name of a registered colormap.
- kwargs
Additional arguments passed to
pandas.DataFrame.plot()
.
- df
- Returns
- ax
matplotlib.axes.Axes
Modified ax or new instance
- ax
-
pyam.figures.
sankey
(df, mapping)[source]¶ Plot a sankey diagram
It is currently only possible to create this diagram for single years.
- Parameters
- df
pyam.IamDataFrame
Data to be plotted
- mappingdict
Assigns the source and target component of a variable
{ variable: (source, target), }
- df
- Returns