input_modification#

Functions:

`check_for_meta_module`(key)	Checks if key is a meta module that is to be executed.
`convert_dict_to_kwargs_dict`(dictionary[, ...])	Converting dictionary generated by `convert_file_to_dictionary()` to a dictionary that can be used to provide keyword arguments.
`convert_file_to_dictionary`(file)	Convert provided text file into dictionary.
`convert_input_to_dictionary`(file[, default, ...])	Reads provided input file (file) and default file, converting both to dictionaries.
`execute_plugin`(plugin_name, plugs_dict[, ...])	Executing module.
`file_import`(file_name[, mode, return_path])	Importing package file or file at arbitrary path and returning typing.TextIO instance.
`get_by_path`(root, items)	Access a nested object in root by item sequence.
`import_plugin`(plugin_name, plugin_module)	Importing module.
`insert`(class_object, top_key, middle_key, ...)	Insert function used in plugins.
`merge`(a, b[, path, update])	Deep merge two dictionaries, with b having priority over a
`num`(s)	Converting string to either an int, float, or, if neither is possible, returning the string.
`parse_parameter`(key[, delimiter])	Provided key is split at delimiter(s) and returned as cleaned array
`parse_parameter_to_array`(key[, delimiter, ...])	parse_parameter() is applied to key string and result is converted to num and returned in ndarray
`process_cell`(dictionary, top_key, key, ...)	Processing of a single cell at dictionary[top_key][key][bottom_key]
`process_input`(dictionary, top_key, key, ...)	Processing of input at dictionary[top_key][key][bottom_key].
`process_path`(dictionary, path, top_key, key, ...)	Processing provided path.
`process_table`(dictionary, top_key, bottom_key)	Looping through all keys in dictionary[top_key] and applying process_input to dictionary[top_key][key][bottom_key].
`read_textfile`(file_name, delimiter[, mode])	Wrapper for genfromtxt with lru_cache for repeated reads of the same file.
`reverse_parameter_to_string`(parameter)	Reverts processed parameter list to string.
`set_by_path`(root, items, value[, value_type])	Set a value in a nested object in root by item sequence.
`sum_all_tables`(dictionary, table_group, ...)	Applies `sum_table()` to all dictionary entries with a key that contains table_group.
`sum_table`(dictionary, top_key, bottom_key[, ...])	For the provided dictionary, all entries in dictionary[top_key] are processed using `process_input()` (positions: top_key > key > bottom key) and summed.

pyH2A.Utilities.input_modification.check_for_meta_module(key)[source]#

Checks if key is a meta module that is to be executed.

Notes

Meta module is identified by checking if key contains the substring ‘Analysis’ and does not contain any of the substrings in exceptions.

pyH2A.Utilities.input_modification.convert_dict_to_kwargs_dict(dictionary, middle_key='Value')[source]#

Converting dictionary generated by convert_file_to_dictionary() to a dictionary that can be used to provide keyword arguments.

Parameters

dictionarydict: Dictionary to be converted.
middle_keystr, optional: Middle key which is present in input dictionary. This key is removed in the process.

Returns

outputdict: Dictionary suitable to provide keyword arguments.

pyH2A.Utilities.input_modification.convert_file_to_dictionary(file)[source]#

Convert provided text file into dictionary. Text file has to follow GitHub flavoured Markdown style.

Parameters

filetyping.TextIO: typing.TextIO instance of file to be converted.

Returns

inpdict: Dictionary containing converted data from file.

Notes

Table format:

# Table A name

First | Second | …

— | — | —

Entry A | value 1 | …

Entry B | value 2 | …

# Table B name

…

The table name is used as top_key, the entries within the first column are used as middle_key and the names of the other columns are used as bottom key. E.g. {‘Table A name’: {‘Entry A’ : {‘Second’: ‘value 1’}}}

pyH2A.Utilities.input_modification.convert_input_to_dictionary(file, default='pyH2A.Config~Defaults.md', merge_default=True)[source]#

