Working with commodities

Commodity & CommoditySet Modules

Changelog

Version	Description
5.0.1	np.float is deprecated, change to float.
3.4.11	a bug fixed in the get_delivery_hours method related to the date range
3.4.10	added get_delivery_hours method
3.4.7	bugfix in the Commodity constructor related to the type of LHV energy content.
3.4.6	add count_delivery_hours.
3.1.2	add extra properties to the commodity object.
3.4.4	added dst_switches to the commodity object.
3.0.0	Constructor doesnt read anymore from xml node, use CommoditySet object
1.0.0	Class Commodity added.

Documentation

Commodity Class

A Commodity object contains key data pertaining to a commodity as defined on the KYOS platform. Commodity objects should be constructed using the make_commodity() function.

Attributes:

Name	Type	Description
id	int	Commodity ID number
name	str	Name of the commodity
is_cent	bool	Boolean which indicates if the commodity's currency units are in cents i.e. 1/100th of the main denomination unit
currency	Currency	Currency object corresponding the Currency ID number for this commodity.
unit_id	int	Unit id of the commodity
energy_content	float	Energy content of commodity measred in Joules
group_id	int	Group ID number of the commodity
group_name	str	Group name of the commodity e.g. 'power' or 'gas'
delivery_type_Set	object	kyoslib.DeliveryTypeSet object
trading_calendar_id	int	ID number of the trading calendar that corresponds to this commodity
timezone_id	int	ID of the timezone of the commodity
timezone_name	str	Name of the timezone of the commodity
timezone_offset_minutes	int	how many minutes dst
trading_day_start	int	hour of start delivery, e.g. uk power starts at 23:00
tradable_period_id	int	delivery_period_id of tradable granularity, e.g. Dutch power has hour granularity
is_default_group_unit	bool	is this commodity unit the default of the group
unit_conversion_type	int	type of conversion type, e.g. 0 is none, 1 is energy and 2 is volume. This is defined in the KYOS' setting screen
volume_conversion_factor	float	conversion factor to commodity group default. E.g. if the commodity has default unit MT but the default of the group is in LBS, then this factor is approximately 2204.6
carbon_content	float	Carbon content (kg/GJ)
energy_lhw	float	lower heating value of a fuel commodity
dst_switches	Series	Series with dst switch moments for the commodity's timezone

count_delivery_hours(output_granularity, start_date, end_date, delivery_type_id=1)

Counts the number of delivery hours within a given time granularity and for a given delivery type ID.

Parameters:

Name	Type	Description	Default
output_granularity	int	Desired output granularity (day=3, month=5).	required
start_date	datetime	Start date (sets time equal to 00:00:00).	required
end_date	datetime	End date (sets time equal to 00:00:00).	required
delivery_type_id	int	(optional) Delivery type ID (e.g. baseload=1, peakload=2). Default value is 1.	1

Returns:

Type	Description
tuple	tuple containing: - (np.array): delivery_hours. Size: L-by-1 (where L is the number of time periods according to output_granularity). - (np.array): datetime_vec. Vector of datetime.date values from start_date to end_date, according to desired output granularity. Size: L-by-1 (where L is the number of time periods according to output_granularity).

dst_change(date_vector, delivery_matrix)

Adjusts the number of delivery hours in the delivery matrix, according to DST switch dates.

Parameters:

Name	Type	Description	Default
date_vector	array	Vector of dates (daily granularity).	required
delivery_matrix	array	Matrix of delivery hours for each date in date_vector. Elements in the matrix must be of type float, with value=1 (delivery) or value=0 (no delivery). Size: L-by-24, with L the length of date_vector.	required

Returns:

Type	Description
array	Delivery matrix with adjusted delivery hours.

get_delivery_hours(del_period_id, start_date, end_date, delivery_type_id=1)

Returns the delivery hours and the delivery indicators between the start and end date granularity and for a given delivery type ID. Current implementation does not support to return delivery dates with the DST switches

Parameters:

Name	Type	Description	Default
del_period_id	int	delivery period/granularity of the dates (2-hour, 1 -half hour, 14 - quarter hour)	required
start_date	datetime	Start date (sets time equal to 00:00:00).	required
end_date	datetime	End date (sets time equal to 00:00:00).	required
delivery_type_id	int	(optional) Delivery type ID (e.g. baseload=1, peakload=2). Default value is 1.	1

Returns:

Name	Type	Description
delivery_dates	np.array)(NDays x 24 x period_per_hour	calendar delivery date
ind_delivery	np.array) (NDays x 24 x period_per_hour	true/false if delivery happens in this period

Helpers

Returns a list of all available commodity objects in the input xml file generated by the KYOS platform

Parameters:

Name	Type	Description	Default
xml_path	str	Full path to xml file including name	'PrototypeSettings.xml'

Returns:

Type	Description
list	List of commodity objects

Note

XML settings file called KyPythonSettings.xml must exist within the current working (project) directory. This file contains the commodity information. The make_currency function should be run before make_commodity

Examples:

>>> from kyoslib_py.settings import make_commodity
>>> commodity_set = make_commodity()
>>> commodity_set[0].group_name
'power'
>>> next((x for x in commodity_set if x.id == 5), None)

CommoditySet Class

This is the manager object of the commodity class. This class loads the set of all available commodites.

Attributes:

Name	Type	Description
commodities	list	list of objects

Examples:

>>> from kyoslib_py.settings import CommoditySet
>>> commodity_set = CommoditySet.from_xml()
>>> commodity = commodity_set.get_commodity(5)
>>> commodity.get_name()
'TTF'

__init__(commodity_info_list, currency_set)

Parameters:

Name	Type	Description	Default
commodity_info_list	list	this is a list of dictionaries. Each dictionary contains the commodity info for a commodity object. This is the standard form in which a commodity is described, for example in the KYOS API.	required
currency_set	CurrencySet	contains standard information about all currencies available in the KYOS platform.	required

from_xml(xml_path='./PrototypeSettings.xml', currency_set=None, calendar_set=None, dst_switches_set=None) staticmethod

This method builds the CommoditySet object from a xml file.

Parameters:

Name	Type	Description	Default
xml_path	str	path to the xml file with commodity information	'./PrototypeSettings.xml'
currency_set	object	kyoslib.CurrencySet object	None
calendar_set	object	kyoslib.CalendarSet object	None
dst_switches_set	object	object	None

Returns:

Type	Description
object	kyoslib.CommoditySet object

get_commodity(requested_commodity_id)

Returns commodity object if commodity_id is found in the set of commodities.

Parameters:

Name	Type	Description	Default
requested_commodity_id	int	commodity id from the server	required

Returns:

Type	Description
object	kyoslib.Commodity object or None

get_commodity_id_list()

This method can be used to a list of ids of the commodities inside the commodity set

Returns:

Type	Description
list	each element is a KYOS commodity id

get_commodity_list()

This method can be used to a list of the commodities inside the commodity set

Returns:

Type	Description
list	each element is a KYOS commodity

This is a set of Daylight saving switches. A method is created to get the timezone dependent dst switches.

Attributes:

Name	Type	Description
commodities	list	list of objects

get_dst_moments(timezone_id)

This method gets the time dependent DST series.

Parameters:

Name	Type	Description	Default
timezone_id	int	id of the relevant timezone	required

Returns:

Type	Description
Series	pandas.Series: series with dst moment with the datetime on the index