API Reference¶

Site¶

Overview¶

`create`(site_config)	Create a new site
`forecast`(site_id[, type])	Get the latest forecast for a site
`get`(site_id)	Get a site by id
`delete`(site_id)	Delete a site
`list`()	List all of your sites
`status`(site_id)	Get the training status of your site.
`train`(site_id)	Start training for your site
`upload`(site_id, df)	Upload observed data for your site.

Methods¶

class rebase.Site¶

classmethod create(site_config)¶

Create a new site

Parameters: site_config (dict) – config for site to create
Returns: the site id for the newly created site
Return type: str
Raises: rebase.InvalidUsageError – if site_config is missing some required fields

Example:

>>> site_config = {
    'latitude': 51,
    'longitude': 7
}
>>> site_id = rb.Site.create(site_config)
>>> print(site_id)
4ab82692-3944-4069-9cbb-f9c59513c1c3

classmethod delete(site_id)¶

Delete a site

Parameters: site_id (str) – id of site to delete
Raises: rebase.NotFoundError – if specified site does not exist

Example:

>>> site_id = '4ab82692-3944-4069-9cbb-f9c59513c1c3'
>>> rb.Site.delete(site_id)
Success. Site: 4ab82692-3944-4069-9cbb-f9c59513c1c3 was deleted.

classmethod forecast(site_id, type='prioritized')¶

Get the latest forecast for a site

Parameters

site_id (str) – id of the site
type (str) –
type of forecast to return
- prioritized returns best forecast at the time
- ai only returns AI forecasts
- physical only returns physical forecasts
Default prioritized

Returns

Returns a dict with the following format:

{
    'type' (str): # type same as params,
    'ref_time' (DateTime): # date when forecast data updated,
    'df' (pandas.DataFrame): # dataframe with forecast data
}

Example:

>>> site_id = '4ab82692-3944-4069-9cbb-f9c59513c1c3'
>>> data = rb.Site.forecast(site_id)
>>> print(data['df'])
                               forecast
    valid_time
    2020-10-14 00:00:00+00:00       77.3
    2020-10-14 00:15:00+00:00       86.1
    ...                             ...
    2020-10-17 23:30:00+00:00       87.0
    2020-10-17 23:45:00+00:00       86.6

Return type

dict

classmethod get(site_id)¶

Get a site by id

Parameters

site_id (str) – the id of the site

Returns

the config of the site

Example:

>>> site_id = '4ab82692-3944-4069-9cbb-f9c59513c1c3'
>>> site_config = rb.Site.get(site_id)
>>> print(site_config)
{
    'site_id': '4ab82692-3944-4069-9cbb-f9c59513c1c3',
    'type': 'solar'
}

Return type

dict

Raises

rebase.NotFoundError – if specified site does not exist

classmethod list()¶

List all of your sites

Returns

list with one dict per site

Example:

>>> sites = rb.Site.list()
>>> print(sites)
[
    {'site_id': ..., }, # site 1
    ...,
    {'site_id': ...}, # site N
]

Return type

List

classmethod status(site_id)¶

Get the training status of your site.

Parameters

site_id (str) – id of site to get status of

Returns

Returns a dict with the training status.

Possible states:

queued - training is queued
training - is currently training
complete - training is complete
retry - training failed but is retrying
failed - training failed (no more retry)

Example:

>>> site_id = '4ab82692-3944-4069-9cbb-f9c59513c1c3'
>>> rb.Site.status(site_id)
{
    'status': 'complete',
    'history': [
        {'state': 'queued', 'timestamp_utc': '2020-10-12 13:04:17'},
        {'state': 'training', 'timestamp_utc': '2020-10-12 13:04:22'},
        {'state': 'complete', 'timestamp_utc': '2020-10-12 13:05:23'},
    ]
}

Return type

dict

classmethod train(site_id)¶

Start training for your site

Parameters: site_id (str) – id of site to train
Raises: rebase.TrainingNotReadyError – if you have not uploaded observation data to train on for this site

Example:

>>> site_id = '4ab82692-3944-4069-9cbb-f9c59513c1c3'
>>> rb.Site.train(site_id)

classmethod upload(site_id, df)¶

Upload observed data for your site. This data is used when training a model.

Parameters

site_id (str) – id of site to upload data for

df (pandas.DataFrame) –

DataFrame with the following format

>>>
         valid_time                observation

0        2020-01-22 00:00:00+00:00       126.3
1        2020-01-22 00:15:00+00:00       122.7
.        ...                             ...
n-1      2020-10-17 23:30:00+00:00       169.2
n        2020-10-17 23:45:00+00:00       176.6

Example:

