MutliViz Analytics Engine

MVG library

For use of client side development the MVG class shall be used.

The MVGAPI class is intended for development of the library itself.

For more information see README.md.

class mvg.mvg.MVG(endpoint: str, token: str)

Bases: MVGAPI

Class for a session providing an API to the vibium server. Contains additional functionality over API methods

wait_for_analyses(request_id_list: list, timeout=None)

Wait for the analyses specified by list of request_ids to finish.

Parameters:

• request_id_list (list) – list of request_ids (analysis identifier)

• timeout (float [Optional]) – amount of time (in seconds) to wait for the analyses to finish

class mvg.mvg.MVGAPI(endpoint: str, token: str)

Bases: object

Class for a session providing an API to the vibium server

check_version() → dict

Checks if the version of MVG is compatible with the API version called on the server side. This call does not require a valid token. Where: API version is the version on the server side, highest tested version is the highest API version the MVG has been tested against, and the MVG version is the version of the MVG library.

Raises:

• UserWarning – In case it would be advisable to upgrade MVG.

• ValueError – In case MVG is incompatible with the API.

Returns:

message – Showing the api version, the highest version tested against and the version of the MVG library.

Return type:

dict

create_label(sid: str, timestamp: int, label: str, severity: int, notes: str | None = '', exist_ok: bool = False)

Create a label for a measurement

Parameters:

• sid (str) – Id of the source for the measurement

• timestamp (int) – Timestamp of the measurement to label

• label (str) – A string label to attach to the measurement

• severity (int) – Severity of the label as a positive integer

• notes (Optional[str], optional) – Optional notes for the label, by default “”

• exist_ok (bool) – Set to true to prevent exceptions for 409 Conflict errors caused by trying to create an existing label. Defaults to False

create_measurement(sid: str, duration: float, timestamp: int, data: Dict[str, List[float]], meta: dict = None, exist_ok: bool = False)

Stores a measurement on the server side.

Although it is up to the client side to handle the scaling of data it is recommended that the values represent the acceleration in g. The timestamp shall represent the time when the measurement was recorded.

Parameters:

• sid (str) – source Id.

• duration (float) – duration of the measurement in seconds.

• timestamp (int) – in milliseconds since EPOCH.

• data (Dict[str, List[float]]) – Data on the format {channel: values}. Each value is a timeseries of measurements. This format can be generated by pandas.DataFrame.to_dict(“list”)

• meta (dict) – Meta information to attach to data.

• exist_ok (bool) – Set to true to prevent exceptions for 409 Conflict errors caused by trying to create an existing measurement. Defaults to False

create_source(sid: str, channels: List[str], meta: dict = None, exist_ok: bool = False)

Creates a source on the server side.

Parameters:

• sid (str) – Source ID

• channels (List[str]) – Channels of waveform Data. For instance axial, vertical and horizontal measurements for the source. Cannot be updated after creating source.

• meta (dict) –

  Meta information of source. Note that tabular source requires “location” and “assetName” in metadata, while spectrum and waveform need “location”, “assetName”, “sensorName” and “measurementName” e.g: {

  ”location”: “Factory x”, “assetName”: “Water pump 13”, “sensorName”: “NDE H”, “measurementName”: “8k_Acc_1200000”

  }

• exist_ok (bool) – Set to true to prevent exceptions for 409 Conflict errors caused by trying to create an existing source. Defaults to False.

create_spectrum_measurement(sid: str, freq_range: ConstrainedListValue[float], timestamp: int, data: Dict[str, List[float]], meta: dict = None, exist_ok: bool = False)

Stores a measurement on the server side.

Although it is up to the client side to handle the scaling of data it is recommended that the values represent the acceleration in g. The timestamp shall represent the time when the measurement was recorded.

Parameters:

• sid (str) – source Id.

• freq_range (FrequencyRange) – lowest and highest frequency available in the spectrum as a list [MIN, MAX].

