pyVIP is the Python package that houses the Virtualitics API and was developed for Python 3.

Installation

Prerequisites

Make sure you have the latest version of Explore installed, which can be downloaded from the Account Portal.

We recommend that you use pyVIP with the latest Anaconda distribution of Python 3 (pyVIP is compatible with Python 3.6 through 3.8). Please refer to Anaconda’s instructions if you need any help installing Anaconda.

Installation of pyVIP

From an Anaconda Prompt window, run the following line to install pyVIP:

$> pip install pyVIP

Update your pyVIP version

It is recommended that you regularly update your pyVIP version so that you can use the latest functionalities that we’ve built into the package. To update your pyVIP package, run the following line from an Anaconda Prompt window:

$> pip install –upgrade pyVIP

 Checking your pyVIP version

To verify that you have the correct version of pyVIP, run the following command from an Anaconda Prompt window:

$> python -c “import virtualitics; print(virtualitics.__version__);”

You should see the version number printed to the prompt. For example, you may see “1.8.0”.

Installing from Wheel

You can download the package wheel directly from here.

Setup

Explore Authentication Token

Navigate to the Virtualitics Account Portal and sign in. Select My Account on the left and scroll down to the Tokens and Keys section. Click on Generate for API Token!

If you do not have admin privileges on your machine, you will need to include this API token each time you instantiate the VIP class:

from virtualitics import api

explore = api.VIP(#INSERT API TOKEN HERE#)

If you have admin privileges on your machine, you can set an environment variable called “VIP_AUTH_TOKEN” with the token generated from the Virtualitics Account Portal so that you do not have to specify this each time you instantiate the VIP class. To do this, follow these steps:

1. Open Control Panel from the Start Menu.
2. Click on “System and Security” and then “System”.
3. Click on “Advanced system settings” from the list on the left and then click on the “Environment Variables…” button in the window that appears. You will then see a list of your “User variables” and “System variables”.
4. Click on “New…” under the “User variables” section. Fill in the information as seen below.

Optional: Encryption Key

We strongly recommend using an encryption key! We use this key to encrypt all data passed through the API. Using the instructions above, set an additional user-level environment variable called “VIP_ENCRYPTION_KEY” and specify a strong alphanumeric key. If you are unsure whether this applies to you, please consult your IT department. This encryption key can also be input each time you instantiate the VIP class if you do not have admin privileges on your machine.

Note: After setting your new environment variables, please close your Anaconda prompt and open a new prompt to pull the variables into context.

Updating Explore Settings

Open Explore and sign in with the same credentials you used when using the Virtualitics Account Portal. Open the Settings window by clicking on the gear icon located in the upper right of the toolbar. In the left panel of the Settings menu, navigate to the API section:

• Port Configuration: This is where you specify the port number you would like Explore’s API WebSocket-Server to utilize. The default Port Configuration is set to use 12345; if you are unsure what to specify, we recommend you speak with your IT department or consult with support@virtualitics.com.
• Encryption Key: Set this to the same key you saved as an environment variable. If you did not specify the environment variable for “VIP_ENCRYPTION_KEY” then you can leave this cell blank.
• If you would like the Explore API WebSocket-Server to launch every time you sign into Explore, please select the “Launch server on login” checkbox (recommended).

After you have set up the API Configurations appropriately, click “Launch”!

First Usage

Open a new Anaconda Prompt 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, the user must go into Explore and verify the API connection before continuing:

An example of how to use the API to connect, load a dataset, and generate a plot is below. Please see our complete set of Example Notebooks for more in-depth examples, and refer to our Technical Documentation to learn more about the functionalities of the API.

Note: The API cannot be used while in an active SVO session.

Additional Details

The Virtualitics API runs on a WebSocket connection between Explore (Server) and a Python session (Client). The Virtualitics API WebSocket is launched from 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 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 Explore. 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 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, 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.