parse

flat_config_folder	Parse config files inside folder into a dict of pandas.DataFrames.
python_mapping	Parse a python mapping and transform into a dict of pandas.DataFrames.
xl_like	pandas.read_excel() convenience wrapper.
xml	Parse xml file into a dict of pandas.DataFrames.
reorder_esm	Reorder the energy system mapping based on the given order.

parse is a tessif module for reading energy system data.

Each function returns a mapping representation the read in data ready to be passed to a mapping2es module to turn it into a ready to simulate energy system model.

In case the stored data representation was designed according to the desired simulation tool, the respective transformation module can be found in transform.mapping2es).

If not designed to – or in case of a more general approach – an abstract data format can be used and then be transformed according to the needs of the desired tool by using one of the transformation engines found in transform.mapping2es.tsf.

tessif.parse.flat_config_folder(folder, timeframe='primary', global_constraints='primary', **kwargs)

Parse config files inside folder into a dict of pandas.DataFrames.

Read in flat mappings in configuration file format and transform them into pandas.DataFrame objects keyed by their energy system components (i.e. ‘sources’, ‘busses’, etc..). As well as a pandas.DataFrame object keyed by timeframe.

Parameters:

• folder (Path, str) –

  Path or string representation of a path specifying a folder containing flat mappings in configuration file format

• timeframe (str, default='primary') –

  String specifying which of the (potentially multiple) timeframes passed is to be used. Expected to correspond with section headers.

  One of 'primary', 'secondary', etc… by convention. Designed to be tweaked arbitrarily (e.g. pass 'tf1' if the corresponding section header is named 'tf1')

• global_constraints (str, default='primary') –

  String specifying which of the (potentially multiple) set of constraints passed is to be used. Expected to correspond with section headers.

  One of 'primary', 'secondary', etc… by convention. Designed to be tweaked arbitrarily (e.g. pass 'global_constraints_1' if the corresponding section header is named 'global_constraints_1')

• kwargs –

  Warning

  Not implemented yet.

Returns:

mapping – of DataFrames to their energy system component identifier (‘sources’, ‘storages’ etc..) As well as a singular DataFrame mapped to timeframe.

Return type:

Mapping

Note

For more on flat config data formats see Flat Configuration Files

Example

Read in tessif’s fully parameterized working example in flat configuration file format:

>>> import os
>>> from tessif.frused.paths import example_dir
>>> import tessif.parse as parse
>>> es_dict = parse.flat_config_folder(
...     folder=os.path.join(example_dir, 'data', 'tsf',
...                         'cfg', 'flat', 'basic'))
>>> print(type(es_dict))
<class 'collections.OrderedDict'>

tessif.parse.python_file(path)

Import a python file from path using python.

tessif.parse.python_mapping(mapping, timeframe='primary', global_constraints='primary', **kwargs)

Parse a python mapping and transform into a dict of pandas.DataFrames.

(with the exception of the global_constraints mapping, which is preserved as mapping)

Read in a nested mapping in pure python and transform it into pandas.DataFrame objects keyed by their energy system components (i.e. ‘sources’, ‘busses’, etc..). As well as a pandas.DataFrame object keyed by timeframe.

Parameters:

• mapping (dict) – Nested mapping in pure python representing an energy system.

• timeframe (str, default='primary') –

  String specifying which of the (potentially multiple) timeframes passed is to be used. Expected to correspond with sublevel keys.

  One of 'primary', 'secondary', etc… by convention. Designed to be tweaked arbitrarily (e.g. pass 'tf1' if the corresponding sublevel key is named 'tf1')

• global_constraints (str, default='primary') –

  String specifying which of the (potentially multiple) set of constraints passed is to be used. Expected to correspond with provided sublevel keys

  One of 'primary', 'secondary', etc… by convention. Designed to be tweaked arbitrarily (e.g. pass 'global_constraints_1' if the corresponding sublevel key is named 'global_constraints_1')

• kwargs –

  Warning

  Not implemented yet.

Returns:

mapping – of DataFrames to their energy system component identifier (‘sources’, ‘storages’ etc..) As well as a singular DataFrame mapped to timeframe.

Return type:

Mapping

Note

For more on pure python mapping data formats see Pure Python Mappings

Example

Folowing example illustrates how a pure nested python mapping is transformed into string keyed DataFrame objects (with the exception of the global_constraints mapping).

