Python API

Warning

Please note that aneris is still in early developmental stages, thus all interfaces are subject to change.

Input/Output: aneris._io

Provides helper functions for reading input data and configuration files.

The default configuration values are provided in aneris.RC_DEFAULTS.

class aneris._io.RunControl(rc=None, defaults=None)

A thin wrapper around a Python Dictionary to support configuration of harmonization execution.

Input can be provided as dictionaries or YAML files.

Methods

get(k[,d])
items()
keys()
recursive_update(k, d)	Recursively update a top-level option in the run control.
values()

__init__(rc=None, defaults=None)

Parameters:

rcstring, file, dictionary, optional

a path to a YAML file, a file handle for a YAML file, or a dictionary describing run control configuration

defaultsstring, file, dictionary, optional

a path to a YAML file, a file handle for a YAML file, or a dictionary describing default run control configuration

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

recursive_update(k, d)

Recursively update a top-level option in the run control.

Parameters:

kstring

the top-level key

ddictionary or similar

the dictionary to use for updating

aneris._io.read_excel(f)

Read an excel-based input file for harmonization.

Parameters:

fstring

path to input file

Returns:

modelpd.DataFrame

model data frame in IAMC format

overridespd.DataFrame

overrides data frame in IAMC format

configdictionary

configuration overrides (if any)

Harmonization: aneris.harmonize

class aneris.harmonize.Harmonizer(data, history, config={}, harm_idx=['region', 'gas', 'sector'], method_choice=None)

A class used to harmonize model data to historical data in the standard calculation format.

Methods

harmonize([year, overrides])	Return pd.DataFrame of harmonized trajectories given pd.DataFrame overrides.
metadata()	Return pd.DataFrame of method choice metadata.
methods([year, overrides])	Return pd.DataFrame of methods to use for harmonization given pd.DataFrame of overrides.

harmonize(year=None, overrides=None)

Return pd.DataFrame of harmonized trajectories given pd.DataFrame overrides.

metadata()

Return pd.DataFrame of method choice metadata.

methods(year=None, overrides=None)

Return pd.DataFrame of methods to use for harmonization given pd.DataFrame of overrides.

Methods: aneris.methods

This module defines all possible functional forms of harmonization methods and the default decision tree for choosing which method to use.

aneris.methods.budget(df, df_hist, harmonize_year='2015')

Calculate budget harmonized trajectory.

Parameters:

dfpd.DataFrame

model data

df_histpd.DataFrame

historic data

harmonize_yearstring, optional

column name of harmonization year

Returns:

df_harmpd.DataFrame

harmonized trajectories

Notes

Finds an emissions trajectory consistent with a provided historical emissions timeseries that closely matches a modeled result, while maintaining the overall carbon budget.

An optimization problem is constructed and solved by IPOPT, which minimizes the difference between the rate of change of the model and the harmonized model in each year, while 1. preserving the carbon budget of the model, and 2. being consistent with the historical value.

With years \(y_i\), model results \(m_i\), harmonized results \(x_i\), historical value \(h_0\) and a remaining carbon budget \(B\), the optimization problem can be formulated as

\[\min_{x_i} \sum_{i \in |I - 1|} \big( \frac{m_{i+1} - m_i}{y_{i + 1} - y_{i}} - \frac{x_{i+1} - x_i}{y_{i + 1} - y_{i}} \big)^2\]

s.t.

\[\sum_{i} (y_{i + 1} - y_{i}) \big( x_i + 0.5 (x_{i+1} - x_i) \big) = B \quad \text{(carbon budget preservation)}\]

and

\[x_0 = h_0 \quad \text{(consistency with historical values)}\]

aneris.methods.coeff_of_var(s)

Returns coefficient of variation of a Series.

\[c_v = \frac{\sigma(s^{\prime}(t))}{\mu(s^{\prime}(t))}\]

Parameters:

spd.Series

timeseries

Returns:

c_vfloat

coefficient of variation

aneris.methods.constant_offset(df, offset, harmonize_year='2015')

Calculate constant offset harmonized trajectory.

Parameters:

dfpd.DataFrame

model data

offsetpd.DataFrame

offset data

harmonize_yearstring, optional

column name of harmonization year, ignored

Returns:

dfpd.DataFrame

harmonized trajectories

aneris.methods.constant_ratio(df, ratios, harmonize_year='2015')

Calculate constant ratio harmonized trajectory.

Parameters:

dfpd.DataFrame

model data

ratiopd.DataFrame

ratio data

harmonize_yearstring, optional

column name of harmonization year, ignored

Returns:

dfpd.DataFrame

harmonized trajectories

aneris.methods.default_method_choice(row, ratio_method, offset_method, luc_method, luc_cov_threshold)

Default decision tree as documented at.

Refer to choice flow chart at https://drive.google.com/drive/folders/0B6_Oqvcg8eP9QXVKX2lFVUJiZHc for arguments available in row and their definition

aneris.methods.harmonize_factors(df, hist, harmonize_year='2015')

Calculate offset and ratio values between data and history.

Parameters:

dfpd.DataFrame

model data

histpd.DataFrame

historical data

harmonize_yearstring, optional

column name of harmonization year

Returns:

offsetpd.Series

offset (history - model)

ratiopd.Series

ratio (history / model)

aneris.methods.hist_zero(df, *args, **kwargs)

Returns df (no change)

aneris.methods.linear_interpolate(df, offset, final_year='2050', harmonize_year='2015')

Calculate linearly interpolated convergence harmonized trajectory.

Parameters:

dfpd.DataFrame

model data

offsetpd.DataFrame

offset data

final_yearstring, optional

column name of convergence year

harmonize_yearstring, optional

column name of harmonization year

Returns:

dfpd.DataFrame

harmonized trajectories

aneris.methods.model_zero(df, offset, harmonize_year='2015')

Returns result of aneris.methods.constant_offset()

aneris.methods.reduce_offset(df, offset, final_year='2050', harmonize_year='2015')

Calculate offset convergence harmonized trajectory.

Parameters:

dfpd.DataFrame

model data

offsetpd.DataFrame

offset data

final_yearstring, optional

column name of convergence year

harmonize_yearstring, optional

column name of harmonization year

Returns:

dfpd.DataFrame

harmonized trajectories

aneris.methods.reduce_ratio(df, ratios, final_year='2050', harmonize_year='2015')

Calculate ratio convergence harmonized trajectory.

Parameters:

dfpd.DataFrame

model data

ratiopd.DataFrame

ratio data

final_yearstring, optional

column name of convergence year

harmonize_yearstring, optional

column name of harmonization year

Returns:

dfpd.DataFrame

harmonized trajectories

Tools/Utilities: aneris.utils

aneris.utils.isin(df=None, **filters)

Constructs a MultiIndex selector.

aneris.utils.isnum(s)

Returns True if s is a number.

aneris.utils.isstr(x)

Returns True if x is a string.

aneris.utils.logger()

Global Logger used for aneris.

aneris.utils.numcols(df)

Returns all columns in df that have data types of floats or ints.

aneris.utils.pd_read(f, str_cols=False, *args, **kwargs)

Try to read a file with pandas, supports CSV and XLSX.

Parameters:

fstring

the file to read in

str_colsbool, optional

turn all columns into strings (numerical column names are sometimes read in as numerical dtypes)

args, kwargssent directly to the Pandas read function

Returns:

dfpd.DataFrame

aneris.utils.pd_write(df, f, *args, **kwargs)

Try to write a file with pandas, supports CSV and XLSX.