>>> import pandas as pd
>>> site_id = '4ab82692-3944-4069-9cbb-f9c59513c1c3'
>>> df = pd.read_csv('example_data.csv')
>>> rb.Site.upload(site_id, df)
Success!

Configurations¶

There are currently 4 different supported types of sites:

Solar
Wind
Localized weather
Electricity demand

Each of them requires a specific configuration when being created from rb.Site.create(), which you can find below.

Solar¶

Required attributes¶
Attribute	Description	type
type	Type of site (must be `solar` in this case)	string
name	Name to give your site	string
latitude	Latitude of your site, ranging from `29.5` to `70.5`	float
longitude	Longitude of your site, ranging from `-23.5` to `45.0`	float
azimuth	Orientation of your solar panels, `North = 0, East = 90, South = 180, West = 270` degrees	float
tilt	Tilt of your solar panels `0` to `90` degrees	float
capacity	Capacity of your site. Should be an array containing one object for each capacity change on this format: `[{value: v0, validFrom: d0}, ..., {value: vn, validFrom: dn}]` value of `value` key must be the capacity in kW as a float value of `validFrom` key must be an ISO 8601 formatted date string from when the capacity is valid from	JSON array of JSON objects

Example:

 {
  'type': 'solar',
  'name': 'My solar site',
  'latitude': 53.41,
  'longitude': 5.94,
  'azimuth': 171.3, # 0 = North, 90 = East, 180 = South, 270 = West
  'tilt': 10.3,
  'capacity': [
    {'value': 750.5, 'validFrom': '2019-10-10T00:00:00Z'}, # capacity of site changed to 750.5 kW at this date
    {'value': 500.3, 'validFrom': '2019-04-03T00:00:00Z'}, # site was installed at this date
  ],
}

Wind¶

Required attributes¶
Attribute	Description	type
type	Type of site (must be `wind` in this case)	string
name	Name to give your site	string
latitude	Latitude of your site, ranging from `29.5` to `70.5`	float
longitude	Longitude of your site, ranging from `-23.5` to `45.0`	float
capacity	Capacity of your site. Should be an array containing one object for each capacity change on this format: `[{value: v0, validFrom: d0}, ..., {value: vn, validFrom: dn}]` value of `value` key must be the capacity in kW as a float value of `validFrom` key must be an ISO 8601 formatted date string from when the capacity is valid from	JSON array of JSON objects

Example:

{
  'type': 'wind',
  'name': 'My wind site',
  'latitude': 53.41,
  'longitude': 5.94,
  'capacity': [
    {'value': 4000, 'validFrom': '2019-10-10T00:00:00Z'}, # capacity of site changed to 4000 kW at this date
    {'value': 2000, 'validFrom': '2019-04-03T00:00:00Z'}, # site was installed at this date
  ],
}

Localized weather¶

Required attributes¶
Attribute	Description	type
type	Type of site (must be `localized` in this case)	string
name	Name to give your site	string
latitude	Latitude of your site, ranging from `29.5` to `70.5`	float
longitude	Longitude of your site, ranging from `-23.5` to `45.0`	float
measurement	The type of measurement data to predict Must be one of: `WindSpeed / Temperature / CloudCover`	string

Example:

{
  'type': 'localized',
  'name': 'My localized site',
  'latitude': 53.41,
  'longitude': 5.94,
  'measurement': 'WindSpeed'
}

Electricity demand¶

Required attributes¶
Attribute	Description	type
type	Type of site (must be `load` in this case)	string
name	Name to give your site	string
latitude	Latitude of your site, ranging from `29.5` to `70.5`	float
longitude	Longitude of your site, ranging from `-23.5` to `45.0`	float
nwps	An array of one or more NWPS to train on Must be one or more of: `DWD_ICON-EU` `NCEP_GFS`	JSON array of strings
variables	Array of NWP variables and lags to use in training Available variables: `Temperature` `SolarDownwardRadiation` `WindSpeed` `WindDirection` `CloudCover` Each variable can have an optional array of lags with values in range `-24` to `24`	JSON array of JSON objects
variables	Array of calendar features that should be included in training Available features: `holidays` - If the model should take public holidays into account `hourOfDay` - If the model should take into account which hour of the day it is `dayOfWeek` - If the model should take into account which day of the week it is `weekOfYear` - If the model should take into account which week of the year it is	JSON array of JSON strings

Example:

{
   'type': 'load',
   'name': 'My load site',
   'latitude': 53.41,
   'longitude': 5.94,
   'nwps': ['DWD_ICON-EU', 'NCEP_GFS'],
   'variables': [
       {'name': 'Temperature', 'lag': [-4, -3, -2, -1, 1, 2, 3, 4]},
       {'name': 'SolarDownwardRadiation'},
   ],
   'calendar': ['holidays', 'hourOfDay'],
}

User guide