API Reference

oemof.datapackage.datapackage package

Submodules

oemof.datapackage.datapackage.aggregation module

Module used for aggregation sequences and elements.

oemof.datapackage.datapackage.aggregation.temporal_clustering(datapackage, n, path='/tmp', how='daily')[source]

Creates a new datapackage by aggregating sequences inside the sequence folder of the specified datapackage by clustering n timesteps

Parameters:

datapackage (string) – String of meta data file datapackage.json
n (integer) – Number of clusters
path (string) – Path to directory where the aggregated datapackage is stored
how (string) – How to cluster ‘daily’ or ‘hourly’

oemof.datapackage.datapackage.aggregation.temporal_skip(datapackage, n, path='/tmp', name=None, *args)[source]

Creates a new datapackage by aggregating sequences inside the sequence folder of the specified datapackage by skipping n timesteps

Parameters:

datapackage (string) – String of meta data file datapackage.json
n (integer) – Number of timesteps to skip
path (string) – Path to directory where the aggregated datapackage is stored
name (string) – Name of the new, aggregated datapackage. If not specified a name will be given

oemof.datapackage.datapackage.building module

oemof.datapackage.datapackage.building.infer_metadata(package_name='default-name', keep_resources=False, path=None, metadata_filename='datapackage.json')[source]

Add basic meta data for a datapackage

Parameters:

package_name (string) – Name of the data package
keep_resources (boolean) – Flag indicating of the resources meta data json-files should be kept after main datapackage.json is created. The resource meta data will be stored in the resources directory.
path (string) – Absolute path to root-folder of the datapackage
metadata_filename (basestring) – Name of the inferred metadata string.

oemof.datapackage.datapackage.building.infer_metadata_from_data(path, package_name='default-name', metadata_filename='datapackage.json', fk_targets=None)[source]

Creates a metadata .json file at the root-folder of datapackage

The foreign keys are inferred from the csv files within “data/elements” and “data/sequences” resources.

Parameters:

path (string) – Absolute path to root-folder of the datapackage
package_name (string) – Name of the data package
metadata_filename (basestring) – Name of the inferred metadata string.
fk_targets (list of string) – List of resources name containing potential foreign keys targets

Returns:

Save a json metadata file at the root-folder of datapackage
under the provided path.

oemof.datapackage.datapackage.building.infer_package_foreign_keys(package, fk_targets=None)[source]

Infer the foreign_keys from elements and sequences and update meta data

Parameters:

package (a Package instance)
fk_targets (resources containing potential foreign keys targets)

oemof.datapackage.datapackage.building.infer_resource_foreign_keys(resource, sequences_profiles_to_resource, fk_targets_mapping)[source]

Find out the foreign keys within a resource fields

Look through all field of a resource which are of type ‘string’ if any of their values are matching a profile header in any of the sequences resources or a value within the column name of resources present in fk_targets_mapping

Parameters:

resource (a :datapackage.Resource: instance)
sequences_profiles_to_resource (the mapping of sequence profile) – headers to their resource name
fk_targets_mapping (a mapping of potential foreign keys targets mapped to)
their resource

Returns:

The (datapackage.Resource: instance with updated “foreignKeys” field)

oemof.datapackage.datapackage.building.infer_resources(directory='data/elements')[source]

Method looks at all files in directory and creates datapackage.Resource object that will be stored

Parameters:: directory (string) – Path to directory from where resources are inferred

oemof.datapackage.datapackage.building.initialize(config, directory='.')[source]: Initialize datapackage by reading config file and creating required directories (data/elements, data/sequences etc.) if directories are not specified in the config file, the default directory setup up will be used.

oemof.datapackage.datapackage.building.input_filepath(file, directory='archive/')[source]

oemof.datapackage.datapackage.building.map_sequence_profiles_to_resource_name(p, excluded_profiles=('timeindex',))[source]

Look in every sequence resources and map each of its fields to itself

Within this process the unicity of the field names will be checked, with the exception of the field “timeindex”

oemof.datapackage.datapackage.building.package_from_resources(resource_path, output_path, clean=True)[source]

