MVG: MultiViz Analytics Engine Client Library

The MultiViz Analytics EnGine ('MVG') is a Python library that enables users to:

• Establish a session with the Vibium Cloud service
• Interface the services via API calls. For more information, refer to the API documentation.

Documentation

Usage of the library and several examples can be found here.

Installation

To install the library, use the following pip command:

pip install va-mvg

Basic Usage

The basic usage involves three steps:

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

2. Call the API functions.

3. Handle exceptions. Errors are propagated via exceptions, and it is the responsibility of the calling application to handle these.

Important Concepts

• Endpoint: The server that provides the analytics and data handling functions. This is represented by a URL and is set when creating the session.

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

• Token: An authentication and authorization token provided by Viking Analytics.

• Metadata: Additional data providing information about the sources or measurements. This can contain specific key-value pairs for some analyses, but generally, metadata is managed by the client side. Even if it is not processed on the server side, metadata is stored alongside the sources/measurements and can be retrieved from the server side. For example:

  {"sensor_type": "arduino",
  "location": "gearbox"}

• Measurements: 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. The client side is responsible for conveying the source ID and timestamp to the server side.

• Features: 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. The client side needs to specify the feature, the data, and the parameters for an analysis. Data needs to be available on the server. All calls to analysis are asynchronous. The typical flow is to (1) request an analysis, (2) poll for status, and (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 using the job ID. It is primarily the client side's responsibility to keep track of analyses.

Version Handling of MVG and API Version

The version string of the MVG API on the server side has the form v{MAJOR}.{MINOR}.{PATCH}. An increase in MAJOR signifies an incompatible change that requires an upgrade of mvg. An increase in MINOR does not require an upgrade but may not allow access to new features of the API. Please refer to the mvg documentation

and the example "examples/0-check_version.ipynb" for details.

Additional Documentation

• Autogenerated API documentation on mvg from mvg.py

Examples

In the examples section, there are several Jupyter notebooks with Python code demonstrating how to use the library for interfacing with the Viking Analytics Engine. You can download these notebooks by clicking on the "View Page Source" link located at the top left of the examples. Be sure to change the extension to .ipynb before running them.

Analysis Classes (beta)

Analysis classes provide a simple and powerful way to parse and inspect the results from analysis calls for our features. Apart from converting the results to dataframes, they can be used in an interactive shell to inspect the results from analysis calls.

In the "analysis_class_examples" directory, there are scripts showing how to use the analysis classes.

Maintainer

The mvg library is maintained by Viking Analytics AB. Visit their website at https://www.vikinganalytics.se.

Bug Reporting, Pull Requests, and Support

For bug reporting, pull requests, and support, please use the issue tracking and pull requests on the mvg GitHub page: https://github.com/vikinganalytics/mvg.

License

The mvg library is licensed under the Apache License 2.0. See the LICENSE file for details.