def clim_converter(input_dict, res_convert_array, com_convert_array):
"""Convert input data dict from a census division to a climate zone basis.
This function principally serves to prepare the inputs for, and
then call, a function that performs the calculations to convert
data in the input_dict database specified for each microsegment
from a census division to climate zone basis.
Args:
input_dict (dict): Data from JSON database, as imported,
on a census division basis.
res_convert_array (numpy.ndarray): An array of census
division to climate zone conversion factors for
residential building types.
com_convert_array (numpy.ndarray): Array of census
division to climate zone conversion factors for
commercial building types.
Returns:
A complete dict with the same structure as input_dict,
except at the top level, where census division keys
have been replaced by climate zone keys, and the data
have been updated to correspond to those climate zones.
"""
# Create an instance of the CommercialTranslationDicts object from
# com_mseg, which contains a dict that translates census division
# strings into the corresponding integer codes
cd = cm.CommercialTranslationDicts()
# Obtain list of all climate zone names as strings
cz_list = res_convert_array.dtype.names[1:]
# Obtain list of all census divisions in the input data
cd_list = list(input_dict.keys())
# Set up empty dict to be updated with the results for each climate
# zone as the data are converted
converted_dict = {}
# Add the values from each climate zone to the converted_dict
for cz_number, cz_name in enumerate(cz_list):
# Create a copy of the input dict at the level below a census
# division or climate zone (the structure below that level
# should be identical); uses the first census division in
# cd_list each time
base_dict = copy.deepcopy(input_dict[cd_list[0]])
# Loop through all census divisions to add their contributions
# to each climate zone
for cd_name in cd_list:
# Proceed only if the census division name is found in
# the dict specified in this function, otherwise raise
# a KeyError
if cd_name in cd.cdivdict.keys():
# Obtain the census division number from the dict
# and subtract 1 to make the number usable as a list
# index (1st list element is indexed by 0 in Python)
cd_number = cd.cdivdict[cd_name] - 1
# Make a copy of the portion of the input dict
# corresponding to the current census division
add_dict = copy.deepcopy(input_dict[cd_name])
# Call the merge_sum function to replace base_dict with
# updated contents; add 1 to the climate zone number
# because it will be used as a column index for an
# array where the first column of data are in the
# second column (indexed as 1 in Python); this approach
# overwrites base_dict, which is intentional because it
# is the master dict that stores the data on a climate
# zone basis as the contribution from each census
# division is added to the climate zone by merge_sum
base_dict = merge_sum(base_dict, add_dict, cd_number,
(cz_number + 1), cd.cdivdict, cd_list,
res_convert_array, com_convert_array)
else:
raise(KeyError("Census division name not found in dict keys!"))
# Once fully updated with the data from all census divisions,
# write the resulting data to a new variable and update the
# master dict with the data using the appropriate census
# division string name as the key
newadd = base_dict
converted_dict.update({cz_name: newadd})
return converted_dict
def env_cpl_data_handler(cpl_data, conversions, years, key_list):
"""Restructure envelope component cost, performance, and lifetime data.
This function extracts the cost, performance, and lifetime data for
the envelope components of residential and commercial buildings
from the original data and restructures it into a form that is
generally consistent with similar data originally obtained from
the Annual Energy Outlook (AEO). These data are added to the input
microsegments database after it is converted to a climate zone
basis, since these data are already reported by climate zone (if
the data for a given envelope component are climate-specific).
Args:
cpl_data (dict): Cost, performance, and lifetime data for
building envelope components (e.g., roofs, walls) including
units and source information.
conversions (dict): Cost unit conversions for envelope (and
heating and cooling equipment, though those conversions are
not used in this function) components, as well as the
mapping from EnergyPlus building prototypes to AEO building
types (as used in the microsegments file) to convert cost
data from sources that use the EnergyPlus building types
to the AEO building types.
years (list): A list of integers representing the range of years
in the data.
key_list (list): Keys that specify the current location in the
microsegments database structure and thus indicate what
data should be returned by this function.
Returns:
A dict with installed cost, performance, and lifetime data
applicable to the microsegment and envelope component specified
by key_list, as well as units and source information for those
data. All costs should have the units 2016$/ft^2 floor. Note
that unlike the cost, performance, and lifetime data obtained
from the AEO, these data are not specified on a yearly basis.
These data are returned only if applicable for the envelope
component that appears in key_list, and not for cases such as
"people gain" for which there is no corresponding product that
is part of the building.
"""
# Preallocate variables for the building class (i.e., residential
# or commercial) and the building type
bldg_class = ''
bldg_type = ''
# Loop through the keys specifying the current microsegment to
# determine the building type, whether the building is residential
# or commercial, and identify the climate zone
for entry in key_list:
# Identify the building type and thus determine the building class
if entry in mseg.bldgtypedict.keys():
bldg_class = 'residential'
bldg_type = entry
elif entry in cm.CommercialTranslationDicts().bldgtypedict.keys():
bldg_class = 'commercial'
bldg_type = entry
# Identify and record the climate zone
if entry in ['AIA_CZ1', 'AIA_CZ2', 'AIA_CZ3', 'AIA_CZ4', 'AIA_CZ5']:
cz_int = entry
# Some envelope components are reported as two or more words, but
# the first word is often the required word to select the relevant
# cost, performance, and lifetime data, thus it is helpful to split
# the envelope component key string into a list of words
envelope_type = key_list[-1].split()
# Use the first word in the list of strings for the envelope name
# to determine whether data are available cost, performance, and
# lifetime data and, if so, record those data (specified for the
# correct building class) to a new variable
specific_cpl_data = ''
if envelope_type[0] in cpl_data['envelope'].keys():
specific_cpl_data = cpl_data['envelope'][envelope_type[0]][bldg_class]
# Preallocate empty dicts for the cost, performance, and lifetime
# data, to include the data, units, and source information
the_cost = {}
the_perf = {}
the_life = {}
# If any data were found for the particular envelope type and
# building class, extract the cost, performance, and lifetime data,
# including units and source information, and record it to the
# appropriate dict created for those data
if specific_cpl_data:
# Extract cost data units, if available (since some envelope
# components might have costs reported without a dict structure)
try:
orig_cost_units = specific_cpl_data['cost']['units']
except TypeError:
orig_cost_units = None
# Obtain and record the cost data in the preallocated dict,
# starting with cases where the cost units require conversion
# to be on the desired common basis of '2016$/ft^2 floor'
if orig_cost_units and orig_cost_units != '2016$/ft^2 floor':
# Extract the current cost value
orig_cost = specific_cpl_data['cost']['typical']
# Use the cost conversion function to obtain the costs
# for the current envelope component
adj_cost, adj_cost_units = cost_converter(orig_cost,
orig_cost_units,
bldg_class, bldg_type,
conversions)
# Add the cost information to the appropriate dict,
# constructing the cost data itself into a structure with
# a value reported for each year
the_cost['typical'] = {str(yr): adj_cost for yr in years}
the_cost['units'] = adj_cost_units
the_cost['source'] = specific_cpl_data['cost']['source']
# If cost units are reported but the units indicate that there
# is no need for conversion, shift the data to a per year
# basis but carry over the units and source information
elif orig_cost_units:
the_cost['typical'] = {str(yr):
specific_cpl_data['cost']['typical']
for yr in years}
the_cost['units'] = orig_cost_units
the_cost['source'] = specific_cpl_data['cost']['source']
# Output the cost data as-is for for cases where no cost
# data are reported (i.e., orig_cost_units == None)
else:
the_cost = specific_cpl_data['cost']
# Obtain the performance data depending on whether or not a
# second word appears in the envelope_type list, as with
# 'windows conduction' and 'windows solar'; other types that
# will have two or more entries in the envelope_type list
# include people gain, equipment gain, other heat gain, and
# lighting gain
if len(envelope_type) > 1:
# For windows data, the performance data are specified by
# 'solar' or 'conduction'; the other envelope types that
# are not relevant will be ignored per this if statement
if envelope_type[1] in specific_cpl_data['performance'].keys():
# Simplify the cost, performance, lifetime dict to only
# the relevant performance data (this step shortens later
# lines of code to make it easier to comply with the PEP 8
# line length requirement)
env_s_data = specific_cpl_data['performance'][envelope_type[1]]
# Extract the performance value, first trying for if it
# is specified to the climate zone level
try:
perf_val = env_s_data['typical'][cz_int]
except KeyError:
perf_val = env_s_data['typical']
# Add the units and source information to the dict
# (note that this step can't move outside this if
# statement because these data are in a different
# location for this case where the performance
# specification is more detailed)
the_perf['units'] = env_s_data['units']
the_perf['source'] = env_s_data['source']
# For the cases where the performance data are accessible from
# the existing cost, performance, and lifetime data dict without
# providing further levels of specificity
else:
# Extract the performance value, first trying for if
# the value is broken out by vintage
try:
perf_val = [
specific_cpl_data['performance']['typical']['new'],
specific_cpl_data['performance']['typical']['existing']]
# Try for if the value is further broken out by climate
try:
perf_val = [x[cz_int] for x in perf_val]
except TypeError:
pass
except KeyError:
# Try for if the value is broken out by climate
try:
perf_val = specific_cpl_data['performance']['typical'][
cz_int]
except TypeError:
perf_val = specific_cpl_data['performance']['typical']
the_perf['units'] = specific_cpl_data['performance']['units']
the_perf['source'] = specific_cpl_data['performance']['source']
# Record the performance value identified in the above rigmarole
# Case where the performance value is not broken out by vintage
if type(perf_val) is not list:
# Note: the dict comprehension handles cases where the
# performance value is further broken out by year; if the value
# is not broken out by year, the comprehension assumes the same
# performance value for all years in the analysis time horizon
the_perf['typical'] = {
str(yr): perf_val[str(yr)] if type(perf_val) is dict
else perf_val for yr in years}
# Case where the performance value is broken out by vintage
else:
# Note: the dict comprehension handles cases where the
# performance value is further broken out by year; if the value
# is not broken out by year, the comprehension assumes the same
# performance value for all years in the analysis time horizon
the_perf['typical'] = {
'new': {
str(yr): perf_val[0][str(yr)] if type(perf_val[0]) is dict
else perf_val[0] for yr in years},
'existing': {
str(yr): perf_val[1][str(yr)] if type(perf_val[1]) is dict
else perf_val[1] for yr in years}}
# Transfer the lifetime data as-is (the lifetime data has a
# uniform format across all of the envelope components) except
# for the average, which is updated to be reported by year
the_life['average'] = {str(yr):
specific_cpl_data['lifetime']['average']
for yr in years}
the_life['range'] = specific_cpl_data['lifetime']['range']
the_life['units'] = specific_cpl_data['lifetime']['units']
the_life['source'] = specific_cpl_data['lifetime']['source']
# Add the cost, performance, and lifetime dicts into a master dict
# for the microsegment and envelope component specified by key_list
tech_data_dict = {'installed cost': the_cost,
'performance': the_perf,
'lifetime': the_life}
# If the building type is residential, add envelope component
# consumer choice parameters for each year in the modeling time
# horizon (these parameters are based on AEO consumer choice
# data for the residential heating and cooling end uses in
# 'rsmeqp.txt')
if bldg_class == 'residential':
tech_data_dict['consumer choice'] = {
'competed market share': {
'parameters': {'b1': {str(yr): -0.003 for yr in years},
'b2': {str(yr): -0.012 for yr in years}},
'source': ('EIA AEO choice model parameters for heating' +
' and cooling equipment')
}
}
# If no data were found, which is expected for envelope components
# that are not representative of building products (e.g., people
# gain, equipment gain), simply return 0
else:
tech_data_dict = 0
return tech_data_dict
def merge_sum(base_dict, add_dict, cd, cz, cd_dict, cd_list,
res_convert_array, com_convert_array, cd_to_cz_factor=0):
"""Calculate values to restructure census division data to climate zones.
Two dicts with identical structure, 'base_dict' and 'add_dict' are
passed to this function and manipulated to effect conversion of the
data from a census division (specified by 'cd') to a climate zone
(specified by 'cz') basis.
This function operates recursively, traversing the structure of
the input dicts until a list of years is reached. At that point,
if the census division specified corresponds to the first census
division in the original data (the order is obtained from
'cd_list'), the entries in 'base_dict' are overwritten by the same
data multiplied by the appropriate conversion factor. If the census
division is not the first to appear in the original data,
'base_dict' has already been modified, and data from subsequent
census divisions should be added to 'base_dict', thus 'add_dict' is
modified to the current climate zone using the appropriate
conversion factor and added to 'base_dict'.
This approach to converting the data to a climate zone basis works
because this function is called from within nested for loops that
cover all of the census divisions for each climate zone.
Consequently, the data from each of the census divisions converted
to their respective contributions to a single climate zone can be
added together to obtain the data in the desired final form.
Args:
base_dict (dict): A portion of the input JSON database
corresponding to the current census division, modified in
place to convert the data to a climate zone basis.
add_dict (dict): A portion of the input JSON database
corresponding to the current census division, copied from
the original input data each time this function is called
by the clim_converter function. This portion of the data
should be structurally identical to 'base_dict', and
(generally) corresponds to the data that should be updated
and then added to 'base_dict'.
cd (int): The census division (1-9) currently being processed.
Used as an array row index, so the actual values begin
with 0, not 1.
cz (int): The climate zone to which the census division data
are being added. Used as an array column index where the
first (0th) column is not relevant, thus it begins at 1.
cd_dict (dict): A dict for translating between census division
descriptive strings and their corresponding numeric codes.
cd_list (list): A list of the census divisions that are in the
input data (the top level keys from the JSON structure),
in the order in which they appear.
res_convert_array (numpy.ndarray): Coefficients for converting
from census divisions to climate zones for residential buildings.
com_convert_array (numpy.ndarray): Coefficients for converting
from census divisions to climate zones for commercial buildings.
cd_to_cz_factor (float): The numeric conversion factor to
calculate the contribution from the current census division
'cd' to the current climate zone 'cz'.
Returns:
A dict with the same form as base_dict and add_dict, with the
values for the particular census division specified in 'cd'
converted to the climate zone 'cz'.
"""
# Extract lists of strings corresponding to the residential and
# commercial building types used to process these inputs
res_bldg_types = list(mseg.bldgtypedict.keys())
com_bldg_types = list(cm.CommercialTranslationDicts().bldgtypedict.keys())
for (k, i), (k2, i2) in zip(sorted(base_dict.items()),
sorted(add_dict.items())):
# Compare the top level/parent keys of the section of the dict
# currently being parsed to ensure that both the base_dict
# (census division basis) and add_dict (climate zone basis)
# are proceeding with the same structure
if k == k2:
# Identify appropriate census division to climate zone
# conversion weighting factor as a function of building type;
# k and k2 correspond to the current top level/parent key,
# thus k and k2 are equal to a building type immediately
# prior to traversing the entire child tree for that
# building type, for which the conversion number
# cd_to_cz_factor will be the same
if k in res_bldg_types or k in com_bldg_types:
if k in res_bldg_types:
cd_to_cz_factor = res_convert_array[cd][cz]
elif k in com_bldg_types:
cd_to_cz_factor = com_convert_array[cd][cz]
# Recursively loop through both dicts
if isinstance(i, dict):
merge_sum(i, i2, cd, cz, cd_dict, cd_list, res_convert_array,
com_convert_array, cd_to_cz_factor)
elif type(base_dict[k]) is not str:
# Special handling of first dict (no addition of the
# second dict, only conversion of the first dict with
# the appropriate factor)
if (cd == (cd_dict[cd_list[0]] - 1)):
# In the special case of consumer choice/time
# preference premium data, the data are reported
# as a list and must be reprocessed using a list
# comprehension (or comparable looping approach)
if isinstance(base_dict[k], list):
base_dict[k] = [z*cd_to_cz_factor for z
in base_dict[k]]
else:
base_dict[k] = base_dict[k]*cd_to_cz_factor
else:
if isinstance(base_dict[k], list):
base_dict[k] = [sum(y) for y
in zip(base_dict[k],
[z*cd_to_cz_factor for z
in add_dict[k2]])]
else:
base_dict[k] = (base_dict[k] +
add_dict[k2]*cd_to_cz_factor)
else:
raise(KeyError('Merge keys do not match!'))
# Return a single dict representing sum of values of original two dicts
return base_dict