4.1.1.4. bca_tool_code.general_modules package

4.1.1.4.1. Submodules

4.1.1.4.2. bca_tool_code.general_modules.annual_summary module

class AnnualSummary

Bases: object

The AnnualSummary class creates a summary of results by year_id along with present values and annualized values for use in the benefit-cost analysis.

__init__()

annual_summary(settings, data_object, options, year_ids)

Parameters:

• settings – object; the SetInputs class object.

• data_object – object; the fleet data object to summarize.

• options – object; the options object associated with the data_object.

• year_ids – range; the min_year_id thru max_year_id as set in settings.

Returns:

Updates the annual summary dictionary with annual, present and annualized values based on the data_object.

get_attribute_value(key, attribute_name)

Parameters:

• key – tuple; (series, option_id, year_id, rate), where series is ‘AnnualValue’, ‘PresentValue’ or ‘AnnualizedValue’.

• attribute_name – str; the attribute for which the value is sought.

Returns:

The value associated with the attribute for the given key.

update_object_dict(key, update_dict)

Parameters:

• key – tuple; ((vehicle_id), option_id, modelyear_id, age_id, discount_rate).

• update_dict – Dictionary; represents the attribute-value pairs to be updated.

Returns:

Updates the object dictionary with each attribute updated with the appropriate value.

static calc_annualized_value(present_value, rate, periods, annualized_offset)

Parameters:

• present_value – Numeric; the present value to be annualized.

• rate – Numeric; the discount rate to use.

• periods – int; the number of periods over which to annualize present_value.

• annualized_offset – int; 0 or 1 reflecting whether costs are assumed to occur at the start of the year or the end of the year.

Returns:

A single annualized value of present_value discounted at rate over periods number of year_ids.

4.1.1.4.3. bca_tool_code.general_modules.calc_deltas module

calc_deltas(settings, data_object, options)

This function calculates deltas for action alternatives relative to the no action alternative set via the General Inputs.

Parameters:

• settings – object; the SetInputs class object.

• data_object – object; the fleet data object.

• options – object; the options object associated with the data_object.

Returns:

Updates the data_object dictionary with deltas relative to the no_action_alt. OptionIDs (numeric) for the deltas will be the alt_id followed by the no_action_alt. For example, deltas for optionID=1 relative to optionID=0 will have optionID=10. OptionNames will also show as ‘OptionID=1_name minus OptionID=0_name’.

calc_deltas_weighted(settings, dict_for_deltas, options)

This function calculates deltas for action alternatives relative to the passed no action alternative specifically for the weighted cost per mile dictionaries.

Parameters:

• settings – object; the SetInputs class object.

• dict_for_deltas – Dictionary; contains values for calculating deltas.

• options – object; the options object associated with the data_object.

Returns:

An updated dictionary containing deltas relative to the no_action_alt. OptionIDs (numeric) for the deltas will be the option_id followed by the no_action_alt. For example, deltas for optionID=1 relative to optionID=0 would have optionID=10.

Note

There is no age_id or discount rate in the key for the passed weighted dictionaries; this function was not used for the HD2027 FRM so may not work properly.

4.1.1.4.4. bca_tool_code.general_modules.create_figures module

class CreateFigures(df, units, destination, program)

Bases: object

__init__(df, units, destination, program)

The CreateFigures class is used to generate figures (charts).

Parameters:

• df – DataFrame; contains data to be charted.

• units – str; units for use on the y-axis of the created chart.

• destination – Path object; provides the path to which to save the created chart.

• program – str; the program identifier (i.e., ‘CAP’ or ‘GHG’) to include in the saved filename.

line_chart_args_by_option(dr, alt_name, year_min, year_max, *args)

This method generates a chart showing passed arguments under the given alternative.

Parameters:

• dr – Numeric; the discount rate of the data to be charted.

• alt_name – str; the OptionName of the data to be charted.

• year_min – int; the minimum calendar year of data to be charted.

• year_max – int; the maximum calendar year of data to be charted.

• args – str(s); the data attributes to be charted.

Returns:

A single chart saved to the destination folder.

line_chart_arg_by_options(dr, alt_names, year_min, year_max, arg)

This method generates a chart showing the passed argument under each of the passed alternatives.

Parameters:

• dr – Numeric; the discount rate of the data to be charted.

• alt_names – List; contains the OptionNames for which to chart data.

• year_min – int; the minimum calendar year of data to be charted.

• year_max – int; the maximum calendar year of data t be charted.

• arg – str; the single data attribute to be charted.

Returns:

A single chart saved to the destination folder.

create_figures(args)

This method is called by tool_main and then controls the generation of charts by the CreateFigures class.

Parameters:

args – List; attributes to include in figures.

