Usage¶

There are two main ways to use pyiso: via the client objects, or via celery tasks. The client approach is preferred for scripted data analysis. The task approach enables asynchronous or periodic data collection and is in use at the WattTime Impact API.

Clients¶

First, create a client using the client_factory(ba_name) function. ba_name should be taken from this list of abbreviated names for available balancing authorities listed on the Introduction page. For example:

>>> from pyiso import client_factory
>>> isone = client_factory('ISONE')

Requests made to external data sources will automatically time out after 20 seconds. To change this value, add a keyword argument in the constructor:

>>> isone = client_factory('ISONE', timeout_seconds=60)

Each client returned by client_factory is derived from BaseClient and provides one or more of the following methods (see also Options):

BaseClient.get_generation(latest=False, yesterday=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse generation fuel mix data.

Parameters:	latest (bool) – If True, only get the generation mix at the one most recent available time point. Available for all regions. yesterday (bool) – If True, get the generation mix for every time point yesterday. Not available for all regions. start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both `start_at` and `end_at` parameters. Not available for all regions. end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both `start_at` and `end_at` parameters. Not available for all regions.
Returns:	List of dicts, each with keys `[ba_name, timestamp, freq, market, fuel_name, gen_MW]`. Timestamps are in UTC.
Return type:	list

BaseClient.get_load(latest=False, yesterday=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse load data.

Parameters:	latest (bool) – If True, only get the load at the one most recent available time point. Available for all regions. yesterday (bool) – If True, get the load for every time point yesterday. Not available for all regions. start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both `start_at` and `end_at` parameters. Not available for all regions. end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both `start_at` and `end_at` parameters. Not available for all regions.
Returns:	List of dicts, each with keys `[ba_name, timestamp, freq, market, load_MW]`. Timestamps are in UTC.
Return type:	list

BaseClient.get_trade(latest=False, yesterday=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse import/export data. Value is net export (export - import), can be positive or negative.

Parameters:	latest (bool) – If True, only get the trade at the one most recent available time point. Available for all regions. yesterday (bool) – If True, get the trade for every time point yesterday. Not available for all regions. start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both `start_at` and `end_at` parameters. Not available for all regions. end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both `start_at` and `end_at` parameters. Not available for all regions.
Returns:	List of dicts, each with keys `[ba_name, timestamp, freq, market, net_exp_MW]`. Timestamps are in UTC.
Return type:	list

The lists returned by clients are conveniently structured for import into other data structures like pandas.DataFrame:

>>> import pandas as pd
>>> data = isone.get_generation(latest=True)
>>> df = pd.DataFrame(data)
>>> print df
  ba_name freq fuel_name  gen_MW market                  timestamp
0   ISONE  n/a      coal  1170.0   RT5M  2014-03-29 20:40:27+00:00
1   ISONE  n/a     hydro   813.8   RT5M  2014-03-29 20:40:27+00:00
2   ISONE  n/a    natgas  4815.7   RT5M  2014-03-29 20:40:27+00:00
3   ISONE  n/a   nuclear  4618.8   RT5M  2014-03-29 20:40:27+00:00
4   ISONE  n/a    biogas    29.5   RT5M  2014-03-29 20:40:27+00:00
5   ISONE  n/a    refuse   428.6   RT5M  2014-03-29 20:40:27+00:00
6   ISONE  n/a      wind    85.8   RT5M  2014-03-29 20:40:27+00:00
7   ISONE  n/a   biomass   434.3   RT5M  2014-03-29 20:40:27+00:00

Happy data analysis!

Tasks¶

If you have a celery environment set up, you can use the tasks provided in the pyiso.tasks module. There is one task for each of the client’s get_* methods that implements a thin wrapper around that method. The call signatures match those of the corresponding client methods, except that the ba_name is a required first argument. For example, to get the latest ISONE generation mix data every 10 minutes, add this to your celerybeat schedule:

CELERYBEAT_SCHEDULE = {
    'get-isone-genmix-latest' : {
        'task': 'pyiso.tasks.get_generation',
        'schedule': crontab(minute='*/10'),
        'args': ['ISONE'],
        'kwargs': {'latest': True},
    }
}

In practice, you will want to chain these tasks with something that captures and processes their output.