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)[source]

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)[source]
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)[source]

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)[source]

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)[source]

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

aneris._io.read_excel(f)[source]

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)[source]

A helper class to harmonize all scenarios for a model.

Methods

harmonize(scenario)[source]

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

harmonized_results()[source]

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

scenarios()[source]

Return all known scenarios

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

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

Methods

harmonize(overrides=None)[source]

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

metadata()[source]

Return pd.DataFrame of method choice metadata

methods(overrides=None)[source]

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

aneris.harmonize.diagnostics(unharmonized, model, metadata)[source]

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:

unharmonized : pd.DataFrame

unharmonized model data in standard calculation format

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)[source]

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)[source]

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)[source]

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)[source]

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')[source]

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)[source]

Returns df (no change)

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

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)[source]

Returns result of aneris.methods.constant_offset()

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

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')[source]

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)[source]

Helper class to aggregate emissions

Methods

add_variables(totals=None, aggregates=True)[source]

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)[source]

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='')[source]

Helper class to translate between IAMC and calcluation formats

Methods

to_std(df=None, set_metadata=True)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

The gas associated with each variable

aneris.utils.isnum(s)[source]

Returns True if s is a number

aneris.utils.isstr(x)[source]

Returns True if x is a string

aneris.utils.logger()[source]

Global Logger used for aneris

aneris.utils.numcols(df)[source]

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

aneris.utils.remove_emissions_prefix(x, gas='XXX')[source]

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

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

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)[source]

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)[source]

returns a units column given a variable column