• timestamp (int) – in milliseconds since EPOCH.

• data (Dict[str, List[float]]) – Data on the format {channel: values}. This format can be generated by pandas.DataFrame.to_dict(“list”).

• meta (dict) – Meta information to attach to data [optional].

• exist_ok (bool) – Set to true to prevent exceptions for 409 Conflict errors caused by trying to create an existing measurement. Defaults to False.

create_spectrum_source(sid: str, channels: List[str], meta: dict = None, exist_ok: bool = False)

Creates a spectrum source on the server side.

Parameters:

• sid (str) – Source ID

• channels (List[str]) – Channels of spectrum Data. For instance axial, vertical and horizontal. Channel names must be unique. Cannot be updated after creating source.

• meta (dict) – Meta information of source [optional].

• exist_ok (bool) – Set to true to prevent exceptions for 409 Conflict errors caused by trying to create an existing source. Defaults to False.

create_tabular_measurement(sid: str, data: Dict[str, List[float]], meta: Dict[float, dict] = None, exist_ok: bool = False)

Stores a measurement on the server side.

Although it is up to the client side to handle the scaling of data it is recommended that the values represent the acceleration in g. The timestamp shall represent the time when the measurement was recorded.

Parameters:

• sid (str) – source Id.

• data (Dict[str, List[float]]) – Tabular data on the format {column: values}. ‘timestamp’ column is required. This format can be generated by pandas.DataFrame.to_dict(“list”)

• meta (dict) – Meta information to attach to data. Should have the format {timestamp: meta_dict}. Timestamps must match data timestamps

• exist_ok (bool) – Set to true to prevent exceptions for 409 Conflict errors caused by trying to create an existing measurement. Defaults to False

create_tabular_source(sid: str, columns: List[str], meta: dict = None, exist_ok: bool = False)

Creates a tabular source on the server side.

Parameters:

• sid (str) – Source ID

• columns (List[str]) – Data variables. Currently supports numerical data. Cannot be updated after creating source.

• meta (dict) – Meta information of source [optional].

• exist_ok (bool) – Set to true to prevent exceptions for 409 Conflict errors caused by trying to create an existing source. Defaults to False.

delete_analysis(request_id: str)

Deletes an analysis.

Parameters:

request_id (str) – request_id (analysis identifier)

delete_label(sid: str, timestamp: int)

Delete all label information from a measurement

Parameters:

• sid (str) – Id of the source for the measurement

• timestamp (int) – Timestamp of the measurement

delete_measurement(sid: str, timestamp: int)

Deletes a measurement.

Parameters:

• sid (str) – source Id. Identifies source.

• timestamp (int) – in milliseconds since EPOCH. Identifies measurement.

delete_source(sid: str)

Deletes a source on the given endpoint.

Parameters:

sid (str) – source Id.

get_analysis_info(request_id: str) → dict

Retrieves info of an analysis request.

The info of an analysis request includes the current status and the status history of the analysis where the status history is a list of statuses logged for the analysis. The info also contains an overview of the measurements used by the analysis.

Parameters:

request_id (str) – request_id (analysis identifier)

Returns:

a dictionary with the analysis info.

Return type:

dict

get_analysis_results(request_id: str, offset: int = None, limit: int = None, result_type: str = None) → dict

Retrieves an analysis with given request_id The format of the result structure depends on the feature.

Parameters:

• request_id (str) – request_id (analysis identifier)

• offset (int) – zero-based index of an item in one of the dictionaries in the data for “results” key [optional].

• limit (int) – maximum number of items to be returned from each dictionary in the data for “results” key [optional].

• result_type (str) – The type of results to return. By default, the type is ‘full’ implying the complete analysis results will be returned. The allowed types varies between features [optional].

Returns:

a dictionary with the results in case available.

Return type:

dict

get_analysis_status(request_id: str) → str

Return the status of an analysis request with given request_id.

