HistoricalPrice Class¶
The HistoricalPrice class allows the storing and loading of historical price spot and forward data sent to a
Prototypemodel. The choice of which historical data should be made available to a model is made when defining aPrototypeprofile. Please refer to the section describing Prototypes in the User manual of the Kyos Analytical platform. Alternatively, if the price source ID is already known, the API can be used via a method in the class.
Changelog¶
| Version | Description |
|---|---|
| 2.2.1 | Adjust order of granularity detection in API method. |
| 2.2.0 | Include method to import historical prices using API. |
| 1.6.4 | Bugfix in get_historical_prices() in class HistoricalPrice. |
| 1.0.0 | Class HistoricalPrice added. |
Documentation¶
The HistoricalPrice class allows the storing and loading of historical price spot and forward data sent to a model in csv format, in addition to historical_data_info.json.
Attributes:
| Name | Type | Description |
|---|---|---|
id |
int
|
Price source id |
commodity_id |
int
|
Id number of the corresponding commodity |
type |
string
|
spot' or 'forward' |
delivery_type |
str
|
base', 'peak' or 'other' for forward prices, otherwise an empty list |
delivery_period_id |
int
|
Id number of the delivery period for spot prices, otherwise an empty list |
prices |
DataFrame
|
Pandas dataframe containing the price data. Empty list until loaded with a method (see below). |
Notes
All historical price profiles contained with the json file in the HistoricalData directory are loaded at the same time and stored within the class variable all_price_sources. The path of the subdirectory is also saved as a class variable (price_path).
Examples:
>>> from kyoslib_py.historical_price import HistoricalPrice
>>> HistoricalPrice()
>>> HistoricalPrice.all_price_sources[0].id
>>> 33
__init__(base_path=None)
¶
Constructor method.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_path
|
str
|
String of the path of the main job directory. The HistoricalData subdirectory is assumed to be one level down. |
None
|
get_historical_prices(start_date=None, end_date=None, start_delivery_date=None, delivery_type_id=None, delivery_period_id=None, maturity=None)
¶
Method to load specific price data for a given price source id. If already stored in the object, reads it directly otherwise loads it using the load_all_prices method.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
start_date
|
Datetime
|
Start date from which to return prices. For forward prices, the trading date is used. For spot, the delivery date is used. Defaults to the earliest date if not provided. |
None
|
end_date
|
Datetime
|
End date before which to return prices. For forward prices, the trading date is used. For spot, the delivery date is used. Defaults to the latest date if not provided. |
None
|
start_delivery_date
|
Datetime
|
Only return prices with delivery that starts on this date (relevant for forward prices only, otherwise use start_date and end_date). All delivery starts returned if not provided. |
None
|
delivery_type_id
|
list
|
List of delivery type ids for which to return historical prices. Only relevant for forward prices. All delivery types returned if not provided. |
None
|
delivery_period_id
|
list
|
List of delivery period ids for which to return historical prices. Only relevant for forward prices. All delivery periods returned if not provided. |
None
|
maturity
|
list
|
List of maturities for which to return historical prices. Only relevant for forward prices. All maturities returned if not provided |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame of the relevant price data. Returned in same format as the input data, which depends on the data being of type 'forward' or 'spot'. |
Examples:
>>> from kyoslib_py.historical_price import HistoricalPrice
>>> HistoricalPrice()
>>> HistoricalPrice.all_price_sources[0].get_historical_prices()
>>> HistoricalPrice.all_price_sources[0].get_historical_prices(start_date=dt.datetime(2019,1,1),
delivery_period_id = [1 2])
get_historical_prices_api(profile_id, price_type, csv_write=False, start_date=None, end_date=None, products=None, delivery_start_date=None, maturity=None)
staticmethod
¶
Static method to load spot or forward price data for a specific price source ID via API, with option to save to disk as csv file & json (as per the format expected by the HistoricalPrice class).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
profile_id
|
int
|
price source ID number |
required |
price_type
|
string
|
Type of prices being requested, must be either 'forward' or 'spot'. Case insensitive. |
required |
csv_write
|
Boolean
|
If true, writes data to csv and JSON in specific format. Defaults to False. |
False
|
start_date
|
string
|
YYYY-MM-DD format, start date for API request. |
None
|
end_date
|
string
|
YYYY-MM-DD format, start date for API request. |
None
|
products
|
list
|
List of products being requested (strings). Relevant for forward data only. Must be one of the following: day, month, quarter, season, calyear, gasyear, weekend, week, bow, wdnw or bom. |
None
|
delivery_start_date
|
string
|
Delivery start date of requested price data in YYYY-MM-DD format. Relevant for forward data only. Can only be used in combination with one product and not with maturity. |
None
|
maturity
|
int
|
Maturity of requested data. Relevant for forward data only. Can only be used in combination with one product and cannot be used with maturity. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame of the relevant price data in specific format which varies depending on the data being spot or forward. |
Examples:
>>> from kyoslib_py.historical_price import HistoricalPrice as Hp
>>> prices = Hp.get_historical_prices_api(profile_id=15, price_type='spot')
>>> prices = Hp.get_historical_prices_api(profile_id=27, price_type='forward', csv_write=True)
>>> prices = Hp.get_historical_prices_api(profile_id=15, price_type='spot', start_date='2020-07-20',
>>> end_date='2020-08-01')
load_all_prices()
¶
Method to load all price data in the associated csv file for a given price source id and store it as a DataFrame within the object.
Returns:
| Type | Description |
|---|---|
HistoricalPrice
|
Instance of the HistoricalPrice class with prices field populated with a DataFrame; date columns are sent as type DateTime. |
Examples:
>>> from kyoslib_py.historical_price import HistoricalPrice
>>> HistoricalPrice()
>>> HistoricalPrice.all_price_sources[0].load_all_prices()