KPI Calculation Service - Samples - Developer Documentation - Developer Documentation
Skip to content

KPI Calculation Service – Samples

Calculating KPIs

This sample provides a generic procedure for computing common KPIs. The input is a sequence of events labeled with the following five State KPIs:

  • NoData (or Unknown) - no data hours
  • SH - service hours
  • RSH - reserve shutdown hours
  • POH - planned outage hours
  • FOH - forced outage hours

These events divide the time line into non-overlapping time intervals, with each interval being assigned exactly Hour KPI label. This property allows a simple computation procedure with the following input and output:

Input Parameter Description
<From-Date,To-Date> Period of interest
initialState Initial state from {NoData, SH, RSH, POH, FOH}
<Timestamp[i],StateKPI[i]> Sequence of events, where each StateKPI[i] is from {Unknown, SH, RSH, POH, FOH}

Output:

KPI Computation Procedure

Use the following endpoint for the KPI calculation:

/api/kpicalculation/v3/computekpi

Example request:

/api/kpicalculation/v3/computekpi?from=2017-05-03T23:30:00.000Z&to=2017-05-04T08:30:00.000Z&variableName=kpistatus&initialState=RSH
Request body 
[
    {
        "_time":"2017-05-04T00:00:00.000Z"
    },
    {
        "_time":"2017-05-04T00:30:00.000Z"
    },
    {
        "_time":"2017-05-04T01:00:00.000Z",
        "kpistatus":"UNKNOWN"
    },
    {
        "_time":"2017-05-04T01:30:00.000Z",
        "kpistatus":"UNKNOWN"
    },
    {
        "_time":"2017-05-04T02:00:00.000Z",
        "kpistatus":"UNKNOWN"
    },
    {
        "_time":"2017-05-04T02:30:00.000Z",
        "kpistatus":"SH"
    },
    {
        "_time":"2017-05-04T03:00:00.000Z",
        "kpistatus":"SH"
    },
    {
        "_time":"2017-05-04T03:30:00.000Z",
        "kpistatus":"POH"
    },
    {
        "_time":"2017-05-04T04:00:00.000Z",
        "kpistatus":"SH"
    },
    {
        "_time":"2017-05-04T04:30:00.000Z",
        "kpistatus":"SH"
    },
    {
        "_time":"2017-05-04T05:00:00.000Z",
        "kpistatus":"POH"
    },
    {
        "_time":"2017-05-04T05:30:00.000Z"
    },
    {
        "_time":"2017-05-04T06:00:00.000Z"
    },
    {
        "_time":"2017-05-04T06:30:00.000Z",
        "kpistatus":"UNKNOWN"
    },
    {
        "_time":"2017-05-04T07:00:00.000Z",
        "kpistatus":"FOH"
    },
    {
        "_time":"2017-05-04T07:30:00.000Z",
        "kpistatus":"FOH"
    },
    {
        "_time":"2017-05-04T08:00:00.000Z",
        "kpistatus":"POH"
    }
]

Example Response:

Response 
{
    "unknownHours": 2,
    "periodHours": 9,
    "availableHours": 3.5,
    "serviceHours": 2,
    "reserveShutdownHours": 1.5,
    "unavailableHours": 3.5,
    "forcedOutageHours": 1,
    "plannedOutageHours": 2.5,
    "availabilityFactor": 50,
    "unavailabilityFactor": 50,
    "reliabilityFactor": 85.71428571428571,
    "serviceFactor": 28.57142857142857,
    "forcedOutageFactor": 14.285714285714285,
    "meanTimeBetweenFailures": 1
}

Determining Unit States from Sensor and Calendar Data

This sample provides a generic procedure for determining the State of a motor with a speed sensor and a maintenance calendar. These are required as input for the automatic KPI calculation.

Motor with Speed Sensor and Maintenance Calendar

For determining the State KPI states, certain conditions must be fulfilled. This allows a computational procedure with the following input and output:

Input Parameter Description
<From-Date,To-Date> Period of interest
initialState Initial state from {Unknown, SH, RSH, POH, FOH}
defaultState Default state from {RSH, FOH}, used if no sensor and calendar data is available
R[i] = <Timestamp[i],S[i]> Sequence of sensor readings, where each S[i] is a real number.
SIT Service indication threshold
PO[m] = <Start-Date[m],End-Date[m]> Calendar with start and end times for planned outages

Output:

KPI State Calculation

Request example:

