Core LMDI Model

class EnergyIntensityIndicators.LMDI.CalculateLMDI(sector, level_of_aggregation, lmdi_models, categories_dict, energy_types, directory, output_directory, primary_activity=None, base_year=1985, end_year=2017, unit_conversion_factor=1, weather_activity=None)

Bases: EnergyIntensityIndicators.LMDI.LMDI

build_col_list(data, key)

Return bool indicating whether dataset contains data for given key

build_nest(data, select_categories, results_dict, level1_name, level_name=None)

Process and organize raw data

calc_lower_level(categories, final_fmt_results, e_type)

Calculate decomposition for lower levels of aggregation

calculate_breakout_lmdi(raw_results, final_results_list, level_of_aggregation, breakout, categories, lmdi_type)

If breakout=True, calculate LMDI for each lower aggregation level contained in raw_results.

Parameters

• raw_results (dictionary) – Built “nest” of dictionaries containing input data for LMDI calculations

• final_results_list (list) – list to which calculate_breakout_lmdi appends LMDI results

Returns

list of LMDI results dataframes

Return type

final_results_list [list]

TODO: Lower level Total structure (product of each structure index for multiplicative) and component intensity index (index of aggregate intensity divided by total strucutre) need to be passed to higher level

calculate_energy_data(e_type, energy_data)

Calculate ‘deliv’, ‘source’, and ‘source_adj’ data from ‘fuels’ and ‘elec’ dataframes contained in the energy_data dictionary.

static calculate_shares(dataset, total_label)

“sum row, calculate each type of energy as percentage of total :param dataset: energy data :type dataset: dataframe

Returns

shares – contains shares of each energy category relative to total energy

Return type

dataframe

call_lmdi(energy_input_data, activity_input_data, lower_level_structure, lower_level_intensity_df, total_label, unit_conversion_factor, weather_data, lmdi_type, loa=None, energy_type=None)

Prepare LMDI inputs and pass them to call_decomposition method.

Returns

formatted LMDI results

Return type

results (dataframe)

static check_cols(dict_key, df, label)

Check whether dataframe contains column matching dict_key

collect_energy_data(energy_data)

Calculate energy data for energy types in self.energy_types for which data is not provided

Example data:

data_dict = {‘All_Passenger’: {‘energy’: {‘deliv’: passenger_based_energy_use},

‘activity’: passenger_based_activity},

‘All_Freight’: {‘energy’: {‘deliv’: freight_based_energy_use},

‘activity’: freight_based_activity}}

static create_total_column(df, total_label)

Create column from sum of all other columns, name with name of level of aggregation

static deep_get(dictionary, keys, default=None)

Get lower level portion of nested dictionary from path

static get_deliv(elec, fuels)

Calculate delivered energy by adding electricity and fuels then add ‘Energy_Type’ column to the resulting delivered energy dataframe

static get_elec(elec)

Add ‘Energy_Type’ column to electricity dataframe

static get_fuels(fuels)

Add ‘Energy_Type’ column to fuels dataframe

get_nested_lmdi(level_of_aggregation, raw_data, lmdi_type, calculate_lmdi=False, breakout=False)

Collect LMDI decomposition according to user specifications

get_source(elec, fuels)

Call conversion factors method from GetEIAData, calculate source energy from conversion_factors, electricity and fuels dataframe, then add ‘Energy-Type’ column to the resulting source energy dataframe

get_source_adj(elec, fuels)

Call conversion factors method from GetEIAData, calculate source adjusted energy from conversion_factors, electricity and fuels dataframe, then add ‘Energy-Type’ column to the resulting source adjusted energy dataframe

static int_index(df)

Ensure df index is Year of type int

static logarithmic_average(x, y)

The logarithmic average of two positive numbers x and y

merge_input_data(list_dfs, second_index)

Merge dataframes of same variable type

nominal_energy_intensity(energy_input_data, activity_input_data)

Calculate nominal energy intensity (i.e. energy divided by activity)

order_categories(level_of_aggregation, raw_results)

Order categories so that lower levels are calculated prior to current level of aggregation. This ordering ensures that lower level structure is passed to higher level.

prepare_lmdi_inputs(energy_type, energy_input_data, activity_input_data, lower_level_intensity_df, total_label, weather_data, unit_conversion_factor=1)

Calculate the LMDI inputs (collect log ratio components)

Parameters

• activity_input_data (dataframe or dictionary of dataframes) – Activity input data for LMDI calculations

• energy_input_data (dataframe) – Energy input data for LMDI calculations

• total_label (str) – Name of the level of the level of aggregation representing the total of the current level. E.g. If categories are “Northeast”, “South”, etc, the total_label is “National”

• unit_conversion_factor (int, optional) – [description]. Defaults to 1.

static select_value(dataframe, base_row, base_column)

Select value from dataframe as in Excel’s @index function

class EnergyIntensityIndicators.LMDI.LMDI(sector, lmdi_models, output_directory, base_year, end_year, primary_activity)

Bases: object

Base class for LMDI

LMDI_types = {'additive': <class 'EnergyIntensityIndicators.additive_lmdi.AdditiveLMDI'>, 'multiplicative': <class 'EnergyIntensityIndicators.multiplicative_lmdi.MultiplicativeLMDI'>}

calc_ASI(model, log_mean_divisia_weights_normalized, log_ratios, total_label)

Collect activity, structure, and intensity components

calc_component(log_ratio_component, weights, type_, primary_activity)

Calculate the component values from log_ratio components and log mean divisia weights

static calculate_log_changes(dataset)

Calculate the log changes Parameters: ———-

dataset: dataframe

log_ratio: dataframe

call_decomposition(energy_data, energy_shares, log_ratios, total_label, lmdi_type, loa, energy_type)

Calculate Log Mean Divisia Index from input data

data_visualization(data, loa, energy_type, total_label)

Format data for proper visualization

The following data types have been proposed (an ellipsis … indicates an optional parameter):

@filter|Category1|…Category2|…|Label#units

A list of options that can be grouped by 1 or more categories. @weight|Category1|…Category2|…|Label#units

A weighted value to use with a matching filter (must match filter label and categories). @scenario|Label

A list of options that are completely separate from each other, i.e. they will not be seen on the same chart at the same time. The options come from the unique values in the scenario column. @timeseries|Label

A list of options that can be used to make a time series, e.g. a list of years. @geography|Label

A list of geography names, e.g. states, counties, cities, that can be used in charts or a choropleth map. @geoid

The column values are geography IDs that can be used in a choropleth map. @latlong

Latitude and longitude coordinates

Example Data Schema:

“@Geography”	“@Year”	“@filter|Sector”	“@filter|Measure|Activity”	“@filter|Measure|Structure”	“@filter|Measure|Intensity”	“@filter|Measure|Weight”
National	2000	A	0	0	0	0
National	2000	B	0	0	0	0
National	2010	A	0.8123	.6931	-0.1823	86.56
National	2010	B	0.8123	-0.287	-0.287	33.07

Parameters

• Returns –

• csv –

ensure_same_indices(df1, df2)

Returns two dataframes with the same indices purpose: enable dataframe operations such as multiply and divide between the two dfs

sum_product(component_, weights, name)

Calculate the sum product of a log-ratio component and log mean divisia weights, rename column in the resulting dataframe

static use_intersection(data, intersection_)

Select portion of dataframe where index is in intersection_

• Multiplicative LMDI
• AdditiveLMDI