C3 AI Documentation Home

Compound Metrics

You can create increasingly complex data transformations by building compound metrics based on existing simple or compound metrics.

Unlike simple metrics, compound metrics are Typeless. This means that compound metrics apply to any Type, as long as the referenced input metrics are all defined for the same Type. Therefore, compound metrics don't need to have a source type or the path to traverse from one Type to another.

Compound metrics are instances of the C3 Type CompoundMetric.

Definition

There are three main fields on a compound metric:

  • id (string): Same as name. Convention: use "CamelCase" (ex: RollingAveragePower)
  • name (string): Convention: use "CamelCase" (ex: RollingAveragePower)
  • expression (string): Expression that must be evaluated
    • Other simple and compound metrics
    • Logical and mathematical operators from JavaScript (for example, +, -, *, /, &&, ||)
    • Any function available in ExpressionEngineFunction
    • Any function that mixes MetricFunctionLibrary

The source type that you defined for simple metrics types is not used for compound metrics. A compound metric does not have a source type.

Example

Assume two metrics:

  • A Simple Metric AveragePower defined on the Car Type
  • A Simple Metric with the same name, AveragePower, defined on boats

In this example, the compound metric takes the two assets and the average of the power value for both assets as input parameters.

Compound metrics

Note in the CompoundMetric definition there is no source type; this metric can be evaluated on the Car Type or the Boat Type.

Rolling operator for cumulative sum

The compound metric DurationOnInHours measures the total amount of time a light bulb is switched on measured in hours.

JSON
{
  "id": "DurationOnInHours",
  "name": "DurationOnInHours",
  "description": "The total amount of time a smart bulb is switched on in hours",
  "expression": "eval('AVG', 'HOUR', rolling('SUM', Status))"
}

Starting from the inner part of the definition, the metric makes use of an expression engine function called rolling.

rolling accepts a Timeseries object and performs a rolling aggregation based on the aggregation function specified.

In this example, the Timeseries is to be summed and aggregated by a simple metric called Status. Status presumably knows the status of a light bulb (whether it is on or off). This entire piece is nested in another expression engine function called eval. eval forces an evaluation of a the Timeseries based on the specified information.

In this case, the Timeseries Type produced by the rolling function can be evaluated at an HOUR intervals by averaging the values to get one point for each hour.

Was this page helpful?