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

__init__(rc=None, defaults=None)

Parameters:

rc : string, file, dictionary, optional

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

defaults : string, file, dictionary, optional

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

recursive_update(k, d)

Recursively update a top-level option in the run control

Parameters:

k : string

the top-level key

d : dictionary or similar

the dictionary to use for updating

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

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

Parameters:

f : string

the file to read in

str_cols : bool, optional

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

args, kwargs : sent directly to the Pandas read function

Returns:

df : pd.DataFrame

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

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

aneris._io.read_excel(f)

Read an excel-based input file for harmonization.

Parameters:

f : string

path to input file

Returns:

model : pd.DataFrame

model data frame in IAMC format

overrides : pd.DataFrame

overrides data frame in IAMC format

config : dictionary

configuration overrides (if any)

Harmonization: aneris.harmonize

class aneris.harmonize.HarmonizationDriver(rc, hist, model, overrides, regions)

A helper class to harmonize all scenarios for a model.

Methods

harmonize(scenario)

Harmonize a given scneario. Get results from aneris.harmonize.HarmonizationDriver.results()

harmonized_results()

Return 2-tuple of (pd.DataFrame of harmonized trajectories, pd.DataFrame of metadata)

scenarios()

Return all known scenarios

class aneris.harmonize.Harmonizer(data, history, config={}, verify_indicies=True)

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

Methods

harmonize(overrides=None)

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

metadata()

Return pd.DataFrame of method choice metadata

methods(overrides=None)

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

aneris.harmonize.diagnostics(model, metadata)

Provide warnings or throw errors based on harmonized model data and metadata

Current diagnostics are: - large missing values (sector has 20% or more contribution to

history and model does not report sector) - Warning provided

• non-negative CO2 emissions (values other than CO2 are < 0) - Error thrown

Parameters:

model : pd.DataFrame

harmonized model data in standard calculation format

metadata : pd.DataFrame

harmonization metadata

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.coeff_of_var(s)

Returns coefficient of variation of a Series

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

Parameters:

s : pd.Series

timeseries

Returns:

c_v : float

coefficient of variation

aneris.methods.constant_offset(df, offset)

Calculate constant offset harmonized trajectory

Parameters:

df : pd.DataFrame

model data

offset : pd.DataFrame

offset data

Returns:

df : pd.DataFrame

harmonized trajectories

aneris.methods.constant_ratio(df, ratios)

Calculate constant ratio harmonized trajectory

Parameters:

df : pd.DataFrame

model data

ratio : pd.DataFrame

ratio data

Returns:

df : pd.DataFrame

harmonized trajectories

aneris.methods.default_methods(hist, model, base_year, luc_method=None)

Determine default harmonization methods to use.

See http://mattgidden.com/aneris/theory.html#default-decision-tree for a graphical description of the decision tree.

Parameters:

hist : pd.DataFrame

historical data

model : pd.DataFrame

model data

base_year : string, int

column name of harmonization year

luc_method : string, optional

method to use for high coefficient of variation

Returns:

methods : pd.Series

default harmonization methods

metadata : pd.DataFrame

metadata regarding why each method was chosen

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

Calculate offset and ratio values between data and history

Parameters:

df : pd.DataFrame

model data

hist : pd.DataFrame

historical data

harmonize_year : string, optional

column name of harmonization year

Returns:

offset : pd.Series

offset (history - model)

ratio : pd.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:

df : pd.DataFrame

model data

offset : pd.DataFrame

offset data

final_year : string, optional

column name of convergence year

harmonize_year : string, optional

column name of harmonization year

Returns:

df : pd.DataFrame

harmonized trajectories

aneris.methods.model_zero(df, offset)

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:

df : pd.DataFrame

model data

offset : pd.DataFrame

offset data

final_year : string, optional

column name of convergence year

harmonize_year : string, optional

column name of harmonization year

Returns:

df : pd.DataFrame

harmonized trajectories

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

Calculate ratio convergence harmonized trajectory

Parameters:

df : pd.DataFrame

model data

ratio : pd.DataFrame

ratio data

final_year : string, optional

column name of convergence year

harmonize_year : string, optional

column name of harmonization year

Returns:

df : pd.DataFrame

harmonized trajectories

Tools/Utilities: aneris.utils

class aneris.utils.EmissionsAggregator(df, model=None, scenario=None)

Helper class to aggregate emissions

Methods

add_variables(totals=None, aggregates=True)

Add aggregates and variables with direct mappings.

Parameters:

totals : list, optional

sectors to compute totals for

add_aggregates : bool, optional

whether to add aggregate variables

to_template(**kwargs)

Create an IAMC template out of the original data frame

Parameters:first_year: optional, the first year to report values for

class aneris.utils.FormatTranslator(df=None, prefix='', suffix='')

Helper class to translate between IAMC and calcluation formats

Methods

to_std(df=None, set_metadata=True)

Translate a dataframe from IAMC to standard calculation format

Parameters:

df : pd.DataFrame, optional

set_metadata : bool, optional

save metadata (model, scenario) for future use

to_template(df=None, model=None, scenario=None, column_style=None)

Translate a dataframe from standard calculation format to IAMC

Parameters:

df : pd.DataFrame, optional

model : string, optional

model name

scenario : string, optional

scenario name

column_style : string

column style (upper, lower, etc.) to use

aneris.utils.agg_regions(df, rfrom='ISO Code', rto='Native Region Code', mapping=None, verify=True)

Aggregate values in a dataframe to a new regional composition

Parameters:

df : pd.DataFrame

rfrom : string

original regional composition column name in mapping

rto : string

column name to use for aggregation in mapping

mapping : pd.DataFrame, optional

mapping to use, otherwise MESSAGE mappings are read

verify : bool, optional

if True, confirm that sum of original values == sum of aggregated values

Returns:

df : pd.DataFrame

aneris.utils.check_null(df, name=None, fail=False)

Determines which values, if any in a dataframe are null

Parameters:

df : pd.DataFrame

name : string, optional

the name of the dataframe to use in a warning message

fail : bool, optional

if True, assert that no null values exist

aneris.utils.combine_rows(df, level, main, others=None, sumall=True, dropothers=True, rowsonly=False, newlabel=None)

Combine rows (add values) in a dataframe. Rows corresponding to the main and other values in a given level (or column) are added together and reattached taking the main value in the new column.

For example, countries can be combined using this strategy.

Parameters:

df : pd.DataFrame

level : string, int

common level or column (e.g., ‘region’)

main : string

the value of the level to aggregate on

others : string, optional

a list of other values to aggregate

sumall : bool, optional

sum main and other values (otherwise, only add other values)

dropothers : bool, optional

remove rows with values provided in others

rowsonly : bool, optional

only return newly generated rows

newlabel : string, optional

a new label for the level/column value, default is main

Returns:

df : pd.DataFrame

resulting data

aneris.utils.gases(var_col)

The gas associated with each variable

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.remove_emissions_prefix(x, gas='XXX')

Return x with emissions prefix removed, e.g., Emissions|XXX|foo|bar -> foo|bar

aneris.utils.remove_recalculated_sectors(df, prefix='', suffix='')

Return df with Total gas (sum of all sectors) removed

aneris.utils.subtract_regions_from_world(df, name=None, base_year='2015', threshold=0.05)

Subtract the sum of regional results in each variable from the World total. If the result is a World total below a threshold, set those values to 0.

Parameters:

df : pd.DataFrame

name : string, optional

name to use in error checking

base_year : int, string, optional

column to use in error checking

threshold : float, optional

threshold below which to set values to 0

aneris.utils.units(var_col)

returns a units column given a variable column