Analytics Results v1
[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]
AnalyticsOS℠ records all the analytics from one evaluation grouped by an Evaluation Manifest. This defines the parameters such as what model was used for analysis, what time window of data was processed, as well as which asset the analytics describe.
This data is exposed over a RESTful API, and extra parameters can also be specified to include analytics like predictions, alerts, and calculation summaries.
1.1.1 HTTPS Request
Request Field | Value |
URL | https://cloud.analyticsos.com/result-manager/api/v1/eval-manifest |
Request type | GET |
Authorization | Bearer Token |
1.1.2 HTTPS Request Parameters
Parameter | Data Format | Value | Optional | Default |
include_cdf | True / False | Should CDF results be included? | Yes | False |
include_predictions | True / False | Should prediction results be included? | Yes | False |
include_mofn | True / False | Should M-of-N results be included? | Yes | False |
start_timestamp_ms | Timestamp | Earliest desired timestamp | Yes | Null |
end_timestamp_ms | Timestamp | Latest desired timestamp | Yes | Null |
user_id | String | ID of User requesting data from | Yes | Null |
Note:
- If start_timestamp_ms is not provided, any records with timestamps before end_timestamp_ms will be returned.
- If end_timestamp_ms is not provided, any records with timestamps after start_timestamp_ms will be returned.
- If neither start_timestamp_ms nor end_timestamp_ms are provided, all records will be returned.
- Some API clients will have access to data for multiple users and user_id must be provided. If an API client is for a single user, then user_id may be omitted.
1.1.3 HTTPS Request Response Body Structure
{
“analytics_configuration_id”: “dbf3650f-53a7-48ff-8ca5-fd8555088eee”, “asset_configuration_id”: “d6475189-0b6a-4ab7-8436-58c1c48e6c89”, “asset_id”: “3db7d162-49f1-4309-b229-0a23a6e31ded”, “user_id”: “eabaf3a4-44d7-42e2-b7f5-f0c2e55b85b3”, “customer_id”: “9e9f6bf0-49c8-487a-a86f-89c2bb0c4f3c”, “id”: “b04b29c1-7c0d-49ea-8395-21b479799d64”, “model_id”: “9a838d64-9d02-4bb4-8014-88b340b85ce6”, “timestamp_evaluation_start”: 1473264435670.0, “timestamp_evaluation_end”: 1473264436670.0, “status”: “COMPLETED”, “cdf_results”: [], “mofn_alerts”: [], “predictions”: [] } |
Note:
The cdf_results, mofn_alerts, and predictions JSON arrays in the example above will contain JSON objects matching the structure defined in the Result Summary, M-of-N Alerts, and Intelligent Predictions sections respectively.
1.1.4 JSON Field descriptions
Analytics Config ID | analytics_configuration_id | Variable Character (200) | Unique Asset identifier |
Asset ID | asset_id | Variable Character (200) | Unique Asset identifier |
Model ID | model_id | Variable Character (200) | Unique Model identifier |
Asset Config ID | asset_configuration_id | Variable Character (200) | Unique Model identifier |
Customer ID | customer_id | Variable Character (200) | Unique Model identifier |
User ID | user_id | Variable Character (200) | Unique Model identifier |
Status | status | Variable Character (20) | Describes if the evaluation was successful or if there was an error |
Evaluation Start Timestamp | timestamp_evaluation_start | Timestamp | Time defined by the start of the current evaluation window |
Evaluation End Timestamp | timestamp_evaluation_end | Timestamp | Time defined by the end of the current evaluation window |
CDF Results | cdf_results | JSON Array | Array of result summaries of model calculations |
M-of-N Results | mofn_alerts | JSON Array | Array of M-of-N alerts |
Predictions | predictions | JSON Array | Array of Predictions |
Note:
The result REST API utilizes pagination if more records are found meeting the request filter than the
configured limit. Please see the Pagination page for more information.
1.1.5 Output – CDF Result Summary
Overview
Within an AOS model, each calculation step is referred to as a Node. The node name describes both the system being analyzed and a description of the parameter being calculated. Within an AOS model, node names are unique.
During the model definition process, any node can be flagged for export. The results of the calculation are saved in a stochastic summary format.
HTTPS Request Response CDF Result Body Structure
{
“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” } |
JSON Field descriptions
Node Result Field | JSON Key | Data Format | Description |
Node Name | node | Variable Character (200) | Calculation title within the AOS model |
Node Units | units | Variable Character (200) | Measurement units of the node’s value(ex. °C) |
10th Percentile | result_10 | Double | Precision 10th percentile calculated result value |
30th Percentile | result_30 | Double | Precision 30th percentile calculated result value |
50th Percentile | result_50 | Double | Precision 50th percentile calculated result value(median) |
70th Percentile | result_70 | Double | Precision 70th percentile calculated result value |
90th Percentile | result_90 | Double | Precision 90th percentile calculated result value |
1.1.6 Output – M-of-N Result Summary
Overview
M-of-N is a filter process that requires M samples of N population to be within an upper and lower threshold in order to trigger an event. Within AOS, M-of-N rules can be applied to any calculation node (including sensor nodes) to determine the system’s current state of operation. Using M-of-N as a filtering process allows systems and processes to be evaluated at an aggregate level, while still triggering an alarm if a defined portion of the calculations are within one or more thresholds (e.g. trigger an alarm state if 90% of temperature readings are between 200 and 300 degrees). Especially for inherently noisy sensor feeds, this allows for reduction in false positives.
In general, the rule_output value summarizes the current state of the node. One rule set may have several potential outputs that each represent an operational state of the system or component. The context of output values within the rule set are specific to the AOS Model and should be contained within model documentation.
HTTPS Request Response M-of-N Result Body Structure
{
“node”: “Motor A Temperature above Ambient”, “units”: “Degrees Fahrenheit”, “rule_set”: “Motor A Temperature Above Ambient Status”, “rule_left_value”: 100, “rule_left_inclusive”: true, “rule_right_value”: 200, “rule_right_inclusive”: false, “rule_percentage”: 85, “result_percentage”: 95.1, “rule_message”: “Motor A Temperature within elevated range.” } |
JSON Field Descriptions
M-of-N Result Field | JSON Key | Data Format | Description |
Node Name | node | Variable Character (200) | Calculation title within the AOS model |
Node Units | units | Variable Character (200) | Measurement units of the node’s value (ex. °C) |
Rule Set | rule_set | Variable Character (200) | Description of the class of rules being monitored on the AOS calculation node |
Rule Left Side Value | rule_left_value | Double Precision | First value in the M-of-N inequality |
Rule Left Inclusive | rule_left_inclusive | True / False | Boolean statement of whether the inequality is inclusive of the left side value |
Rule Right Side Value | rule_right_value | Double Precision | Second value in the M-of-N inequality |
Rule Right Inclusive | rule_right_inclusive | True / False | Boolean statement of whether the inequality is inclusive of the right side value |
Rule Percentage | rule_percentage | Double Precision | The required percentage of model results that are required to be within the inequality for the rule to be true |
Result Percentage | result_percentage | Double Precision | Percentage of all output values from the current evaluation that are within the M-of-N thresholds |
Message | rule_message | Variable Character (1500) | Human readable explanation of the |
1.1.7 Output – Intelligent Predictor
Overview
Intelligent Predictor Nodes allow an AOS model to estimate the future point in time in which a calculated value or sensor node will intersect a defined threshold. Intelligent Predictor rules are associated with a certain portion of the stochastic distribution (e.g. 10th percentile, median value, or 90th percentile) and use a running history of
previous evaluation states to determine the trend of a variable. Selection of the distribution section should reflect the severity of system response if the threshold is reached. A historical trend is used to forecast forward in time to determine the datetime at which the defined threshold value will be crossed.
The model architecture also sets a minimum lead time which to focus on threshold crossings – i.e. motor
temperature is estimated to cross a critical level in 10 days, but the model architecture is configured to only provide an alert when the predicted crossing is less than 3 days. Thresholds can be defined as either upper limits or lower limits at the time of model architecture.
The stochastic prediction distribution computed by AOS is illustrated in the image below:
Figure 1: Intelligent Prediction uncertainty cone
From the diagram above
- Green region: Past observed data
- Pale region: Future data not yet observed
- Blue cone: Predicted possible values
The 10th and 90th percentile form the outer edges of the cone, essentially the earliest and latest AOS is predicting that the threshold might be crossed. The 50th percentile prediction is the dark line in the middle. All three percentiles are available in the JSON output and can be selected depending on the level of certainty desired in the prediction.
As the image illustrates, the 10th percentile crosses the threshold at labeled point 1. This is more conservative than the 50th percentile prediction which crosses later at labeled point 2, but different use cases require different prediction sensitivity.
Gross Estimation
If the Intelligent Predictor predicts that the threshold will be crossed in 3 days, but the configured minimum alert lead time is 5 days then no alert will be produced. It can still be useful to know how far away a threshold cross even is, however. This is the purpose of the gross_estimation prediction which is included in the JSON Array with the 10/50/90 percentiles.
The gross estimation prediction does not use all the same algorithms as the 10/50/90 percentiles and can make predictions farther into the future, but it can also be more volatile. This is intended to give a general sense of how far away the threshold is, but the 10/50/90 percentiles are preferred for actual alerts and service notifications.
HTTPS Request Response Intelligent Predictor Body Structure
{
“node”: “Motor A Temperature above Ambient”, “lead_time_message”: “Pressure in system will exceed safety specifications soon. Shutdown immeadiately and inspect for damage.”, “predictive_threshold_cdf_result”: [ { “result_state”: 4, “result_state_name”: “CROSSING_IMMINENT”, “result_prediction_time_delta”: 331497, “result_timestamp_prediction”: 1548892942560, “threshold_analysis_point”: “gross_estimation”, “threshold_analysis_point_value”: 23.448146767546014 }, { “result_state”: 4, “result_state_name”: “CROSSING_IMMINENT”, “result_prediction_time_delta”: 260000, “result_timestamp_prediction”: 1548892871063, “threshold_analysis_point”: “90”, “threshold_analysis_point_value”: 23.448146767546014 }, { “result_state”: 4, “result_state_name”: “CROSSING_IMMINENT”, “result_prediction_time_delta”: 335000, “result_timestamp_prediction”: 1548892946063, “threshold_analysis_point”: “50”, “threshold_analysis_point_value”: 23.448146767546014 }, { “result_state”: 4, “result_state_name”: “CROSSING_IMMINENT”, “result_prediction_time_delta”: 425000, “result_timestamp_prediction”: 1548893036063, “threshold_analysis_point”: “10”, “threshold_analysis_point_value”: 23.448146767546014 } ], “threshold_name”: “Temperature upper limit”, “threshold_type”: “upper_threshold”, “threshold_value”: 150, “units”: “F” } |
JSON Field descriptions
The below table describes the outputs generated by Intelligent Predictor rules.
Intelligent Predictor Result Field | JSON Key | Data Format | Description |
Node Name | node | Variable Character (200) | Calculation title within the AOS model |
Node Units | units | Variable Character (200) | Measurement units of the node’s value (ex. °C) |
Threshold Name | threshold_name | Variable Character (200) | Description of the class of rules being monitored by the AOS calculation node |
Threshold Value | threshold_value | Double Precision | Value for which the Intelligent Predictor trend line is being calculated to cross analysis point on the intelligent predictor rule |
Threshold Analysis Point Array | predictive_threshold_cdf_results | JSON Array | An array of JSON objects describing the state of each |
Threshold Type | threshold_type | Variable Character (20) | Declaration of whether the threshold is an upper_threshold or a lower_threshold |
Prediction Type Name | prediction_type_name | Variable Character (50) | Description of the prediction type used. |
The below table describes the structure of objects in the predictive_threshold_cdf_results JSON array. Each object in the array represents a single analysis point.
Threshold Analysis Point Result Field | JSON Key | Data Format | Description |
Threshold Analysis Point | threshold_analysis_point | Variable Character (20) | Portion of the stochastic distribution used to create the Intelligent Predictor trend line. |
Threshold Analysis Point Value | threshold_analysis_point_value | Double Precision | Current result of the node during this evaluation – only the portion of the stochastic distribution needed for Intelligent Predictor rule |
Prediction Timestamp | result_timestamp_prediction | Datetime | Datetime at which the Intelligent Predictor will intercept the defined threshold value; may be NULL if current trend will not intercept |
Prediction Timespan | result_timespan_prediction | Long Integer | The estimated number of milliseconds from the end of the evaluation until the Intelligent Predictor will intercept the defined threshold value; may be NULL if current trend will not intercept |
State | result_state | Integer | State of the Intelligent Predictor trend line with respect to the threshold settings |
State Name | result_state_name | Variable Character (200) | Description of Intelligent Predictor state |
The following are potential outputs from Intelligent Predictor result_state and result_state_name. Each state represents a different relationship between the estimated trend line and the threshold value. Description is not included in the JSON payload and is only for informational purposes.
result_state | result_state_name | Description |
-1 | UNKNOWN | Error in model result data |
0 | CROSSED_THRESHOLD | The current state has reached the threshold. |
1 | NOT_CROSSED | The current state has not reached the threshold and will not reach the threshold within the notification time window. |
2 | ZERO_SLOPE | The underlying variable is constant and a flat trend line is estimated. |
3 | NOT_ENOUGH_INFORMATION | The minimum number of model evaluations has not occurred in order to generate an Intelligent Predictor trend line. |
4 | CROSSING_IMMINENT | The current state has not reached the threshold but has been estimated to cross the threshold within the notification time window. |
5 | NO_UPDATE | The last evaluation occurred during a gap in measured data so the Intelligent Predictor did not update. |
[/bt_bb_text][/bt_bb_column][/bt_bb_row][/bt_bb_section]