Reads provided input file (file) and default file, converting both to dictionaries. The dictionaries are merged, with the input file having priority.

Parameters

filestr: Path to input file.
defaultstr, optional: Path to default file.
merge_defaultbool: Flag to control if input is merged with default file.

Returns

inpdict: Input dictionary.

pyH2A.Utilities.input_modification.execute_plugin(plugin_name, plugs_dict, plugin_module=True, nested_dictionary=False, **kwargs)[source]#

Executing module.

Parameters

plugin_namestr: Name of module.
plugs_dictdict: Dictionary to store class object generated from module.
plugin_modulebool, optional: Flag to differentiate between plugins and analysis modules. If True, module is imported from Plugins. directory. If False, it is imported from Analysis. directory.
nested_dictioanrybool, optional: If True, a sub dictionary is created in plugs_dict, where the class object is stored.
**kwargs:: Keyword arguments passed to class within module.

Returns

plugin_object:: Class objected generated from module.

Notes

Module plugin_name is imported. It is assumed that the module contains a class with the same name as plugin_name. An instance of this class is created using **kwargs. The class object is then stored in plugs_dict.

pyH2A.Utilities.input_modification.file_import(file_name, mode='rb', return_path=False)[source]#

Importing package file or file at arbitrary path and returning typing.TextIO instance.

Parameters

file_namestr: Path to file to be read. Can be either a regular path or a path of the form package.subdirectory~file_name to refer to a file in the pyH2A installation.
modestr: Mode for file read. Can be either r or rb. In case of r, a typing.TextIO instance is returned. In case of rb a typing.BinaryIO instance is returned.

Returns

outputtyping.BinaryIO or typing.TextIO instance: Whether a typing.BinaryIO or typing.TextIO is returned depends on mode.

pyH2A.Utilities.input_modification.get_by_path(root, items)[source]#: Access a nested object in root by item sequence.

pyH2A.Utilities.input_modification.import_plugin(plugin_name, plugin_module)[source]#

Importing module.

Parameters

plugin_namestr: Name of module.
plugin_modulebool, optional: Flag to differentiate between plugins and analysis modules. If True, module is imported from Plugins. directory. If False, it is imported from Analysis. directory.

Returns

plugin_class:: Class from imported module.

Notes

Module plugin_name is imported. It is assumed that the module contains a class with the same name as plugin_name

pyH2A.Utilities.input_modification.insert(class_object, top_key, middle_key, bottom_key, value, name, print_info=True, add_processed=True, insert_path=True)[source]#

Insert function used in plugins.

Parameters

class_object: Discounted_Cash_Flow object: Dicounted_Cash_Flow object with .inp attribute, which is modified.
top_keystr: Top key.
middle_keystr: Middle key.
bottom_keystr: Bottom key.
Valueint, float, str or ndarray: Value inserted at top_key > middle_key > bottom_key position.
namestr: Name of plugin performing insertion.
print_infobool, optional: Flag to control if information on action of insert() is printed.
add_processedbool, optional: Flag to control if ‘Processed’ key is added.
insert_pathbool, optional: Flog to control if ‘Path’ key is added.

Notes

inp attribute of class_object is modified by inserting value at the position defined by top_key > middle_key > bottom_key. If there already is a value at this position, it will be overwritten. In this case, the ‘Path’ entry will be set to ‘None’ to avoid issues if value at this position already existed and had a path specified. If there is not already a value at this position, it will be created name is the name of plugin using insert for insertion. If print_info is True, action of insert will be printed.

pyH2A.Utilities.input_modification.merge(a, b, path=None, update=True)[source]#: Deep merge two dictionaries, with b having priority over a

pyH2A.Utilities.input_modification.num(s)[source]#

Converting string to either an int, float, or, if neither is possible, returning the string.

Parameters

sstr: String to be converted to a number.

Returns

numint, float or str: String converted to int, float or str.

Notes

Input strings can contain commas as thousands seperators, which will be removed if the string is otherwise a valid number (float or int). If the input string ends with a “%” sign, it will be converted to a number divided by 100.