/api/kpicalculation/v3/calculatekpistates?from=2016-12-31T23:30:00.000Z&to=2017-01-01T07:30:00.000Z&variableName=sensor&initialState=RSH&defaultState=FOH&threshold=1.1&shutdownCorrelationThreshold=5000
Request body 
{
"calendar": {
    "PlannedOutage": [
      {
        "from": "2017-01-01T10:00:00.000Z",
        "to": "2017-01-01T11:00:00.000Z"
      },
      {
        "from": "2017-01-01T06:00:00.000Z",
        "to": "2017-01-01T07:00:00.000Z"
      },
      {
        "from": "2017-01-01T00:00:00.000Z",
        "to": "2017-01-01T01:00:00.000Z"
      },
      {
        "from": "2017-01-01T04:00:00.000Z",
        "to": "2017-01-01T05:00:00.000Z"
      },
      {
        "from": "2017-01-01T02:00:00.000Z",
        "to": "2017-01-01T03:00:00.000Z"
      },
      {
        "from": "2017-01-01T08:00:00.000Z",
        "to": "2017-01-01T09:00:00.000Z"
      },
      {
        "from": "2016-12-31T22:00:00.000Z",
        "to": "2016-12-31T23:00:00.000Z"
      },
      {
        "from": "2017-01-01T03:00:00.000Z",
        "to": "2017-01-01T04:00:00.000Z"
      }
    ]
  },
  "timeseries": [
    {
      "_time": "2017-01-01T00:10:00.000Z",
      "sensor": "2.0",
      "sensor1": "2.0"
    },
    {
      "_time": "2017-01-01T00:50:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T01:00:00.000Z",
      "sensor": "2.0"
    },
    {
      "_time": "2017-01-01T01:30:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T02:00:00.000Z",
      "sensor": "2.0"
    },
    {
      "_time": "2017-01-01T03:00:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T03:30:00.000Z",
      "sensor": "2.0"
    },
    {
      "_time": "2017-01-01T04:30:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T05:10:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T05:30:00.000Z",
      "sensor1": "1.0"
    },
    {
      "_time": "2017-01-01T05:50:00.000Z",
      "sensor": "2.0"
    },
    {
      "_time": "2017-01-01T06:30:00.000Z",
      "sensor2": "3.0"
    },
    {
      "_time": "2017-01-01T07:10:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T07:20:00.000Z",
      "sensor": "2.0"
    }
  ]
}
Response 
{
    "indications": [
        {
            "timestamp": "2016-12-31T23:30:00Z",
            "status": "RSH",
            "source": "DEFAULT"
        },
        {
            "timestamp": "2017-01-01T00:00:00Z",
            "status": "POH",
            "source": "CALENDAR"
        },
        {
            "timestamp": "2017-01-01T01:00:00Z",
            "status": "SH",
            "source": "SIGNAL"
        },
        {
            "timestamp": "2017-01-01T01:30:00Z",
            "status": "FOH",
            "source": "DEFAULT"
        },
        {
            "timestamp": "2017-01-01T02:00:00Z",
            "status": "POH",
            "source": "CALENDAR"
        },
        {
            "timestamp": "2017-01-01T03:00:00Z",
            "status": "POH",
            "source": "CALENDAR"
        },
        {
            "timestamp": "2017-01-01T04:00:00Z",
            "status": "POH",
            "source": "CALENDAR"
        },
        {
            "timestamp": "2017-01-01T05:00:00Z",
            "status": "FOH",
            "source": "DEFAULT"
        },
        {
            "timestamp": "2017-01-01T05:10:00Z",
            "status": "FOH",
            "source": "DEFAULT"
        },
        {
            "timestamp": "2017-01-01T05:30:00Z",
            "status": "FOH",
            "source": "DEFAULT"
        },
        {
            "timestamp": "2017-01-01T05:50:00Z",
            "status": "SH",
            "source": "SIGNAL"
        },
        {
            "timestamp": "2017-01-01T06:00:00Z",
            "status": "POH",
            "source": "CALENDAR"
        },
        {
            "timestamp": "2017-01-01T07:00:00Z",
            "status": "SH",
            "source": "SIGNAL"
        },
        {
            "timestamp": "2017-01-01T07:10:00Z",
            "status": "FOH",
            "source": "DEFAULT"
        },
        {
            "timestamp": "2017-01-01T07:20:00Z",
            "status": "SH",
            "source": "SIGNAL"
        },
        {
            "timestamp": "2017-01-01T07:30:00Z",
            "status": "SH",
            "source": "SIGNAL"
        }
    ]
}

Determining Unit States from Sensor, Control Unit and Calendar Data

This sample provides a generic procedure for determining the State of a compressor with a pressure sensor, events from the compressor control unit and a maintenance calendar.

Compressor with Pressure Sensor, Control Unit Events and Maintenance Calendar

For determining the State KPI states, certain conditions must be fulfilled. This allows a computational procedure with the following input and output:

Input Parameter Description
<From-Date,To-Date> Period of interest
initialState Initial state from {Unknown, SH, RSH, POH, FOH}
defaultState Default state from {RSH, FOH}, used if no sensor, control unit and calendar data is available
R[i] = <Timestamp[i],S[i]> Sequence of sensor readings, where S[i] is a real number.
SIT Service indication threshold
E[k]=<Timestamp[k], L[k]> Sequence of events with labels, with L[k] from {NormalStop, Shutdown}
SCT Shutdown correlation threshold
PO[m] = <Start-Date[m],End-Date[m]> Calendar with start and end times for planned outages

Output:

Request example:

