MVG: MultiViz Analytics Engine Library

A Python 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. API documentation.

Obtaining the library

pip install va-mvg

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 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. Example of meta information for a source

    {"sensor_type": "arduino",
    "location": "gearbox"}
    
  • 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 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 (request_id). 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.

Version handling of mvg and API version

The version string of the MVG api has the form v{MAJOR}.{MINOR}.{PATCH}. An increase of MAJOR means an incompatible change which requires an upgrade of mvg, an increase in MINOR does not require an upgrade of mvg, but may then not allow to access new features of the API. See mvg documentation and examples/check_version.py for details.

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.

Maintainer

Maintainer of the mvg library is Viking Analytics AB. https://www.vikinganalytics.se

Bug Reporting, Pull request, and support …

… please use the issue tracking and pull requests on https://github.com/vikinganalytics/mvg

Indices and tables