Returns:

Charts are saved to the path_for_save folder by the ChartFigures class and this method returns to tool_main.

4.1.1.4.5. bca_tool_code.general_modules.discounting module

discount_values(settings, data_object)

The discount function determines metrics appropriate for discounting (those contained in data_object dictionary) and does the discounting calculation to a given year and point within that year.

Parameters:

• settings – object; the SetInputs class object.

• data_object – object; the fleet data object.

Returns:

Updates the data_object dictionary with new key, value pairs where keys stipulate the discount rate and monetized values are discounted at the same rate as the discount rate of the input stream of values.

Note

The costs_start entry of the BCA_General_Inputs file should be set to ‘start-year’ or ‘end-year’, where start-year represents costs starting at time t=0 (i.e., first year costs are undiscounted), and end-year represents costs starting at time t=1 (i.e., first year costs are discounted).

discount_value(arg_value, rate, year, discount_to, offset)

Parameters:

• arg_value – Numeric; the value to be discounted.

• rate – Numeric; the discount rate to use.

• year – int; the calendar year associated with arg_value.

• discount_to – int; the calendar year to which to discount the value.

• offset – int; 0 or 1 reflecting whether costs are assumed to occur at the start of the year or the end of the year.

Returns:

A single value representing arg_value discounted to the year discount_to at rate.

4.1.1.4.6. bca_tool_code.general_modules.emission_cost module

calc_criteria_emission_cost(settings, vehicle)

Parameters:

• settings – object; the SetInputs class object.

• vehicle – object; an object of the Vehicle class.

Returns:

An update_dict for use in updating the cost results dictionary.

Note

This function is not being used so may not work properly.

calc_ghg_emission_cost(settings, vehicle)

Parameters:

• settings – object; the SetInputs class object.

• vehicle – object; an object of the Vehicle class.

Returns:

An update_dict for use in updating the cost results dictionary.

Note

This function is not being used so may not work properly.

4.1.1.4.7. bca_tool_code.general_modules.emission_reduction module

calc_nox_reduction(settings, vehicle)

Parameters:

• settings – object; the SetInputs class object.

• vehicle – object; an object of the Vehicle class.

Returns:

The NOx reduction for the passed vehicle.

Note

The nox_reduction calculation should be done such that it is positive if action has lower nox than no action.

calc_thc_reduction(settings, vehicle)

Parameters:

• settings – object; the SetInputs class object.

• vehicle – object; an object of the Vehicle class.

Returns:

The THC reduction for the given vehicle object.

Note

The thc_reduction calculation should be done such that it is positive if action has lower thc than no action.

4.1.1.4.8. bca_tool_code.general_modules.estimated_age_at_event module

class EstimatedAge

Bases: object

__init__()

calc_estimated_age(settings, vehicle)

Parameters:

• settings – object; the SetInputs class object.

• vehicle – object; an object of the Vehicle class.

Returns:

Updates the estimated ages dictionary with the ages at which an event (e.g., warranty, useful life) will be reached for the given vehicle.

get_attribute_value(key, attribute_name)

Parameters:

• key – tuple; the object dictionary key (i.e., vehicle_id, option_id, modelyear_id, identifier) where identifier would be ‘Warranty’ or ‘UsefulLife’.

• attribute_name – str; The name of the attribute for which a value is sought.

Returns:

The value associated with attribute_name.

4.1.1.4.9. bca_tool_code.general_modules.fleet module

class Fleet

Bases: object

__init__()

create_vehicles(no_action_alt, options)

Parameters:

• no_action_alt – int; the no-action option_id number.

• options – object; an object of the Options class.

Returns:

Nothing but it creates vehicle objects and lists of vehicle objects.

engine_sales(vehicle)

Parameters:

vehicle – object; an object of the Vehicle class..

Returns:

Nothing, but it updates the sales by start year object dictionary with engine sales data.

cumulative_engine_sales(vehicle, start_year)

Parameters:

• vehicle – object; an object of the Vehicle class.

• start_year – int; the implementation step for which cumulative sales are sought.

Returns:

Nothing, but it updates the sales by start year object dictionary with cumulative engine sales data.

cumulative_vehicle_sales(vehicle, start_year)

Parameters:

• vehicle – object; an object of the Vehicle class.

• start_year – int; the implementation step for which cumulative sales are sought.

Returns:

Nothing, but it updates the sales by start year object dictionary with cumulative vehicle sales data.

Note

This method is not used so may not work properly.

get_typical_vmt_per_year(settings, vehicle)

Parameters:

• settings – object; the SetInputs class object.

• vehicle – object; an object of the Vehicle class.

Returns:

A single typical annual VMT/veh value for the given vehicle.

Note

