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=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:
- df
pyam.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 byrun_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.
- 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.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:
- df
pyam.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 tomatplotlib.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.
- 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=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:
- df
pyam.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.
- 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=None, 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 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.
- 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
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.
- 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=None, 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.
- titlestring, optional
Text to use for the 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: