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: mvg.mvg.MVGAPI

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

get_labelled_measurements(source_id)

Get all measurements of a source with label information.

Parameters

source_id (string) – Id of the source for all measurements.

Returns

A dataframe listing the label info for each measurement. Columns: [timestamp, label, severity, notes]

Return type

Dataframe

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 vesrion tested against and the version of the MVG library.

Return type

dict

create_label(sid: str, timestamp: int, label: str, severity: int, notes: Optional[str] = '', 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, 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, meta: dict, channels: List[str], exist_ok: bool = False)

Creates a source on the server side.

Parameters
  • sid (str) – source Id

  • meta (dict) – meta information

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

  • 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: Optional[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, meta: dict, columns: List[str], exist_ok: bool = False)

Creates a tabular source on the server side.

Parameters
  • sid (str) – Source ID

  • meta (dict) – Meta information of source

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

  • 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_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_results(request_id: str) 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)

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 cheduled 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) List[dict]
list_measurements(sid: str) list

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

Parameters

sid (str) – source Id.

Returns

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_measurements(sid: str, start_timestamp: Optional[int] = None, end_timestamp: Optional[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].

Returns

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

  • KPI, and metadata corresponding to a measurement

static parse_version(vstr) semver.VersionInfo

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: Optional[dict] = None, start_timestamp: Optional[int] = None, end_timestamp: Optional[int] = None) str

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].

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

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

Returns

request_id

Return type

analysis identifier

request_population_analysis(sids: List[str], feature: str, parameters: Optional[dict] = None, start_timestamp: Optional[int] = None, end_timestamp: Optional[int] = None) str

Request an 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].

Returns

request_id

Return type

analysis identifier

say_hello() dict

Retrievs 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.

Returns

Return type

A list of supported features (strings)

update_label(sid: str, timestamp: int, label: str, severity: int, notes: Optional[str] = '')

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.