Units and Aggregation Rules

Units

In the absence of units, time series values are only a collection of numbers, with no meaning. Units can be used to add meaning to numbers and determine how to interpret numbers in relation to other numbers having other units.

HAKOM provides a set of standard units as part of the installation. Additionally custom unit configuration is supported as described in the following chapter. Units are defined separately for each data source (repository) in HAKOM TSM.

A unit has the following properties:

Property	Meaning	Example kW (Kilowatt)	Example F (Fahrenheit)
Name	Name of the unit	kW	F
Base Unit	Name of the base unit, from which the respective unit is mathematically derived	W	°C
Offset	Constant that is added to the base unit before the multiplication factor is applied	0.0	-32.0
Factor	Multiplication factor to convert from the base unit to the respective unit	1000.0	0.555555555555556
Integral Unit	Integral unit to be used for conversion from a power unit to a volumetric unit	kWh	null
Aggregation	Aggregation rule, which is applied when the unit is converted from one raster to another raster length	AVG	SUM

Managing Units

Currently, units can be queried, added or updated using the WebTSM Services API via /repositories/:repository/units and /repositories/:repository/units/:ID|name path.

/units request body

XML

{
    "ID": 4,
    "Name": "MW",
    "Factor": 1000000.0,
    "Offset": 0.0,
    "BaseUnit": "W",
    "Aggregation": "AVG",
    "IntegralUnit": "MWh",
    "Description": null,
    "Category": null
}

No Unit

A time series can be configured without a unit by selecting the unit "none". This unit has no configured base unit and uses the aggregation rule "Average".

New Units

It is possible to use new custom units by simply assigning them to a time series when creating or editing a time series. These new units however will behave like the unit "none" regarding their base unit and aggregation rule. It is therefore necessary to properly configure them as described above in order to use unit conversion and the suitable aggregation method.

Conversion Paths

The system automatically determines a conversion path between two units using existing unit definitions and their base units. For example, it is sufficient if the system has a definition for W, kW (with base unit W) and MW (with base unit W) to be able to convert from MW to kW. No explicit definition of kW to MW is required.

Non-linear Conversion Paths

In some cases a conversion from one unit is not possible using a constant factor and offset. This is the case with variable conversion factors, such as price data, currency conversions or temperature-dependent calorific value conversions.

For such cases HAKOM TSM supports the definition of so-called conversion time series. The unit of a conversion time series is always given in "numerator/denominator notation", where the target unit is given in the numerator and the base unit in the denominator. For example "EUR/MW", "EUR/USD" or "kWh/m3".

If a time series is defined with a new unit in "numerator/denominator notation", this time series will automatically be marked as a conversion time series. If no classical unit is available for the conversion path (target unit/base unit), the conversion time series will be used as conversion factor. It is possible to define several conversion time series for the same path, in this case the desired conversion time series must be attached to any time series, that requires that conversion path.

Definition of a Conversion Time Series

TSM App:

Click on Load in the TSM Ribbon
Press the Search... button in the Time series area of the TSM window
Select the Edit tab in the Time Series Search window
In tab Conversions in the bottom part of the screen add the required conversion time series via "→" button.
Press the Save button

For more information about assigning conversion time series also see: Creating, Editing and Deleting Time Series

WebTSM Services API:

Under one of the time series definition paths (/timeseries/:ID|name or /timeseriescollection/definition) in the time series body "ExchangeTimeSeries" pass the list of IDs of the required conversion time series:

JS

{
    "Name": "MyFirstTimeSeries",
    "Type": 2,
    "Interval": {
        "Value": "2",
        "Multiplier": "15"
   },
   "Unit": "KWh",
   "ExchangeTimeSeries": [1,2,3,4]
}

Aggregation Rules

Aggregation rules define how individual values are aggregated in different rasters. For example, the Sum rule will result in all values being summed up when switching from a smaller interval to a larger one, while the Average rule will take the average of the respective values. These rules can be defined at several places, such as:

in the unit (currently only SUM and AVG aggregation rules are supported on this level)
in the time series
in the time series data request

You can read more about aggregation rules and their effect with different rasters here: Aggregation

We recommend the following videos under Video Tutorials:

Units
Aggregation
Behaviour of Flags During Data Aggregation