Timeseries functions

The pyam package includes several utility functions for working with timeseries data formatted as pandas.Series that have the time dimension as index.

Warning

Not all pyam functions currently support continuous-time formats. Please reach out via our Slack channel, mailing list or GitHub issues if you are not sure whether your use case is supported.

Functions:

cross_threshold(x[, threshold, direction, ...])

Returns a list of the years in which a timeseries crosses a threshold

cumulative(x, first_year, last_year)

Returns the cumulative sum of a timeseries

fill_series(x, time)

Returns the timeseries value at a point in time by linear interpolation

growth_rate(x)

Compute the annualized growth rate from timeseries data

pyam.timeseries.cross_threshold(x, threshold=0, direction=['from above', 'from below'], return_type=<class 'int'>)[source]

Returns a list of the years in which a timeseries crosses a threshold

Parameters:
xpandas.Series

A timeseries indexed over years (as integers)

thresholdfloat, optional

The threshold that the timeseries is checked against

directionstr, optional

Whether to return all years where the threshold is crossed or only where threshold is crossed in a specific direction

return_typetype, optional

Whether to cast the returned values to integer (years)

pyam.timeseries.cumulative(x, first_year, last_year)[source]

Returns the cumulative sum of a timeseries

This function implements linear interpolation between years and ignores nan’s in the range. The function includes the last-year value of the series, and raises a warning if start_year or last_year is outside of the timeseries range and returns nan

Parameters:
xpandas.Series

a timeseries to be summed over time

first_yearint

first year of the sum

last_yearint

last year of the sum (inclusive)

pyam.timeseries.fill_series(x, time)[source]

Returns the timeseries value at a point in time by linear interpolation

Parameters:
xpandas.Series

a timeseries to be interpolated

timeint or pandas.datetime

year or datetime to interpolate

pyam.timeseries.growth_rate(x)[source]

Compute the annualized growth rate from timeseries data

The annualized growth rate parameter in period t is computed assuming exponential growth based on the changes from period t to period t+1.

Parameters:
xpandas.Series

Timeseries data indexed over the time domain.

Returns:
Indexed pandas.Series of annualized growth rates
Raises:
ValueError

Math domain error when timeseries crosses 0.

See also

pyam.IamComputeAccessor.growth_rate