{HOST}/calculatekpistates?from=2016-12-31T23:30:00.000Z&to=2017-01-01T07:30:00.000Z&variableName=sensor&initialState=RSH&defaultState=FOH&threshold=1.1&shutdownCorrelationThreshold=5000
Request body 
{
  "ControlSystemEvents": [
    {
      "_time": "2017-01-01T01:29:57.000Z",
      "type": "NORMAL_STOP"
    },
    {
      "_time": "2017-01-01T01:30:00.000Z",
      "type": "SHUTDOWN"
    },
    {
      "_time": "2017-01-01T04:30:01.000Z",
      "type": "SHUTDOWN"
    }
  ],
  "calendar": {
    "PlannedOutage": [
      {
        "from": "2017-01-01T10:00:00.000Z",
        "to": "2017-01-01T11:00:00.000Z"
      },
      {
        "from": "2017-01-01T06:00:00.000Z",
        "to": "2017-01-01T07:00:00.000Z"
      },
      {
        "from": "2017-01-01T00:00:00.000Z",
        "to": "2017-01-01T01:00:00.000Z"
      },
      {
        "from": "2017-01-01T04:00:00.000Z",
        "to": "2017-01-01T05:00:00.000Z"
      },
      {
        "from": "2017-01-01T02:00:00.000Z",
        "to": "2017-01-01T03:00:00.000Z"
      },
      {
        "from": "2017-01-01T08:00:00.000Z",
        "to": "2017-01-01T09:00:00.000Z"
      },
      {
        "from": "2016-12-31T22:00:00.000Z",
        "to": "2016-12-31T23:00:00.000Z"
      },
      {
        "from": "2017-01-01T03:00:00.000Z",
        "to": "2017-01-01T04:00:00.000Z"
      }
    ]
  },
  "timeseries": [
    {
      "_time": "2017-01-01T00:10:00.000Z",
      "sensor": "2.0",
      "sensor1": "2.0"
    },
    {
      "_time": "2017-01-01T00:50:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T01:00:00.000Z",
      "sensor": "2.0"
    },
    {
      "_time": "2017-01-01T01:30:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T02:00:00.000Z",
      "sensor": "2.0"
    },
    {
      "_time": "2017-01-01T03:00:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T03:30:00.000Z",
      "sensor": "2.0"
    },
    {
      "_time": "2017-01-01T04:30:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T05:10:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T05:30:00.000Z",
      "sensor1": "1.0"
    },
    {
      "_time": "2017-01-01T05:50:00.000Z",
      "sensor": "2.0"
    },
    {
      "_time": "2017-01-01T06:30:00.000Z",
      "sensor2": "3.0"
    },
    {
      "_time": "2017-01-01T07:10:00.000Z",
      "sensor": "1.0"
    },
    {
      "_time": "2017-01-01T07:20:00.000Z",
      "sensor": "2.0"
    }
  ]
}
Response 
{
    "indications": [
        {
            "timestamp": "2016-12-31T23:30:00Z",
            "status": "RSH",
            "source": "DEFAULT"
        },
        {
            "timestamp": "2017-01-01T00:00:00Z",
            "status": "POH",
            "source": "CALENDAR"
        },
        {
            "timestamp": "2017-01-01T01:00:00Z",
            "status": "SH",
            "source": "SIGNAL"
        },
        {
            "timestamp": "2017-01-01T01:30:00Z",
            "status": "RSH",
            "source": "NORMAL_STOP"
        },
        {
            "timestamp": "2017-01-01T02:00:00Z",
            "status": "POH",
            "source": "CALENDAR"
        },
        {
            "timestamp": "2017-01-01T03:00:00Z",
            "status": "POH",
            "source": "CALENDAR"
        },
        {
            "timestamp": "2017-01-01T04:00:00Z",
            "status": "POH",
            "source": "CALENDAR"
        },
        {
            "timestamp": "2017-01-01T05:00:00Z",
            "status": "FOH",
            "source": "SHUTDOWN"
        },
        {
            "timestamp": "2017-01-01T05:10:00Z",
            "status": "FOH",
            "source": "DEFAULT"
        },
        {
            "timestamp": "2017-01-01T05:30:00Z",
            "status": "FOH",
            "source": "DEFAULT"
        },
        {
            "timestamp": "2017-01-01T05:50:00Z",
            "status": "SH",
            "source": "SIGNAL"
        },
        {
            "timestamp": "2017-01-01T06:00:00Z",
            "status": "POH",
            "source": "CALENDAR"
        },
        {
            "timestamp": "2017-01-01T07:00:00Z",
            "status": "SH",
            "source": "SIGNAL"
        },
        {
            "timestamp": "2017-01-01T07:10:00Z",
            "status": "FOH",
            "source": "DEFAULT"
        },
        {
            "timestamp": "2017-01-01T07:20:00Z",
            "status": "SH",
            "source": "SIGNAL"
        },
        {
            "timestamp": "2017-01-01T07:30:00Z",
            "status": "SH",
            "source": "SIGNAL"
        }
    ]
}

Except where otherwise noted, content on this site is licensed under the Development License Agreement.

Last update: March 5, 2019