Class IamDataFrame

class pyam_analysis.IamDataFrame(data, **kwargs)[source]

This class is a wrapper for dataframes following the IAMC data convention. It provides a number of diagnostic features (including validation of values, completeness of variables provided) as well as a number of visualization and plotting tools.


append(other, inplace=False, **kwargs)[source]

Import or read timeseries data and append to IamDataFrame


other: pyam-analysis.IamDataFrame, ixmp.TimeSeries, ixmp.Scenario,

pd.DataFrame or data file

an IamDataFrame, TimeSeries or Scenario (requires ixmp), or pd.DataFrame or data file with IAMC-format data columns

inplace : bool, default False

if True, do operation inplace and return None


Return this as a pd.DataFrame


with_metadata : bool, default False

if True, join data with existing metadata

bar_plot(*args, **kwargs)[source]

Plot timeseries bars of existing data

see pyam_analysis.plotting.bar_plot() for all available options

categorize(name, value, criteria, color=None, marker=None, linestyle=None)[source]

Assign scenarios to a category according to specific criteria or display the category assignment


name: str

category column name

value: str

category identifier

criteria: dict

dictionary with variables mapped to applicable checks (‘up’ and ‘lo’ for respective bounds, ‘year’ for years - optional)

color: str

assign a color to this category for plotting

marker: str

assign a marker to this category for plotting

linestyle: str

assign a linestyle to this category for plotting

col_apply(col, func, *args, **kwargs)[source]

Apply a function to a column


col: string

column in either data or metadata

func: functional

function to apply


Export metadata to Excel


path: string

path/filename for xlsx file of metadata export

filter(filters, keep=True, inplace=False)[source]

Return a filtered IamDataFrame (i.e., a subset of current data)


filters: dict

The following columns are available for filtering:
  • metadata columns: filter by category assignment in metadata

  • ‘model’, ‘scenario’, ‘region’, ‘variable’, ‘unit’: string or list of strings, where * can be used as a wildcard

  • ‘level’: the maximum “depth” of IAM variables (number of ‘|’) (exluding the strings given in the ‘variable’ argument)

  • ‘year’: takes an integer, a list of integers or a range

    note that the last year of a range is not included, so range(2010,2015) is interpreted as [2010, ..., 2014]

inplace : bool, default False

if True, do operation inplace and return None

head(*args, **kwargs)[source]

Identical to pd.DataFrame.head() operating on data


Interpolate missing values in timeseries (linear interpolation)


year: int

year to be interpolated

line_plot(*args, **kwargs)[source]

Plot timeseries lines of existing data

see pyam_analysis.plotting.line_plot() for all available options

load_metadata(path, *args, **kwargs)[source]

Load metadata from previously exported instance of pyam_analysis


path: string

xlsx file with metadata exported from an instance of pyam_analysis

metadata(meta, name=None)[source]

Add metadata columns as pd.Series or list


meta: pd.Series, list, int or str

column to be added to metadata (by [‘model’, ‘scenario’] index if possible)

name: str

category column name (if not given by data series name)

pie_plot(*args, **kwargs)[source]

Plot a pie chart

see pyam_analysis.plotting.pie_plot() for all available options

pivot_table(index, columns, values='value', aggfunc='count', fill_value=None, style=None)[source]

Returns a pivot table


index: str or list of strings

rows for Pivot table

columns: str or list of strings

columns for Pivot table

values: str, default ‘value’

dataframe column to aggregate or count

aggfunc: str or function, default ‘count’

function used for aggregation, accepts ‘count’, ‘mean’, and ‘sum’

fill_value: scalar, default None

value to replace missing values with

style: str, default None

output style for pivot table formatting accepts ‘highlight_not_max’, ‘heatmap’

region_plot(map_regions=False, map_col='iso', **kwargs)[source]

Plot regional data for a single model, scenario, variable, and year

see pyam_analysis.plotting.region_plot() for all available options


map_regions: boolean or string, default False

Apply a mapping from existing regions to regions to plot. If True, the mapping will be searched in known locations (e.g., if registered with run_control()). If a path to a file is provided, that file will be used. Files must have a “region” column of existing regions and a mapping column of regions to be mapped to.

map_col: string, default ‘iso’

The column used to map new regions to.

require_variable(variable, unit=None, year=None, exclude=False)[source]

Check whether all scenarios have a required variable


variable: str

required variable

unit: str, default None

name of unit (optional)

years: int or list, default None

years (optional)

exclude: bool, default False

flag scenarios missing the required variables as exclude: True


Reset exclusion assignment for all scenarios to exclude: False

stack_plot(*args, **kwargs)[source]

Plot timeseries stacks of existing data

see pyam_analysis.plotting.stack_plot() for all available options

tail(*args, **kwargs)[source]

Identical to pd.DataFrame.tail() operating on data


Returns a dataframe in the standard IAMC format

to_csv(path, index=False, **kwargs)[source]

Write data to a csv file


index: boolean, default False

write row names (index)

to_excel(path=None, writer=None, sheet_name='data', index=False, **kwargs)[source]

Write timeseries data to Excel using the IAMC template convention (wrapper for pd.DataFrame.to_excel())


excel_writer: string or ExcelWriter object

file path or existing ExcelWriter

sheet_name: string, default ‘data’

name of the sheet that will contain the (filtered) IamDataFrame

index: boolean, default False

write row names (index)

validate(criteria={}, exclude=False)[source]

Validate scenarios using criteria on timeseries values


criteria: dict

dictionary with variable keys and check values

(‘up’ and ‘lo’ for respective bounds, ‘year’ for years)

exclude: bool, default False

flag scenarios failing validation as exclude: True