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℠ (AOS®) 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]