C3 AI Documentation Home

Action Declaration Metrics

Action declaration metrics, or actionDecl metrics, are a Type of SimpleMetric that can be seen as action-based handling of a metric. actionDecl metrics are a special case of the SimpleMetric Type used to define custom actions or functions on a source Type.

Definition

There are two fields on actionDecl Metrics:

  • action (string): The action field is the name of the method that is invoked by this metric. As an example, the SpecialSum() method must be defined on the source Type using the syntax:
Type
SpecialSum: function(Obj obj, TSEvalSpec spec, SimpleMetric metric, userDefinedArg1: string, userDefinedArg2: string) : Timeseries

C3 AI recommends this use-case only during prototyping. No incremental invalidation occurs.

  • include (string): Specify the fields you want to include on the Obj passed to the action. This field is optional.

Upon evaluation of the metric, the platform software finds the Source Type, retrieves the action method and runs it. The action method returns a object of the Type Timeseries.

Limitations of actionDecl metrics

The actionDecl metrics cannot be optimized because of its customizable nature. This implies the metric evaluation can be slow. It is recommended to use actionDecl primarily for prototyping.

Example

Method declaration

The first step in creating an action declaration is declaring a custom method, for example, isSunUp, that can be called on the source Type. This method returns a Timeseries object that indicates if the sun is up or not.

In the SmartBulb Type definition, this method is defined just like a metric -- with defined input argument Types and a specified output Type to be of Type Timeseries. Two additional required parameters are specified: a TSEvalSpec, and a Metric Type, that is the base Type for Simple and Compound metrics.

For a JavaScript implementation, the definition looks like this:

Type
entity type SmartBulb extends LightBulb mixes MetricEvaluatable type key "SMRT_BLB" {
  /**
   * Returns a time series that indicates if the sun is up or not.
   */
  isSunUp: function(obj: Obj, spec: !TSEvalSpec, metric: !Metric): Timeseries js-server
  …
}

Method implementation

A JavaScript implementation below for the method isSunUp returns a time series indicating if the sun is up or not.

JavaScript
// SmartBulb.js
function calculateValue(hourOfDay, latitude) {
  return Math.abs(-Math.cos(Math.PI * 2 * hourOfDay / 24)) > Math.abs(latitude / 90) ? 1 : 0;
}

function isSunUp(obj, spec, metric) {
  var res = [];
  let currentDate = spec.start;
  res.push(calculateValue(currentDate.hourOfDay, obj.latitude));

  while (currentDate.isBefore(spec.end)) {
    currentDate = currentDate.plusHours(1);
    res.push(calculateValue(currentDate.hourOfDay, obj.latitude));
  }

  var timeseries = Timeseries.fromValues(TimeInfo.make({
    start: spec.start,
    end: spec.end,
    interval: "HOUR"
  }), res);
  
  return timeseries.toInterval(spec.interval, 'AVG');
}

Metric definition

Finally, define an Action Declaration Metric, similar to a traditional Simple Metrics and a Time Series Declaration Metric.

Note that, in this definition, there is no expression and instead, there is an actionDecl field. Within this field are the two fields – action and include. In the action field include the custom action – or the method isSunUp.

JSON
{
   "id": "SunIsUp_SmartBulb",
   "name": "SunIsUp",
   "description": "Status (1 or 0) indicating if the sun is up or not at that time",
   "srcType": "SmartBulb",
   "actionDecl": {
     "action": "isSunUp()",
     "include": "latitude"
   }
 }
Was this page helpful?