Communicate with other analytical models

Functionality related to the KYOS platform valuation interface. It allows the transfer of data between different models within the platform.

Changelog

Version	Description
3.0.2	extra_model_data property name changed as extra_model_informationin the ValuationInterface class
2.3.0	extra_model_data property added to the valuation_interface object and set_extra_model_data method added
2.1.0	The customField property of the valuation_interface object changed as customFields
1.2.0	Module valuation_interface added.

Documentation

ValuationInterface Class

The ValuationInterface class allows valuation data to be sent between models in a consistent format, using a JSON file which describes the data, and csv files which contain the data.

Attributes:

Name	Type	Description
model_name	str	Name of the model from which data is being saved
trading_date	str	String in format YYYYMMDD representing the trading date of the model run
folder	string	Full path to the folder where JSON and csv files are to be saved
profile_id	int	Profile ID of the model where data is being saved
data	list	List which holds instances of the CommData class
extra_model_data	dict	model specific information

Note

Only one DataInterface can be constructed at a time. Each new instance of the class is appended to the list class variable all_interfaces

Examples:

>>> from kyoslib_py.valuation_interface import ValuationInterface
>>> import datetime as dt
>>> contract_output = ValuationInterface(model_name='Accumulator',
>>>                                      trading_date=dt.datetime(2020, 1, 1),
>>>                                      folder ='/Output', profile_id=13))
>>> print(contract_output.model_name)
>>> 'Accumulator'

__init__(model_name, trading_date, folder, profile_id=None)

Constructor of the ValuationInterface class.

Parameters:

Name	Type	Description	Default
model_name	str	Name of the model from which data is being saved	required
trading_date	DateTime	DateTime object representing the trading date of the model run	required
folder	string	Full path to the folder where JSON and csv files are to be saved	required
profile_id	int	Profile ID of the model where data is being saved	None

export_data(commodity_id=None)

The export_data method exports data for the relevant commodity into csv files and a single JSON files that describes the relevant data.

Parameters:

Name	Type	Description	Default
commodity_id	int	Commodity ID of the data to be exported. If not provided, all data is exported to csv and JSON.	None

Examples:

>>> import numpy as np
>>> import datetime as dt
>>> from kyoslib_py.valuation_interface import ValuationInterface
>>> contract_output = ValuationInterface(model_name='Accumulator',
>>>                                      trading_date=dt.datetime(2020, 1, 1),
>>>                                      folder ='/Output', profile_id=13))
>>> volume_dates = np.array([dt.datetime(2020,1,1), dt.datetime(2020,2,1),
>>>                          dt.datetime(2020,3,1)])
>>> volume_sims = np.array([[110,120,130], [111,121,132], [115,124,137]])
>>> contract_output.set_data(contract_id=1, forward_curve_id=1, currency_id=1, granularity=5,
>>>                          delivery_type=1, type_output=['Simulation'],
>>>                          type_calculation=['Volume'],
>>>                          dates=volume_dates, values=volume_dates)
>>> contract_output.export_data()

set_data(commodity_id, forward_curve_id, currency_id, granularity, delivery_type, type_output, type_calculation, dates, values)

The set_data method allows data (dates and values) to be added to an existing ValuationInterface class instance. The method automatically detects if time series or simulations are being added, and adds a CommData and/or SimulationData class instance to the data attribute of the ValuationInterface instance.

Parameters:

Name	Type	Description	Default
commodity_id	int	Commodity ID of the data to be stored	required
forward_curve_id	int	Forward curve ID of the data to be stored.	required
currency_id	int	Currency ID of the data to be stored	required
granularity	int	Granularity ID number of the data to be stored e.g. 2 = hourly, 3 = daily, 5 - monthly.	required
delivery_type	int	Delivery type ID of the data (e.g. 1 = baseload, 2 = peakload etc.)	required
type_output	list	List with length one containing a string indicating the type of output (i.e. simulations)	required
type_calculation	list	List with length one containing a string indicating the type of calculations associated with the simulations	required
dates	numpy array	1D numpy array containing the dates of the data values	required
values	numpy array	2D numpy array containing the data values	required

Returns:

Type	Description
ValuationInterface	Instance of the ValuationInterface class object with CommData and/or SimulationData class instances appended

Examples:

>>> import numpy as np
>>> import datetime as dt
>>> from kyoslib_py.valuation_interface import ValuationInterface
>>> contract_output = ValuationInterface(model_name='Accumulator',
>>>                                      trading_date=dt.datetime(2020, 1, 1),
>>>                                      folder ='/Output', profile_id=13))
>>> volume_dates = np.array([dt.datetime(2020,1,1), dt.datetime(2020,2,1),
>>>                          dt.datetime(2020,3,1)])
>>> volume_sims = np.array([[110,120,130], [111,121,132], [115,124,137]])
>>> contract_output.set_data(contract_id=1, forward_curve_id=1, currency_id=1, granularity=5,
>>>                          delivery_type=1, type_output=['Simulation'],
>>>                          type_calculation=['Volume'],
>>>                          dates=volume_dates, values=volume_dates)

set_extra_model_data(data, overwrite=False)

The set_extra_model_data method allows to store extra model information in the ValuationInterface class instance. instead of updating only top-level keys, set_extra_model_data recurses down into dicts nested to an arbitrary depth.

Parameters:

Name	Type	Description	Default
data	dict	a dictinary which conatins model specific information. e.g. accumulator object	required
overwrite	bool	True, clear the dictonariy and append the new input, False, append new input to the existing dictonary	False

Returns:

Type	Description
ValuationInterface	Instance of the ValuationInterface class object with extra model data

Examples:

>>> import datetime as dt
>>> from kyoslib_py.valuation_interface import ValuationInterface
>>> contract_output = ValuationInterface(model_name='KyAccumulator',
>>>                                      trading_date=dt.datetime(2020, 1, 1),
>>>                                      folder ='/Output', profile_id=13)
>>> extraInfo = {"accumulator": {"knock_out_price" : 150, "trigger_price": 130, "accumulation_price": 110}}
>>> contract_output.set_extra_model_data(data=extraInfo)
>>> extraInfo_2 = {"accumulator": {"knock_out_price" : 140, "trigger_price": 120, "accumulation_price": 100,
>>> "buy": 1}}
>>> contract_output.set_extra_model_data(data=extraInfo_2, overwrite=True)

set_metadata(input_folder)

A method to include a MetaData class object as a field within an existing ValuationInterface object. The metadata is saved ina file called 'metadata.json'. The metadata has a specific format, and it is used to pass extra data identifying an asset. Please contact KYOS for more information on the metadata.

Parameters:

Name	Type	Description	Default
input_folder	str	Full path of directory where the metadata.json file is located, without trailing file separator	required

Examples:

>>> from kyoslib_py.valuation_interface import ValuationInterface
>>> contract_output = ValuationInterface(model_name='Accumulator',
>>>                                      trading_date=dt.datetime(2020, 1, 1),
>>>                                      folder ='/Output', profile_id=13))
>>> contract_output.set_metadata('/metadata_folder')