va-mvg 0.0.1.dev0

MultiViz Analytics Engine library

MVG: MultiViz Analytics Engine Library

A library to interface the the MultiViz Analytics EnGine ('MVG')

• setup a session towards the vibium-cloud service

• interface the services by means of API calls

Basic Usage

1. Create a session by instantiating a MVG object. A session is a combination of an endpoint (server address) and a token. The token is used both for authentication (carrying userId and siteID) and authorization. The token is provided by Viking Analytics.

2. Call the API functions

3. Errors are propagated via exceptions. It is up to the calling application to handle error cases.

Important Concepts

• endpoint: The server providing the analytics and data handling functions. Represented by an URL. The endpoint is set when creating the session.

• source ID (sid): an identifier representing a measurement source, typically a sensor. The sid is set on the client side and will be used as a reference for the source and all information related to it (e.g. measurements and analysis results).

• token: authentication and authorization token (to be provided by Viking Analytics)

• meta information: additional information attached to sources or measurements. For some analyses the meta information needs to contain specific key-value pairs, but in general meta information is managed by the client side. Meta information will be stored along the sources/measurements and can be retrieved from the server side, even if it is not processed on the server side.

• measurements: measurements is numerical data (typically a list of float values representing sensor data) identified by the source ID (the sensor recording the measurement) and the timestamp when the measurement was recorded. It is the responsibility of the client side to convey source ID and timestamp to the server side.

• features: features are the analytics functions supported by the server side. An analytics function is invoked on a a set of measurements by requesting an analysis.

• analysis: an analysis applies a feature on a set of previously stored data. To specify an analysis the feature, the data, and the parameters need to be specified by the client side. Data needs to be available on the server. All calls to analysis are asynchronous. So the flow is to (1) request an analysis (2) poll for status (3) retrieve results when the analysis is completed. Each analysis is assigned a unique ID (jobid). Completed analyses are stored on the server side and can be retrieved by means of the jobid. It is primarily the clients side's responsibility to keep track of analyses.

Additional Documentation

• API documentation on mvg, autogenerated from mvg.py

Examples

There are three executable python files in the examples directory:

1. sources_and_measurements.py showing how to create, retrieve and delete sources or measurements for the API.

2. error_handling.pyshowing how to handle errors occuring either when calling the API or during processing on the server side. Errors on the server side will conveyed as http status codes.

3. analysis.py still to be written.