clarify.evaluate

Require access to Clarify namespace

For an integration to access this method, it must have been granted access to the Clarify namespace.

A data method for aggregating time-series data and perform evaluate formula expressions.

Method parameters

Parameter	Properties	Description
items array(Item aggregation)	default=[]	List of item aggregations.
calculations array(Calculation)	default=[]	List of calculations.
data Data query	default={}	Data query to filter/aggregate the returned data framerollup-required.
include array(string("item"))	default=[]	Relationships to include.
format Selection format	default={"dataAsArray":false,"groupIncludedByType":false}	Configure result format.

Item aggregation

Item aggregation describe a particular aggregation method for an item.

Field	Description
id Item ID	Item to aggregate.
aggregation Data aggregation	Aggregation method.
state integer([0:9999])	State value for state-histogram aggregation methods.
lead integer([-1000:1000])	Shift buckets backwards by N.bucket-offset
lag integer([-1000:1000])	Shift buckets forwards by N.bucket-offset
alias Alias	A short alias to use in formulas as well as in the data frame results.

Calculation

A calculation has access to items and previous calculations in context.

Field	Description
formula Calculation formula	A calculation formula.
alias Alias	A short alias to use in formulas as well as in the data frame results.

Result

The result contains a data frame with aggregated and evaluated time-series data, as well as side-loaded item meta-data if requested.

type: object

Field	Description
meta Selection meta	Selection meta data.
data Data frame,array(Data frame)	A matrix view of selected/aggregated data points.
included array(resource),map(string => array(resource))	Side-loaded resources from relationships.

Limits

Items:

• items:

  • You are limited to reference 50 unique item IDs.

Calculations:

• calculations:

  • You are limited to list 100 calculations.
  • Each formula is limited to 1000 characters.

Data query:

• data.filter.times:

  • Maximum window size is:
    • 40 days (40 * 24 hours) when rollup is less than PT1M (1 minute).
    • 400 days (400 * 24 hours) whenrollup is greater than or equal to PT1M (1 minute).
    • 1900 days (1900 * 24 hours) whenrollup is greater than or equal to PT24H (24 hours).
    • Without limit when rollup is window.

• data.filter.times.$gte:

  • Defaults to $lt - 14 days when $lt is set.
  • Defaults to now - 7 days otherwise.

• data.filter.times.$lt:

  • Defaults to $gte + 14 days.

Example

cURL

The curl example uses Basic Auth for simplicity.

curl -u ${BASIC_AUTH_USERNAME}:${BASIC_AUTH_PASSWORD} \
  --request POST \
  --url 'https://api.clarify.io/v1/rpc' \
  --header 'content-type: application/json' \
  --header 'X-API-Version: 1.1' \
  --data \
  '
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "clarify.evaluate",
    "params": {
      "items": [
        {
          "id": "ci3eqq0bi2apjoiemb20",
          "alias": "i1",
          "aggregation": "avg",
          "lead": 1
        },
        {
          "id": "ci3eqq0bi2apjoiemb2g",
          "alias": "i2",
          "aggregation": "sum",
          "lag": 1
        },
        {
          "id": "ci3eqq0bi2apjoiemb30",
          "alias": "i3",
          "aggregation": "sum"
        }
      ],
      "calculations": [
        {
          "formula": "gapfill(i2) + i3",
          "alias": "c1"
        },
        {
          "formula": "i1 / c1",
          "alias": "c2"
        }
      ],
      "data": {
        "rollup": "P1D",
        "timeZone": "UTC",
        "firstDayOfWeek": 1,
        "filter": {
          "times": {
            "$gte": "2023-06-15T00:00:00Z",
            "$lt": "2023-06-20T00:00:00Z"
          },
          "series": {
            "$in": [
              "i1",
              "i2",
              "i3",
              "c1",
              "c2"
            ]
          }
        }
      }
    }
  }
  '

Python

from datetime import timedelta
from pyclarify import Client, ItemAggregation, Calculation

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

items = [
    ItemAggregation(
        id="ci3eqq0bi2apjoiemb20",
        alias="i1",
        aggregation="avg",
        lead=1
    ),
    ItemAggregation(
        id="ci3eqq0bi2apjoiemb2g",
        alias="i2",
        aggregation="sum",
        lag=1
    ),
    ItemAggregation(
        id="ci3eqq0bi2apjoiemb30",
        alias="i3",
        aggregation="sum"
    )
]
calculations = [
    Calculation(formula="gapfill(i2) + i3", alias="c1"),
    Calculation(formula="i1 / c1", alias="c2")
]


r = client.evaluate(
    items=items,
    calculations=calculations,
    rollup=timedelta(days=1),
    timeZone="UTC",
    firstDayOfWeek=1,
    gte="2023-06-15T00:00:00Z",
    lt="2023-06-20T00:00:00Z",
    series=["i1", "i2", "i3", "c1", "c2"],
)

data = r.result.data

Go

package main

import (
    "context"
    "encoding/json"
    "os"
    "time"

    clarify "github.com/clarify/clarify-go"
    "github.com/clarify/clarify-go/fields"
)

func main() {
    // NOTE: To select item data or meta-data, you must grant the integration
    // access to the "clarify" namespace in the Clarify admin panel.
    creds, err := clarify.CredentialsFromFile("clarify-credentials.json")
    if err != nil {
        panic(err)
    }

    ctx := context.Background()
    client := creds.Client(ctx)

    t1 , _ := time.Parse("2023-06-15T00:00:00Z", time.RFC3339Nano)
    t2 , _ := time.Parse("2023-06-20T00:00:00Z", time.RFC3339Nano)

    data := fields.Data().
        Where(fields.TimeRange(t1, t2)).
        RollupDuration(24*time.Hour, time.Monday)

    items := []fields.ItemAggregation{
        {Alias: "i1", ID: "ci3eqq0bi2apjoiemb20", Aggregation: fields.AggregateAvg},
        {Alias: "i2", ID: "ci3eqq0bi2apjoiemb2g", Aggregation: fields.AggregateSum},
        {Alias: "i3", ID: "ci3eqq0bi2apjoiemb30", Aggregation: fields.AggregateSum},
    }
    calculations := []fields.Calculation{
        {Alias: "c1", Formula: "gapfill(i2) + i3"},
        {Alias: "c2", Formula: "i1 / c1"},
    }

    result, err := client.Clarify().Evaluate(items, calculations, data).Do(ctx)
    if err != nil {
        panic(err)
    }
    enc := json.NewEncoder(os.Stdout)
    enc.SetIndent("", "  ")
    enc.Encode(result)
}

Results:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "meta": {
      "total": 5,
      "format": {
        "groupIncludedByType": false,
        "dataAsArray": false
      }
    },
    "data": {
      "times": [
        "2023-06-15T00:00:00Z",
        "2023-06-16T00:00:00Z",
        "2023-06-17T00:00:00Z",
        "2023-06-18T00:00:00Z",
        "2023-06-19T00:00:00Z"
      ],
      "series": {
        "c1": [192, 192, 192, 192, 192],
        "c2": [
          0.36262936708726135, 0.2654939498258671, -0.4030798814736652,
          -0.26349481692193893, 0.407358729183466
        ],
        "i1": [
          69.62483848075418, 50.97483836656648, -77.39133724294372,
          -50.59100484901228, 78.21287600322547
        ],
        "i2": [72, 72, 72, 72, 72],
        "i3": [120, 120, 120, 120, 120]
      }
    }
  }
}

---

1. The data.rollup property must be set to window or an RFC3339 duration string for this request.↩
2. The final bucket offset to use is calculated as lead - lag, and must be in range [-1000:1000].↩