This function calculates a typical annual VMT/vehicle over a set number of year_ids as set via the General Inputs workbook. This typical annual VMT/vehicle can then be used to estimate the ages at which warranty and useful life will be reached. When insufficient year_ids are available – e.g., if the typical_vmt_thru_ageID is set to >5 year_ids and the given vehicle is a MY2041 vintage vehicle and the fleet input file contains data only thru CY2045, then insufficient data exist to calculate the typical VMT for that vehicle – the typical VMT for that vehicle will be set equal to the last prior MY vintage for which sufficient data were present.

update_object_dict(vehicle, unit, update_dict)

Parameters:

• vehicle – object; an object of the Vehicle class.

• unit – tuple; the unit to use in the key (e.g., engine_id or vehicle_id).

• update_dict – Dictionary; represents the attribute-value pairs to be updated.

Returns:

Updates the object dictionary with each attribute updated with the appropriate value.

Note

The method updates an existing key having attribute_name with attribute_value.

4.1.1.4.10. bca_tool_code.general_modules.sum_by_vehicle module

calc_sum_of_costs(key, data_dict, *args)

Parameters:

• key – tuple; the key of the passed data_dict that contains needed attributes.

• data_dict – dictionary; the data.

• args – str(s); the attributes to be summed.

Returns:

The sum of the passed args.

4.1.1.4.11. bca_tool_code.general_modules.vehicle module

class Vehicle

Bases: object

Define vehicle object attributes.

vehicle_df = Empty DataFrame Columns: [] Index: []

attributes_to_adjust = []

year_id_min = 0

year_id_max = 0

year_ids = 0

__init__()

set_vehicle_id()

Returns:

A tuple denoting the vehicle_id consisting of (sourcetype_id, regclass_id, fueltype_id).

set_engine_id()

Returns:

A tuple denoting the engine_id consisting of (regclass_id, fueltype_id).

set_age_id()

Returns:

The age_id (age) of the vehicle.

get_fueltype_name()

Returns:

The fuel type name for the passed ID.

get_regclass_name()

Returns:

The regclass name for the passed ID.

get_sourcetype_name()

Returns:

The source type name for the passed ID.

init_from_file(filepath, options, adjustments=None)

Parameters:

• filepath – Path to the specified file.

• options – object; an instance of the Options class.

• adjustments – object; an instance of the MovesAdjustments class (if applicable).

Returns:

Reads file at filepath; creates a dictionary and other attributes specified in the class __init__.

get_age0_min_year(df, attribute)

Parameters:

• df – DataFrame; the input data (i.e., the MOVES data).

• attribute – str; the attribute for which the age=0 minimum is sought (e.g., calendar year).

Returns:

A single value representing the minimum value of attribute for which age=0.

define_attributes_to_adjust()

Returns:

Updates the attributes_to_adjust object list.

create_vehicle_df(df, year_min, options, adjustments=None)

Parameters:

• df – DataFrame; the raw fleet input data (e.g., from MOVES).

• year_min – int; the first model year to include in the returned DataFrame.

• options – object; the options class object.

• adjustments – object; the MovesAdjustments class object.

Returns:

A DataFrame of the MOVES inputs with necessary MOVES adjustments made according to the MOVES adjustments input file.

static calc_odometer(df)

Parameters:

df – DataFrame; vehicle level data containing vmt_per_veh information.

Returns:

A pandas Series of odometer data (cumulative vmt_per_vehicle).

static rename_attributes(df)

Parameters:

df – DataFrame; the raw fleet input data (e.g., from MOVES).

Returns:

The passed DataFrame with attributes (headers) renamed according to the method’s rename_dict.

4.1.1.4.12. bca_tool_code.general_modules.weighted_results module

create_weighted_cost_dict(settings, data_object, year_max, destination_dict, arg_to_weight=None, arg_to_weight_by=None)

Parameters::

settings: object; the SetInputs class object.

data_object: object; the fleet data object.

year_id_max: int; the max calendar year of the input data.

destination_dict: Dictionary into which to place results.

arg_to_weight: str; the attribute to be weighted by the arg_to_weight_by argument.

arg_to_weight_by: str; the argument to weight by.

Returns:

Updates the destination_dict dictionary of arguments weighted by the weight_by argument.

Note

This function is not being used. This function weights ‘arg_to_weight’ attributes by the ‘arg_to_weight_by’ attribute. The weighting is limited by the number of year_ids (ages) to be included which is set in the general inputs file. The weighting is also limited to model year_ids for which sufficient data exits to include all of those ages. For example, if the maximum calendar year included in the input data is 2045, and the maximum numbers of ages of data to include for each model year is 9 (which would be 10 year_ids of age since year 1 is age 0) then the maximum model year included will be 2035.