Parameters:

request_id (str) – request_id (analysis identifier)

Returns:

status of the analysis. It can take any of the following values: “queued”: The request is scheduled but have not started. “ongoing”: The request is running “failed”: The request failed due to internal issue. “successful”: The request finished successfully.

Return type:

str

get_endpoint() → str

Accessor function.

Returns:

• endpoint (str)

• Endpoint sent to constructor

get_label(sid: str, timestamp: int) → dict

Get a single label from a measurement

Parameters:

• sid (str) – Id of the source for the measurement

• timestamp (int) – Timestamp of the measurement

Returns:

label information

Return type:

dict

get_source(sid: str) → dict

Returns the information stored for a source representing on the given endpoint.

Parameters:

sid (str) – source Id.

Returns:

Information stored about the source.

Return type:

dict

get_token() → str

Accessor function.

Returns:

• token (str)

• Token sent to constructor

list_analyses(sid: str, feature: str) → list

Retrieves list of analysis IDs associated with a source and a feature.

Parameters:

• sid (str) – source Id.

• feature (str) – name of the feature.

Returns:

a list of analysis IDs.

Return type:

list

list_labels(source_id: str, include_unlabeled: bool = False) → List[dict]

Get a list of all the labels for a source

Parameters:

• source_id (str) – Source ID of the source to get the labels from

• include_unlabeled (bool) – Only returns the labeled times if True, by default False

Returns:

Label information for the different timestamps

Return type:

List[dict]

list_measurements(sid: str, offset: int = None, limit: int = None) → list

Retrieves measurements (all timestamps and metadata) for a source.

Parameters:

• sid (str) – source ID.

• offset (int) – index of the first measurement in the database

• limit (int) – maximum number of measurements to be returned

Return type:

An array of arrays of single measurements.

list_sources() → list

Lists all sources (sensors) on the server side

Returns:

list of all source id

Return type:

s known to the server

list_tabular_downsampled_measurements(sid: str, threshold: int | None = None, start_timestamp: int | None = None, end_timestamp: int | None = None) → dict

Retrieves downsampled tabular measurements for a source.

Parameters:

• sid (str) – source Id.

• threshold (int) – Max number of points to display per dataset. Value of 0 means no downsampling will be applied [optional].

• start_timestamp (int) – Measurements starting from a timestamp [optional].

• end_timestamp (int) – Measurements ending at a timestamp [optional].

Returns:

• A dictionary of KPIs in the format

• {kpi1 ({ x: timestamps, y: values }, kpi2: { … }})

list_tabular_measurements(sid: str, start_timestamp: int = None, end_timestamp: int = None, offset: int = None, limit: int = None) → dict

Retrieves tabular measurements (including metadata) for a source.

Parameters:

• sid (str) – source Id.

• start_timestamp (int) – Measurements starting from a timestamp [optional].

• end_timestamp (int) – Measurements ending at a timestamp [optional].

• offset (int) – index of the first measurement in the database

• limit (int) – maximum number of measurements to be returned

Returns:

• An dict having a list of all timestamps, a list of all measurements grouped by

• column names, and metadata corresponding to a measurement.

list_timestamps(sid: str, offset: int = None, limit: int = None, order: SortOrder = 'asc') → Dict

Retrieves timestamps for a source. If offset and limit params are not specified, all timestamps will be returned.

Parameters:

• sid (str) – source ID.

• offset (int) – index of the first timestamp in the database [optional].

• limit (int) – maximum number of timestamps to be returned [optional].

• order (SortOrder) – Sort order, either “asc” or “desc”. Defaults to “asc”.

Returns:

• “offset”: int, representing starting point of returned items.

• ”limit: int, representing max items to return.”

• ”items”: list of int, representing timestamps.

• ”total”: int, representing total number of items.

Return type:

A dictionary containing the following keys

static parse_version(vstr) → Version