Collects resource descriptors and merges them in a datapackage.json

Parameters:

resource_path (string) – Path to directory with resources (in .json format)
output_path (string) – Root path of datapackage where the newly created datapckage.json is stored
clean (boolean) – If true, resources will be deleted

oemof.datapackage.datapackage.building.read_build_config(file='build.toml')[source]

Read config build file in toml format

Parameters:: file (string) – String with name of config file

oemof.datapackage.datapackage.building.read_elements(filename, directory='data/elements')[source]

Reads element resources from the datapackage

Parameters:

filename (string) – Name of the elements to be read, for example load.csv
directory (string) – Directory where the file is located. Default: data/elements

Returns:

pd.DataFrame

oemof.datapackage.datapackage.building.read_sequences(filename, directory='data/sequences')[source]

Reads sequence resources from the datapackage

Parameters:

filename (string) – Name of the sequences to be read, for example load_profile.csv
directory (string) – Directory from where the file should be read. Default: data/sequences

oemof.datapackage.datapackage.building.timeindex(year, periods=8760, freq='H')[source]

Create pandas datetimeindex.

Parameters:

year (string) – Year of the index
periods (string) – Number of periods, default: 8760
freq (string) – Freq of the datetimeindex, default: ‘H’

oemof.datapackage.datapackage.building.update_package_descriptor()[source]

oemof.datapackage.datapackage.building.write_elements(filename, elements, directory='data/elements', replace=False, overwrite=False, create_dir=True)[source]

Writes elements to filesystem.

Parameters:

filename (string) – Name of the elements to be read, for example reservoir.csv
elements (pd.DataFrame) – Elements to be stored in data frame. Index: name
directory (string) – Directory where the file is stored. Default: data/elements
replace (boolean) – If set, existing data will be overwritten. Otherwise integrity of data (unique indices) will be checked
overwrite (boolean) – If set, existing elements will be overwritten
create_dir (boolean) – Create the directory if not exists

Returns:

path (string) – Returns the path where the file has been stored.

oemof.datapackage.datapackage.building.write_sequences(filename, sequences, directory='data/sequences', replace=False, create_dir=True)[source]

Writes sequences to filesystem.

Parameters:

filename (string) – Name of the sequences to be read, for example load_profile.csv
sequences (pd.DataFrame) – Sequences to be stored in data frame. Index: datetimeindex with format %Y-%m-%dT%H:%M:%SZ
directory (string) – Directory where the file is stored. Default: data/elements
replace (boolean) – If set, existing data will be overwritten. Otherwise integrity of data (unique indices) will be checked
create_dir (boolean) – Create the directory if not exists

Returns:

path (string) – Returns the path where the file has been stored.

oemof.datapackage.datapackage.processing module

oemof.datapackage.datapackage.processing.clean(path=None, directories=['data', 'cache', 'resources'])[source]

Parameters:

path (str) – Path to root directory of the datapackage, if no path is passed the current directory is to be assumed the root.
directories (list (optional)) – List of directory names inside the root directory to clean (remove).

oemof.datapackage.datapackage.processing.copy_datapackage(source, destination, subset=None)[source]

Parameters:

source (str) – datapackage.json
destination (str) – Destination of copied datapackage
name (optional) (str) – Name of datapackage
only_data (str) – Name of directory to only copy subset of datapackage (for example only the ‘data’ directory)

oemof.datapackage.datapackage.processing.to_dict(value)[source]: Convert value from e.g. csv-reader to valid json / dict

oemof.datapackage.datapackage.reading module

Tools to deserialize energy systems from datapackages.

WARNING

This is work in progress and still pretty volatile, so use it at your own risk. The datapackage format and conventions we use are still a bit in flux. This is also why we don’t have documentation or tests yet. Once things are stabilized a bit more, the way in which we extend the datapackage spec will be documented along with how to use the functions in this module.

oemof.datapackage.datapackage.reading.deserialize_constraints(model, path, constraint_type_map=None)[source]