>>> from tessif.examples.data.tsf.py_mapping import fpwe as fpwe
>>> import tessif.parse as parse
>>> mapping = parse.python_mapping(fpwe.mapping)
>>> for nested_mapping in mapping.values():
...     print(type(nested_mapping))
<class 'pandas.core.frame.DataFrame'>
<class 'pandas.core.frame.DataFrame'>
<class 'pandas.core.frame.DataFrame'>
<class 'pandas.core.frame.DataFrame'>
<class 'pandas.core.frame.DataFrame'>
<class 'pandas.core.frame.DataFrame'>
<class 'dict'>

tessif.parse.xl_like(io, timeframe='primary', global_constraints='primary', **kwargs)

pandas.read_excel() convenience wrapper.

Reads in spreadsheet datatypes and returns a respective dictionairy. Defaults are tweaked to allow this function to be used as only providing a path to the file in xl_like.io for most of its use cases.

Parameters:

• io (str, ExcelFile, xlrd.Book, path object or file-like object) –

  Any valid string path is acceptable. The string could be a URL. Valid URL schemes include http, ftp, s3, and file. For file URLs, a host is expected. A local file could be: file://localhost/path/to/table.xlsx.

  If you want to pass in a path object, pandas accepts any os.PathLike.

  By file-like object, we refer to objects with a read() method, such as a file handler (e.g. via builtin open function) or StringIO.

• timeframe (str, default='primary') –

  String specifying which of the (potentially multiple) timeframes passed is to be used. Expected to correspond with spreadsheet column headers of the ‘timeframe’ data sheet.

  One of 'primary', 'secondary', etc… by convention. Designed to be tweaked arbitrarily (e.g. pass 'tf1' if the corresponding column header is 'tf1')

• global_constraints (str, default='primary') –

  String specifying which of the (potentially multiple) set of constraints passed is to be used. Expected to correspond with spreadsheet column headers of the ‘global_constraints’ data sheet.

  One of 'primary', 'secondary', etc… by convention. Designed to be tweaked arbitrarily (e.g. pass 'global_constraints_1' if the corresponding column header is named 'global_constraints_1')

• sheet_name (str, int, list, None, default=0) –

  Strings are used for sheet names. Integers are used in zero-indexed sheet positions. Lists of strings/integers are used to request multiple sheets. Specify None to get all sheets. Available cases:

  • Defaults to 0: 1st sheet as a DataFrame

  • 1: 2nd sheet as a DataFrame

  • "Sheet1": Load sheet with name “Sheet1”

  • [0, 1, "Sheet5"]: Load first, second and sheet named “Sheet5” as a dict of DataFrame

  • None: All sheets.

• skiprows (list-like) – Rows to skip at the beginning (0-indexed).

• kwargs – Key word arguments are passed to pandas.read_excel()

Returns:

mapping – of DataFrames to their energy system component identifier (‘sources’, ‘storages’ etc..) As well as a singular DataFrame mapped to timeframe.

Return type:

Mapping

Note

If you want to read in open datatypes formats use engine='odf'.

Examples

Change spellings logging level used by spellings.get_from to debug for decluttering output:

>>> import tessif.frused.configurations as configurations
>>> configurations.spellings_logging_level = 'debug'

Read in tessif’s oemof standard energy system model as an excel spreadsheet:

>>> import os
>>> from tessif.frused.paths import example_dir
>>> import tessif.parse as parse
>>> es_dict = parse.xl_like(
...     io=os.path.join(
...         example_dir, 'data', 'omf', 'xlsx', 'energy_system.xlsx'))
>>> print(type(es_dict))
<class 'dict'>

Read in tessif’s oemof standard energy system model as an Open Documents spreadsheet:

>>> import os
>>> from tessif.frused.paths import example_dir
>>> import tessif.parse as parse
>>> es_dict = parse.xl_like(
...     io=os.path.join(
...         example_dir, 'data', 'omf', 'xlsx', 'energy_system.ods'),
...     engine='odf')
>>> print(type(es_dict))
<class 'dict'>

tessif.parse.xml(path, timeframe='primary', global_constraints='primary', **kwargs)

Parse xml file into a dict of pandas.DataFrames.

Read in mappings in xml format and transform them into pandas.DataFrame objects keyed by their energy system components (i.e. ‘sources’, ‘busses’, etc..). As well as a pandas.DataFrame object keyed by timeframe.

Parameters:

• path (Path, str) – Path or string representation of a path specifying an xml file containing energy system mappings

• timeframe (str, default='primary') –

  String specifying which of the (potentially multiple) timeframes passed is to be used. Expected to correspond with child elements of the ‘timeframe’ element of the xml file.

  One of 'primary', 'secondary', etc… by convention. Designed to be tweaked arbitrarily (e.g. pass 'tf1' if the corresponding element is named 'tf1')

