Evaluate

pyclarify.client.Client.evaluate(rollup: Union[str, datetime.timedelta], items: List[Union[Dict, pyclarify.views.evaluate.ItemAggregation]] = [], calculations: List[Union[Dict, pyclarify.views.evaluate.Calculation]] = [], series: List[str] = [], gte: Union[datetime.datetime, str] = None, lt: Union[datetime.datetime, str] = None, last: int = - 1, include: List[str] = [], window_size: Union[str, datetime.timedelta] = None) → pyclarify.views.generics.Response

Retrieve DataFrame by aggregating time-series data and perform evaluate formula expressions.

Parameters

  • items (Union[Dict, ItemAggregation]) – List of item aggregations, describing a particular aggregation method for the item in list. See the class from pyclarify.views.evaluate.ItemAggregation for attributes.

  • calculations (List[Union[Dict, Calculation]]) – List of calculations, where a calculation has access to items and previous calculations in context. See the class from pyclarify.views.evaluate.Calculation for attributes

  • gte (ISO 8601 timestamp , default: <now - 7 days>) – An RFC3339 time describing the inclusive start of the window.

  • lt (ISO 8601 timestamp , default: <now + 7 days>) – An RFC3339 time describing the exclusive end of the window.

  • last (int, default: -1) – If above 0, select last N timestamps per series. The selection happens after the rollup aggregation.

  • rollup (RFC3339 duration or “window”, default: None) – If duration is specified, roll-up the values into either the full time window (gte -> lt) or evenly sized buckets.

  • include (List of strings, default: []) – A list of strings specifying which relationships to be included in the response.

  • window_size (RFC3339 duration, default None) – If duration is specified, the iterator will use the specified window as a paging size instead of default API limits. This is commonly used when resolution of data is too high to be packaged with default values.

Returns

Response.result.data is a DataFrame

Return type

Response

See also

Client.data_frame

Retrieve data with more filter functionality and without rollup.

Notes

Time selection:

  • Maximum window size is 40 days (40 * 24 hours) when rollup is null or less than PT1M (1 minute).

  • Maximum window size is 400 days (400 * 24 hours) when rollup is greater than or equal to PT1M (1 minute).

  • No maximum window size if rollup is window.

The limits are used internally by the Clarify API. Should you have very high resolution data (>=1hz), you can use time_window argument to reduce the window, resulting in more requests.

Examples

>>> client = Client("./clarify-credentials.json")

Getting a single item.

>>> item = ItemAggregation(
...     id="cbpmaq6rpn52969vfl00",
...     aggregation="max",
...     alias="i1"
... )
>>> r = client.evaluate(items=[item1], rollup="PT10M")
>>> print(r.result.data.to_pandas())
...                             i1
... 2023-10-20 10:20:00+00:00  6.0
... 2023-10-20 10:30:00+00:00  9.0
... 2023-10-20 10:40:00+00:00  8.0

Getting a single item in a time range.

>>> r = client.evaluate(items=[item1], gte="2022-08-10T00:00:00Z", lt="2022-08-30T00:00:00Z", rollup="PT10M")
>>> print(r.result.data.to_pandas())
...                             i1
... 2022-08-10 09:50:00+00:00  8.0
... 2022-08-10 10:00:00+00:00  9.0
... 2022-08-25 11:30:00+00:00  8.0
... 2022-08-30 15:10:00+00:00  2.0
... 2022-08-30 15:20:00+00:00  9.0
... 2022-08-30 15:30:00+00:00  9.0

Using a calculation on a single item.

>>> calc = Calculation(
...     formula="i1**2",
...     alias="power2"
... )
>>> r = client.evaluate(items=[item1], calculations=[calc], rollup="PT10M")
>>> print(r.result.data.to_pandas())
...                             i1  power2
... 2023-10-20 10:20:00+00:00  6.0    36.0
... 2023-10-20 10:30:00+00:00  9.0    81.0
... 2023-10-20 10:40:00+00:00  8.0    64.0

Adding two items.

>>> item = ItemAggregation(
...     id="cbpmaq6rpn52969vfl0g",
...     aggregation="avg",
...     alias="i2"
... )
>>> calc = Calculation(
...     formula="i1 + i2",
...     alias="sumi1i2"
... )
>>> r = client.evaluate(items=[item1, item2], calculations=[calc], rollup="PT10M")
>>> print(r.result.data.to_pandas())
...                             i1   i2   sumi1i2
... 2023-10-20 10:20:00+00:00  6.0   3.0      9.0
... 2023-10-20 10:30:00+00:00  9.0   4.0     13.0
... 2023-10-20 10:40:00+00:00  8.0   4.0     12.0

You can limit the number of series to be returned by specifying aliases in the series parameter.

>>> r = client.evaluate(
...     items=[item1, item2],
...     calculations=[calc],
...     rollup="PT10M",
...     series=["sumi1i2"]
... )
>>> print(r.result.data.to_pandas())
...                            sumi1i2
... 2023-10-20 10:20:00+00:00      9.0
... 2023-10-20 10:30:00+00:00     13.0
... 2023-10-20 10:40:00+00:00     12.0

Chaining calculations.

>>> calc1 = Calculation(
...     formula="i1 + i2",
...     alias="sum"
... )
>>> calc2 = Calculation(
...     formula="i1/sum",
...     alias="ratei1"
... )
>>> calc2 = Calculation(
...     formula="floor(ratei1*100)",
...     alias="ratio"
... )
>>> r = client.evaluate(
...     items=[item1, item2],
...     calculations=[calc1, calc2, calc3],
...     rollup="PT10M",
...     series=["i1", "i2", "ratio"]
... )
>>> print(r.result.data.to_pandas())
...                             i1   i2  ratio
... 2023-10-20 10:20:00+00:00  6.0  3.0   66.0
... 2023-10-20 10:30:00+00:00  9.0  4.0   69.0
... 2023-10-20 10:40:00+00:00  8.0  4.0   66.0