pyH2A.Utilities.input_modification.parse_parameter(key, delimiter='>')[source]#: Provided key is split at delimiter(s) and returned as cleaned array

pyH2A.Utilities.input_modification.parse_parameter_to_array(key, delimiter='>', dictionary=None, top_key=None, middle_key=None, bottom_key=None, special_values=[], path=None)[source]#

parse_parameter() is applied to key string and result is converted to num and returned in ndarray

Parameters

keystr: String convert to array.
delimiterstr, optional: Delimiter used in string.
dictionarydict, optional: Dictionary used for lookup.
top_keystr, optional: Top key for lookup.
middle_keystr, optional: Middle key for lookup.
bottom_keystr, optional: Bottom key for lookup.
special_valueslist, optional: If key contains an element of special_values, the value at path is retrieved instead of using the actual value of key.
pathstr, optional: Path for lookup in case special_values is triggered.

Returns

arrayndarray: Output as array.

pyH2A.Utilities.input_modification.process_cell(dictionary, top_key, key, bottom_key, cell=None, print_processing_warning=True)[source]#

Processing of a single cell at dictionary[top_key][key][bottom_key]

Parameters

dictionarydict: Dictionary within which function operates.
top_keystr: Top key.
keystr: Middle key.
bottom_keystr: Bottom key.
cellint, float, str or None: Cell entry.
print_processing_warningbool: Flag to control if a warning is printed when an unprocessed value is being used.

Notes

If cell contains only a number, the contents of that cell are returned. If cell contains a string, but that string is not a path (indicated by absence of “>” symbol), 1 is returned If cell contains a string which is potentially a path, it is processed: Contents of the cell are split at “;” delimiter, separating multiple potential paths. For each potential path, process_path() is applied. The retrieved target value(s) are multiplied and returned. Since value is initated to 1, if none of the paths are valid, simply 1 is returned.

pyH2A.Utilities.input_modification.process_input(dictionary, top_key, key, bottom_key, path_key='Path', add_processed=True)[source]#

Processing of input at dictionary[top_key][key][bottom_key].

Parameters

dictionarydict: Dictionary within which function operates.
top_keystr: Top key.
keystr: Middle key.
bottom_keystr: Bottom key.
path_keystr, optional: Key used for path column. Defaults to ‘Path’.
add_processedbool, optional: Flag to control if Processed key is added

Notes

Action: if there is an entry at dictionary[top_key][key][path_key], process_input() applies process_cell() to dictionary[top_key][key][bottom_key] as well as dictionary[top_key][key][path_key] and multiplies them. The resulting value is returned and placed into dictionary[top_key][key][bottom_key]

Detailed Description:

First, it is checked if that input has already been processed by looking for the “Processed” key. If this is the case, the input is simply returned. If it has not already been processed, it is checked if the input is a string which could not be a path (not containing “>”). In this case the string is simply returned and “Processed” is added.

If neither condition is met, process_cell() is applied. It is then attempted to retrieve dictionary[top_key][key][path_key]. If this entry cannot be retrieved, the process_cell() value of the input is returned,

If this entry can be retrieved, process_cell() is applied to it and the resulting Value is multiplied by the original process_cell() value of the input, updating value.

If the obtained value differs from the original entry, the obtained value is inserted at dictionary[top_key][key][bottom_key] and the original entry is stored in dictionary[top_key][key][former_bottom_key]

At the end, “Processed” is added.

pyH2A.Utilities.input_modification.process_path(dictionary, path, top_key, key, bottom_key, print_processing_warning=True)[source]#

Processing provided path. Checks are performed to see if path is valid.

Parameters

dictionarydict: Dictionary within which function operates.
pathstr: Path.
top_keystr: Top key.
keystr: Middle key.
bottom_keystr: Bottom key.
print_processing_warningbool: Flag to control if a warning is printed when an unprocessed value is being used.

Notes

