Virtualitics API Technical Overview

The Virtualitics API runs on a WebSocket connection between VIP (Server) and a Python session (Client). The Virtualitics API WebSocket is launched from VIP in the API section of the Preferences window. The Client WebSocket connection is established through the pyVIP package. The api.VIP() constructor initializes this connection and creates a new VIP object. This new VIP object is a handler for the API connection and is used to communicate all API requests to the Python side.

API Structure

The pyVIP package comes with two important classes. The first is the VIP class, which is a handler for the API connection. The VIP class contains methods for loading data, adding columns, generating visualizations, running VIP’s machine learning routines, and much more. There are several ways to generate new plots using the VIP class. There is a generic VIP.plot() method that allows the user to specify the plot type as a parameter. However, to take full advantage of specific settings for different plot types, we strongly recommend using the plot-type-specific methods (e.g. VIP.scatter(), VIP.maps2d(), VIP.surface(), etc.). When these methods finish generating the requested plot, they save a VipPlot object to the VIP.local_history, a list of these VipPlot objects.

VipPlot objects allow you to pass and update a set of mappings and settings within your own code. To generate the plot described in your VipPlot object, simply call VIP.show(VipPlot). By accessing the VipPlot objects in the VIP.local_history, you can make quick changes to plots you’ve recently generated.

Data Types

Users should monitor their data types when passing data to VIP. VIP may adjust column types during the serialization process to reflect the level of precision indicated by the data. This behavior may change in future versions to allow users to specify VIP column types when loading data through the API.

Within your pandas DataFrame object, please ensure that the dtype of your columns are either int, float, or object types. Additionally, our DataFrame parsers assume that your object column contains only strings and will fail if you pass any other type of object.

If you choose to use the category dtype provided by pandas, we recommend that you cast the data back to strings or otherwise convert to int. We will work on adding a parser for the category dtype to the API in a future release.