• global_constraints (str, default='primary') –

  String specifying which of the (potentially multiple) set of constraints passed is to be used. Expected to correspond with child elements of the ‘global_constraints’ element of the xml file.

  One of 'primary', 'secondary', etc… by convention. Designed to be tweaked arbitrarily (e.g. pass 'gc1' if the corresponding element is named 'gc1')

• kwargs –

  Warning

  Not implemented yet.

Returns:

mapping – of DataFrames to their energy system component identifier (‘sources’, ‘storages’ etc..) As well as a singular DataFrame mapped to timeframe.

Return type:

Mapping

Note

For more on xml see .xml

Example

Read in tessif’s fully parameterized working example in xml format:

>>> import os
>>> from tessif.frused.paths import example_dir
>>> import tessif.parse as parse
>>> es_dict = parse.xml(
...     path=os.path.join(example_dir, 'data', 'tsf', 'xml', 'fpwe.xml'))
>>> print(type(es_dict))
<class 'collections.OrderedDict'>

tessif.parse.hdf5(path, timeframe='primary', global_constraints='primary', **kwargs)

Parse hdf5 file into a dict of pandas.DataFrames.

Read in mappings in hdf5 format and transform them into pandas.DataFrame objects keyed by their energy system components (i.e. ‘sources’, ‘busses’, etc..). As well as a pandas.DataFrame object keyed by timeframe.

Parameters:

• path (Path, str) – Path or string representation of a path specifying a hdf5 file containing energy system mappings

• timeframe (str, default='primary') –

  String specifying which of the (potentially multiple) timeframes passed is to be used. Expected to correspond with subgroups of the ‘timeframe’ group of the hdf5 file.

  One of 'primary', 'secondary', etc… by convention. Designed to be tweaked arbitrarily (e.g. pass 'tf1' if the corresponding group is named 'tf1')

• global_constraints (str, default='primary') –

  String specifying which of the (potentially multiple) set of constraints passed is to be used. Expected to correspond with subgroups of the ‘timeframe’ group of the hdf5 file.

  One of 'primary', 'secondary', etc… by convention. Designed to be tweaked arbitrarily (e.g. pass 'gc1' if the corresponding group is named 'gc1')

• kwargs –

  Warning

  Not implemented yet.

Returns:

mapping – of DataFrames to their energy system component identifier (‘sources’, ‘storages’ etc..) As well as a singular DataFrame mapped to timeframe.

Return type:

Mapping

Note

For more on hdf5 see .hdf5

Example

Read in tessif’s fully parameterized working example in hdf5 format:

>>> import os
>>> from tessif.frused.paths import example_dir
>>> import tessif.parse as parse
>>> es_dict = parse.hdf5(
...     path=os.path.join(
...     example_dir, 'data', 'tsf', 'hdf5', 'fpwe.hdf5'))
>>> print(type(es_dict))
<class 'collections.OrderedDict'>

tessif.parse.reorder_esm(esm, order=None)

Reorder the energy system mapping based on the given order.

Design case is to reorder the energy system mapping, so that every energy system component is mappped to its respective identifier. (i.e all sources are mapped to 'source').

Parameters:

• esm (Mapping) – Mapping of which the keys are to be changes.

• order (Mapping, None, dflt=None) –

  Mapping of which the keys are used to reorder the esm. Whereas the values are used to identify which original keys of the esm belong to which new key. Meaning if the old key (i.e import) is to be found in one of the order mapping (i.e. {'sink': 'import', 'commodity'} values, it is replaced (i.e 'sink' in this case).

  If None is used (the default) tesssif.frused.registered_component_types is used as order mapping. (Which is it’s design case)

Example

Change spellings logging level used by spellings.get_from to debug for decluttering output:

>>> import tessif.frused.configurations as configurations
>>> configurations.spellings_logging_level = 'debug'

Reading in the oemof default example and order the energy system mapping according to tessif’s convention

>>> import tessif.parse as parse
>>> import os
>>> from tessif.frused.paths import example_dir
>>> esm = parse.xl_like(
...     io=os.path.join(
...     example_dir, 'data', 'omf', 'xlsx', 'energy_system.xlsx'))

The unordered energy system mapping:

>>> for key in esm.keys():
...     print(key)
Info
Grid
Renewable
Demand
Commodity
mimo_transformers
global_constraints
timeframe

The reordered energy system mapping:

>>> esm = parse.reorder_esm(esm)
>>> for key in esm.keys():
...     print(key)
bus
sink
source
transformer
timeframe