C3 AI Documentation Home

Time Series Declaration Metric

Raw data not modeled as a Timeseries must be converted and used in a metric.

Below are several types of raw data that must be converted.

  • event data
  • status data
  • non-continuous data, such as data generated from an outage event — which are random and last for minutes to hours at a time
  • status data that indicate if and when equipment is on or off

Metrics for this type of data are a special kind of Simple Metric called a tsDecl metric.

Differences from standard simple metric

The normalization process for the standard metric is defined by the time series data model that describes to the data the metric is analyzing, whereas a tsDecl metric defines the normalization process in the metric itself, and a time series is created at run-time.

In a standard metric, the path field should traverse from the SourceType to the IntervalDataHeader Type. From there, the expression references the fields on the IntervalDataHeader Type, normally in the form of normalized.data.value.

In a tsDecl metric, the path should lead from the SourceType to a Type that has a direct reference to an array of collection Types. This collection Type is not required to be a time series Type. It can be an entity Type that data has been loaded into.

This difference exists because in a standard metric, there is a C3 Type (often IntervalDataHeader) between the data points and the SourceType.

For example, from the SourceType, there is usually a field called measurements that references an array of IntervalDataHeaders. However, in the use case of tsDecl metrics, the array of CollectionTypes exists directly on the SourceType, so the TSDecl data field should lead to that collection that is being used to create a normalized time series from.

More information about Simple Metrics can be found here SimpleMetric.

tsDecl definition

Below are a few key fields within the tsDecl object in the metric definition:

  • data (string) — Value of this field should always yield in a field at the end of the path that is a foreign-key array containing the timed data points
  • treatment (string) — Indicates how to convert data points to time-series data. It specifies the kind of treatment applied for aggregation or disaggregation on the data for metric creation and also for normalization. See Treatment for options.
  • start (string) — Start date expression on the data points
  • end (string) — End date expression on the data points (optional in case of point data)
  • value (string) — Expression on the data points (optional). Multiple options are supported:
    • Convert something like a string or a status into a number that can be aggregated into a time series.
    • Value that can be carried out throughout the time series
    • A value directly from a field on the collection type
    • The value is left undefined or empty if the treatment determines the value to be returned. (For example the COUNT AggOp)
  • filter (string) — Filter to be applied on the data points (optional)
  • transform (string) — Transformation applied on the value expression (optional)
    • Typical to fill missing with this step
  • overlapHandling (string) — Indicates how to handle overlap data points when converting to a time series. Options are AVG, MIN, MAX, SUM and default is AVG
  • rollupFunc (string) — Indicates how to aggregate across space individual time series constructed at the end of path using the time series declaration. Options are OR, AND, SUM, AVG, MIN, MAX, MEAN, MEDIAN, VARIANCE, STDDEV. Default is null and all the data points for all end of path objects can be fed into a single time series

Mapping simple metrics to tsDecl metrics

In SimpleMetric an expression (string) is described below:

Type
"avg(avg(normalized.data.power))"
  • The outside avg and normalized keywords are the treatment(string) correlating to the aggregation over time and aggregation applied during normalization.
  • The data (string) property is the analogous field in TSDecl Metrics. This collection type has a datetime and values.
  • The power property is a value (string). It is the value you are looking at or setting.

An example of discontinuous point events

The example below uses the treatment OR to check for a value of the boolean status of 1 or 0 to determine if the bulb is working.

JSON
{
  "id": "WorkLogEvent_SmartBulb",
  "name": "WorkLogEvent",
  "description": "Status (1 or 0) indicating if the smart bulb has a work log event",
  "srcType": "SmartBulb",
  "tsDecl": {
    "treatment": "OR",
    "data": "bulbWorkLogs",
    "value": "1",
    "start": "timestamp"
  }
}

An example of continuous enumerated

The example below uses PREVIOUS to check for a value of the status of 1 or 0 to determine if the PowerGrid is on or off.

JSON
{
  "id": "PowerGridStatus_SmartBulb",
  "name": "PowerGridStatus",
  "description": "Status (1 or 0) indicating ON or OFF of the PowerGrid over time",
  "srcType": "SmartBulb",
  "path": "fixtureHistory.to.apartment.building",
  "tsDecl": {
    "treatment": "PREVIOUS",
    "data": "gridStatusSet",
    "value": "value",
    "start": "timestamp"
  }
}

See also

Was this page helpful?