If provided path contains no “>” symbols, it is not a path and 1 is returned If provided path contains only one “>” symbol, it is not a valid path. A warning is printed and 1 is returned. If provided path contains two “>” symbols, it is potentially a valid path. It is then attempted to retrieve target value. If retrieval attempt is unsuccessful, a warning is printed and 1 is returned. If the path is valid, the target value is retrieved: If the rerieved target value comes from an unprocessed key, a warning is printed. If the retrieved target value is non-numerical, a warning is printed and 1 is returned. If the retrieved target value is numerical, it is returned.

pyH2A.Utilities.input_modification.process_table(dictionary, top_key, bottom_key, path_key='Path')[source]#

Looping through all keys in dictionary[top_key] and applying process_input to dictionary[top_key][key][bottom_key].

Parameters

dictionarydict: Dictionary within which function operates.
top_keystr: Top key.
bottom_keystr, ndarray or list: Bottom key(s).
path_keystr or ndarray, optional: Key(s) used for path column(s). Defaults to ‘Path’.

Notes

bottom_key can also be an array of keys, all of which are processed (in this case, path_key has to be an array of equal length).

pyH2A.Utilities.input_modification.read_textfile(file_name, delimiter, mode='rb', **kwargs)[source]#

Wrapper for genfromtxt with lru_cache for repeated reads of the same file.

Parameters

file_namestr: Path to file.
delimiterstr: Delimiter used in file.
**kwargs:: Keyword arguments passed to numpy.genfromtxt().

Returns

datandarray: Array containing read data.

pyH2A.Utilities.input_modification.reverse_parameter_to_string(parameter)[source]#: Reverts processed parameter list to string.

pyH2A.Utilities.input_modification.set_by_path(root, items, value, value_type='value')[source]#

Set a value in a nested object in root by item sequence.

Notes

Existing value is either multiplied by provided one (value_type = factor) or is replaced by provided one. In-place replacement, should only be used on deep copy of self.inp dictionary

pyH2A.Utilities.input_modification.sum_all_tables(dictionary, table_group, bottom_key, insert_total=False, class_object=None, middle_key_insertion='Summed Total', bottom_key_insertion='Value', print_info=True, path_key='Path', return_contributions=False)[source]#

Applies sum_table() to all dictionary entries with a key that contains table_group. Resulting sum_table() values are summed to return total.

Parameters

dictionarydict: Dictionary within which function operates.
table_groupstr: String to identify table group. If a dictionary key contains the table_group substring it is part of the table group.
bottom_keystr, ndarray or list: Bottom key.
insert_totalbool, optional: If insert_total is True, the total of each table is inserted in the respective table.
class_objectDiscounted_Cash_Flow object: Discounted_Cash_Flow object whose .inp attribute is modified.
middle_key_insertionstr, optional: Middle key used for insertion of total.
bottom_key_insertionstr, optional: Bottom key used for insertion of total.
print_infobool, optional: Flag to control if information on action of insert() is printed.
path_keystr, optional: Key used for path column. Defaults to ‘Path’.
return_contributionsbool, optional: Flag to control if a dictionary with contributions breakdown (for use in cost Cost_Contributions_Analysis module) is returned.

Notes

If insert_total is true, the sum_table() value for a given key is inserted in class_object.inp at key > middle_key_insertion > bottom_key_insertion.

The contributions of each table in table_group are stored in contributions dictionary, which is returned if return_contributions is set to True. Dictionary is structured so that it can be provided to “Cost_Contributions_Analysis” class to generate a cost breakdown plot.

pyH2A.Utilities.input_modification.sum_table(dictionary, top_key, bottom_key, path_key='Path')[source]#

For the provided dictionary, all entries in dictionary[top_key] are processed using process_input() (positions: top_key > key > bottom key) and summed.

Parameters

dictionarydict: Dictionary within which function operates.
top_keystr: Top key.
bottom_keystr, ndarray or list: Bottom key.
path_keystr, optional: Key used for path column. Defaults to ‘Path’.