Filtering and slicing

Arguments for filtering an IamDataFrame

The pyam package provides several methods to filter an IamDataFrame by its (timeseries) data or meta values. Read more about the Data Model that is implemented by an IamDataFrame.

The following arguments are available for filtering and can be combined as needed:

Index

Timeseries data coordinates

  • Any column of the IamDataFrame.coordinates (’region’, ‘variable’, ‘unit’): string or list of strings

  • ‘measurand’: a tuple (or list of tuples) of ‘variable’ and ‘unit’

  • ‘depth’: the “depth” of entries in the ‘variable’ column (number of ‘|’)

  • ‘level’: the “depth” of entries in the ‘variable’ column (number of ‘|’), excluding the strings in the ‘variable’ argument (if given)

  • ‘year’: takes an integer (int/numpy.int64), 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]

  • ‘time_domain’: can be ‘year’ or ‘datetime’

  • Arguments for filtering by datetime.datetime or numpy.datetime64 (’month’, ‘hour’, ‘time’)

Meta indicators and other attributes

  • Any column of the IamDataFrame.meta dataframe: string, integer, float, or list of these

  • ‘exclude’ (see IamDataFrame.exclude): boolean

Note

In any string filters, ‘*’ is interpreted as wildcard, unless the keyword argument regexp=True is used; in this case, strings are treated as regular expressions.

Methods for filtering and slicing an IamDataFrame

IamDataFrame.filter(*, keep=True, inplace=False, **kwargs)[source]

Return a (copy of a) filtered (downselected) IamDataFrame

Parameters:
keepbool, optional

Keep all scenarios satisfying the filters (if True) or the inverse.

inplacebool, optional

If True, do operation inplace and return None.

**kwargs

Arguments for filtering. Read more about the available filter options.

Returns:
pyam.IamDataFrame or None
IamDataFrame.slice(*, keep=True, **kwargs)[source]

Return a (filtered) slice object of the IamDataFrame timeseries data index

Parameters:
keepbool, optional

Keep all scenarios satisfying the filters (if True) or the inverse.

**kwargs

Arguments for filtering. Read more about the available filter options.

Returns:
pyam.slice.IamSlice

The IamSlice class

This class is an auxiliary feature to streamline the implementation of the IamDataFrame.filter() method.

class pyam.slice.IamSlice(data=None, index=None, **kwargs)[source]

A slice object of the IamDataFrame timeseries data index

Attributes:
dimensions

Return the list of index names & data coordinates

time

The time index, i.e., axis labels related to the time domain.

Methods

info([n])

Print a summary of the represented index dimensions and data coordinates
property dimensions

Return the list of index names & data coordinates

info(n=80)[source]

Print a summary of the represented index dimensions and data coordinates

Parameters:
nint

The maximum line length

property time

The time index, i.e., axis labels related to the time domain.

Returns:

Filtering using a proxy IamDataFrame

pyam includes a function to directly filter a pandas.DataFrame with appropriate columns or index dimensions (i.e.,’model’ and ‘scenario’) using an IamDataFrame and keyword arguments similar to IamDataFrame.filter().

pyam.filter_by_meta(data, df, join_meta=False, **kwargs)[source]

Filter by and join meta columns from an IamDataFrame to a pd.DataFrame

Parameters:
datapandas.DataFrame

Data to which meta columns are to be joined, index or columns must include [‘model’, ‘scenario’]

dfIamDataFrame

IamDataFrame from which meta columns are filtered and joined (optional)

join_metabool, optional

join selected columns from df.meta on data

**kwargs

Meta columns to be filtered/joined, where col=… applies filters with the given arguments (using utils.pattern_match()). Using col=None joins the column without filtering (setting col to nan if (model, scenario) not in df.meta.index)