To use the Virtualitics Python API (pyVIP), open a new appropriate terminal window and run the following command to open a new Jupyter Notebook:

$> jupyter notebook

When calling the api.VIP() constructor successfully for the first time, it is important to have  Virtualitics Explore open and verify the API connection before continuing, as shown below.

An example of how to use the API to connect, load a dataset, and generate a plot is provided below for reference. 

Please see our complete set of Example Notebooks for more in-depth examples, and refer to our API Technical Documentation to learn more about the functionalities of the API.

Additional Information

The Virtualitics Python API runs on a WebSocket connection between Virtualitics Explore (Server) and a Python session (Client).

The Virtualitics API WebSocket is launched from Virtualitics Explore in the API section of the Settings 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 Virtualitics Explore's AI 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 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 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 Virtualitics Explore. Virtualitics Explore 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 Virtualitics Explore 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/double, 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 pyVIP in a future release.