Parses the version string into an array

Parameters:

vstr (str) – Version string of form v3.2.1

Returns:

version

Return type:

VersionInfo

read_single_measurement(sid: str, timestamp: int) → dict

Retrieves all measurements for one single timestamps from source Id.

The format of the returned measurement is an array with the first value being the time stamp and the subsequent values being the data (samples).

Parameters:

• sid (str) – source Id.

• timestamp (int) – in milliseconds since EPOCH.

Returns:

• dict containing measurement data, meta information and duration or

• columns, depending on source data class

request_analysis(sid: str, feature: str, parameters: dict = None, selected_channels: List[str] = None, selected_columns: List[str] = None, start_timestamp: int = None, end_timestamp: int = None, callback_url: str = None, force: bool = False) → dict

Request an analysis on the given endpoint with given parameters.

Parameters:

• sid (str) – Source Id.

• feature (str) – Name of feature to run.

• parameters (dict) – Name value pairs of parameters [optional].

• selected_channels (List[str]) – Subset of Waveform Data channels for analysis. This cannot be used in conjunction with selected_columns [optional].

• selected_columns (List[str]) – Subset of Tabular Data columns for analysis. This cannot be used in conjunction with selected_channels [optional].

• start_timestamp (int) – Start of analysis time window [optional].

• end_timestamp (int) – Start of analysis time window [optional].

• callback_url (str) – Base URL to receive a notification when the analysis job ends. A POST request will be made to {callback_url}/analyses with payload that includes the request_id and request_status of the job [optional].

• force (bool) – Set to False to reuse the analysis results if it already exists, otherwise re-run the analysis. Defaults to False.

Returns:

Containing request_id and request_status corresponding to analysis identifier and analysis status.

Return type:

dict

request_population_analysis(sids: List[str], feature: str, parameters: dict = None, start_timestamp: int = None, end_timestamp: int = None, callback_url: str = None, force: bool = False) → dict

Request a population analysis on the given endpoint with given parameters.

Parameters:

• sids (List[str]) – Source ids.

• feature (str) – Name of feature to run. This feature must be of population type.

• parameters (dict) – Name value pairs of parameters [optional].

• start_timestamp (int) – Start of analysis time window [optional].

• end_timestamp (int) – Start of analysis time window [optional].

• callback_url (str) – Base URL to receive a notification when the analysis job ends. A POST request will be made to {callback_url}/analyses with payload that includes the request_id and request_status of the job [optional].

• force (bool) – Set to True to force a re-run on any existing analysis, otherwise existing analysis results will be reused. Defaults to False.

Returns:

Containing request_id and request_status corresponding to analysis identifier and analysis status.

Return type:

dict

say_hello() → dict

Retrieves information about the API. This call does not require a valid token.

Returns:

• message (dict)

• Hello message with info on MVG API.

supported_features() → list

Return all supported features. Presence of a feature is indicated by string with the feature name set to true. That string shall be used to specify that feature in an analysis request. This call does not require a valid token.

Return type:

A list of supported features (strings).

update_label(sid: str, timestamp: int, label: str, severity: int, notes: str | None = '')

Update a label for a measurement

Parameters:

• sid (str) – Id of the source for the measurement

• timestamp (int) – Timestamp of the measurement

• label (str) – The new label to attach to the measurement

• severity (int) – The new severity of the label as a positive integer

• notes (Optional[str], optional) – New optional notes for the label, by default “”

update_measurement(sid: str, timestamp: int, meta: dict)

Replaces meta information along measurement. It is not possible to update the actual measurement data.

Parameters:

• sid (str) – source Id.

• timestamp (int) – in milliseconds since EPOCH. Identifies measurement.

• meta (dict) – Meta information to attach to data.

update_source(sid: str, meta: dict)

Replaces source meta information on the server side.

Parameters:

• sid (str) – source Id.

• meta (dict) – meta information to replace old meta information.