How to use results
[bt_bb_section layout=”boxed_1200″ lazy_load=”yes” show_boxed_content=”no” allow_content_outside=”no”][bt_bb_row][bt_bb_column lazy_load=”yes” highlight=”no” align_to_edge_column=”no” width=”1/1″][bt_bb_text]
The recommended way to use AnalyticsOS results is to pull results from the RESTful API on a schedule and save them into a local database. Applications using AnalyticsOS results can then query the local database directly and provide better performance with less network latency.
1.1 Time filtering
All RESTful API result endpoints support time filtering, so it’s simple to check the timestamp of the last result saved in the local database and only request newer results not yet saved.
1.2 Analytic identifiers
The analytic results exposed by AnalyticsOS Cloud utilize node identifiers so users can locate values of interest. For example, a user might get the following two calculations inside the cdf_results JSON Array. They might belong to the same evaluation batch, but it’s the node identifier which specifies what calculation the values belong to.
| [
{ “node”: “Pump B Suction Pressure”, “result_10”: 42.2, “result_30”: 43.0, “result_50”: 43.1, “result_70”: 43.5, “result_90”: 44.1, “units”: “PSI” }, { “node”: “Motor A Temperature above Ambient”, “result_10”: 10.5, “result_30”: 11.2, “result_50”: 12.1, “result_70”: 13.5, “result_90”: 14.9, “units”: “Degrees Celsius” } ] |
After persisting them to a cdf_results database table, one could query for all “Pump B Suction Pressure” rows to produce a historical view of the calculations for suction pressure. The node identifier is also used to differentiate mofn_alerts and prediction outputs.
Detailed examples of how to use each class of analytics result are given on subsequent pages:
- Predictions
- Alerts
- Calculations
1.3 Predictions
1.3.1 Overview
AnalyticsOS provides predictions based off of sensor values and computed values. These can be represented in several ways to show the relevant uncertainty as well as prescriptions for system remediation.
1.3.2 Vocabulary
Thresholds: At what point is the data in a range where a user should be notified?
Predictions work by estimating when data will go above a defined value or below a defined value. These are called upper thresholds and lower thresholds.
Lead time: How much notice does a user need before the measurement crosses the significant threshold?
Predictions are only produced if the threshold will be crossed within the time the user is interested. If the prediction algorithms see that the threshold will be crossed in 3 weeks, but the lead time is set to 2 weeks, then no prediction is produced.
Prediction CDF: Predictions with uncertainty
The prediction JSON contains a predictive_threshold_cdf_result array which contains the 10th, 50th, and 90th percentiles of the prediction. The 10th and 90th percentile provide AnalyticsOS’ prediction of the soonest and latest that the value will cross the defined threshold, and the 50th percentile is in the middle.
The uncertainty cone in the picture above shows how AnalyticsOS will forecast how high or low the value might be in the future. This is why the 10th, 50th, and 90th percentile predictions are produced.
1.3.3 Example: Motor overheating
The following JSON is an example of one prediction output for motor temperature (one analytics solution might also include other predictions for vibration or current distortion, for example).
| {
‘lead_time_message’: ‘Motor temperature is projected to exceed safe operating temperature, turn off and inspect coolant tank for leak.’, ‘node’: ‘Motor Temperature’, ‘predictive_threshold_cdf_result’: [{ ‘result_prediction_time_delta’: 3500000, ‘result_state’: 4, ‘result_state_name’: ‘CROSSING_IMMINENT’, ‘result_timestamp_prediction’: 1562945506952, ‘threshold_analysis_point’: ’10’, ‘threshold_analysis_point_value’: 509.9 }, { ‘result_prediction_time_delta’: 3600000, ‘result_state’: 4, ‘result_state_name’: ‘CROSSING_IMMINENT’, ‘result_timestamp_prediction’: 1562945606952, ‘threshold_analysis_point’: ’50’, ‘threshold_analysis_point_value’: 509.9 }, { ‘result_prediction_time_delta’: 3700000, ‘result_state’: 4, ‘result_state_name’: ‘CROSSING_IMMINENT’, ‘result_timestamp_prediction’: 1562945706952, ‘threshold_analysis_point’: ’90’, ‘threshold_analysis_point_value’: 509.9 }, { ‘result_prediction_time_delta’: 3600000, ‘result_state’: 4, ‘result_state_name’: ‘CROSSING_IMMINENT’, ‘result_timestamp_prediction’: 1562945606952, ‘threshold_analysis_point’: ‘gross_estimation’, ‘threshold_analysis_point_value’: 509.9 } ], ‘threshold_name’: ‘Motor Temperature’, ‘threshold_type’: ‘upper_threshold’, ‘threshold_value’: 550.0, ‘units’: ‘Degrees F’ } |
Note:
There are four predictions provided in the predictive_threshold_cdf_result array: the 10th percentile, 50th percentile, the 90th percentile, and the ‘gross_estimation’. The 10/50/90 percentile forecasts are only available when a prediction is being produced (threshold cross is expected within the configured lead time). The gross estimation is a longer forecast which is always available, but because it looks farther out it can be more volatile than the other predictions.
It is provided only so users can have a rough approximation of how far the threshold cross is if all of the other predictions are far away and not yet providing a date. The below sections show how different visualizations could be produced all using this data.
Latest prediction
To simply show the latest prediction, one can take the greatest and least result_timestamp_prediction from the 10, 50, and 90 JSON blocks in the predictive_threshold_cdf_result array.
This would produce the ms since epoch times 1562945706952 and 1562945506952 in the JSON example above. This can then be converted to human-friendly formats and presented as a range, e.g. “Between 10:31 AM and 10:35 AM on July 12, 2019”
Prediction history
To view predictions over time it’s possible to query the 10, 50, and 90th percentiles as 3 separate series in the same line chart. This shows the soonest and latest that the threshold is expected to be crossed, as well as the 50th percentile in the middle.
The schema to support this example relies on the 10, 50, and 90 predictions (the elements in the predictive_threshold_cdf_result array) to be saved off to their own relational database table. Then they can be queried and filtered as needed.
| SELECT pt.timestamp_evaluation_end AS “time”, ptcdf.result_prediction_time_delta/(1000*60.0) as “Soonest expected”
FROM predictivethreshold_result_data pt left outer join predictive_threshold_cdf_result ptcdf on pt.id = ptcdf.predictivethreshold_result_data WHERE $__timeFilter(timestamp_evaluation_end) and ptcdf.threshold_analysis_point = ’90’ ORDER BY 1 |
1.4 Alerts
1.4.1 Overview
AnalyticsOS can create alerts if sensor values or computed values occur in concerning ranges.
This analysis is performed by checking what percentage of values fell in the alarm range. In some situations, a few samples in the alarm range are acceptable, but if too many are there then an alert is produced.
1.4.2 Example: Pump Discharge Pressure
The below JSON is an example of what AnalyticsOS produces when an alert is created.
Note: This is just the alert portion of the largest eval-manifest JSON GET response.
| {
‘node’: ‘Pump Discharge Pressure’, ‘result_percentage’: 89.7, ‘rule_left_inclusive’: True, ‘rule_left_value’: 10.0, ‘rule_message’: ‘Pump temperature observed much higher than ambient. Shut down pump and inspect for leak.’, ‘rule_percentage’: 20.0, ‘rule_right_inclusive’: False, ‘rule_right_value’: 500.0, ‘rule_set’: ‘Pump discharge pressure alert’, ‘units’: ‘PSI’ } |
Table
After saving alerts to a table with the same columns as the JSON above it is simple to query the table and show a list of alerts as shown below.
If only certain alerts are desired, then it’s possible to filter on the ‘node’ field, which is unique to each alert.
Note: The JSON above does not include a timestamp because the timestamp for all predictions, alerts, and calculations are at the evaluation manifest level of the JSON. For more information on the structure of the full JSON structure refer to the Analytics Results v1 page.
1.5 Calculations
1.5.1 Overview
AnalyticsOS provides calculations using distributions. This describes the variation observed during each window of data processed. The CDF output exposed by the Analytics Results API include the following values for every analytic:
| {
“node”: “Motor A Temperature above Ambient”, “result_10”: 10.5, “result_30”: 11.2, “result_50”: 12.1, “result_70”: 13.5, “result_90”: 14.9, “units”: “Degrees Celsius” } |
These represent the different points from the cumulative distribution function5of the value in question. The 10th
percentile is the result_10, the median value is the result_50, and the minimum and maximum values observed are result_min and result_max respectively.
1.5.2 Example: Pump Flow Rate
For an analytics solution monitoring a pump, one sensor might be recording the flow rate. In this example there are several ways to represent the calculations produced by AnalyticsOS.
Latest value
The simplest is just to show the latest result_50 value, which is the median value from the last evaluation.
Time series graph
To show the value of the calculation over time, a simple line chart can be used. In this example the result_10 and result_90 lines are also included to show the variation observed over time.
[/bt_bb_text][/bt_bb_column][/bt_bb_row][/bt_bb_section]