oemof.datapackage.datapackage.reading.deserialize_energy_system(cls, path, typemap=None, attributemap=None)[source]

oemof.datapackage.datapackage.reading.read_facade(facade, facades, create, typemap, data, objects, sequence_names, fks, resources)[source]: Parse the resource r as a facade.

oemof.datapackage.datapackage.reading.sequences(r, timeindices=None)[source]: Parses the resource r as a sequence.

oemof.datapackage.tools package

oemof.datapackage’s kitchen sink module.

Contains all the general tools needed by other tools dealing with specific datapackage data sources.

class oemof.datapackage.tools.HSN(mapping_or_iterable=(), /, **kwargs)[source]

Bases: SimpleNamespace

A hashable variant of types.Simplenamespace.

By making it hashable, we can use the instances as dictionary keys, which is necessary, as this is the default type for flows.

oemof.datapackage.tools.raisestatement(exception, message='')[source]: A version of raise that can be used as a statement.

oemof.datapackage.tools.remap(mapping, renamings, selection)[source]

Change mapping’s keys according to the selection in renamings.

The renaming found under selection in renamings is used to rename the keys found in mapping. I.e., return a copy of mapping with every key of mapping that is also found in renaming replaced with renaming[key].

If key doesn’t have a renaming, it’s returned as is. If selection doesn’t appear as a key in renamings, mapping is returned unchanged.

Example

>>> renamings = {'R1': {'zero': 'nada'}, 'R2': {'foo': 'bar'}}
>>> mapping = {'zero': 0, 'foo': 'foobar'}
>>> remap(mapping, renamings, 'R1') == {'nada': 0, 'foo': 'foobar'}
True
>>> remap(mapping, renamings, 'R2') == {'zero': 0, 'bar': 'foobar'}
True

As a special case, if selection is a class, not only selection is considered to select a renaming, but the classes in selection’s mro are considered too. The first class in selection’s mro which is also found to be a key in renamings is used to determine which renaming to use. The search starts at selection.

Parameters:

mapping (Mapping) – The Mapping whose keys should be renamed.
renamings (Mapping of Mappings <collections.abc.Mapping>)
selection (Hashable) – Key specifying which entry in renamings is used to determine the new keys in the copy of mapping. If selection is a class, the first entry of selection’s mro which is found in renamings is used to determine the new keys.

Submodules

oemof.datapackage.tools.geometry module

The code in this module is partly based on third party code which has been licensed under GNU-GPL3. The following functions are copied and adapted from:

_shape2poly()
simplify_poly()
nuts()

oemof.datapackage.tools.geometry.Shapes2Shapes(orig, dest, normed=True, equalarea=False, prep_first=True, **kwargs)[source]

Notes

oemof.datapackage.tools.geometry.intersects(geom, labels, geometries)[source]

oemof.datapackage.tools.geometry.nuts(filepath=None, nuts=0, subset=None, tolerance=0.03, minarea=1.0)[source]

Reads shapefile with nuts regions and converts to polygons

Returns:: OrderedDict – Country keys as keys of dict and shapely polygons as corresponding values

Notes

oemof.datapackage.tools.geometry.read_geometries(filename, directory='data/geometries')[source]

Reads geometry resources from the datapackage. Data may either be stored in geojson format or as WKT representation in CSV-files.

Parameters:

filename (string) – Name of the elements to be read, for example buses.geojson
directory (string) – Directory where the file is located. Default: data/geometries

Returns:

pd.Series

oemof.datapackage.tools.geometry.reproject(geom, fr=pyproj.Proj, to=pyproj.Proj)[source]

Notes

oemof.datapackage.tools.geometry.simplify_poly(poly, tolerance)[source]

Notes

oemof.datapackage.tools.geometry.write_geometries(filename, geometries, directory='data/geometries')[source]

Writes geometries to filesystem.

Parameters:

filename (string) – Name of the geometries stored, for example buses.geojson
geometries (pd.Series) – Index entries become name fields in GeoJSON properties.
directory (string) – Directory where the file is stored. Default: data/geometries

Returns:

path (string) – Returns the path where the file has been stored.