API Documentation

Installation and Setup

Please see our full documentation at https://docs.virtualitics.com/api/setup-and-installation/

Example Notebooks

Please see our full set of example notebooks at https://docs.virtualitics.com/api/example-notebooks/

virtualitics.api

class virtualitics.api.VIP(auth_token=None, port=12345, encryption_key=None, host='ws://localhost', log_level=0, figsize=(8, 8))

Virtualitics API handler for Python.

The class will cache information about the VIP session and establish the VIP connection

Parameters:
  • auth_token – User to pass Authentication Token; default: None will check environment variables for token under “VIP_AUTH_TOKEN”
  • port – The port VIP is serving. default: 12345. Integer in [0, 65535]
  • encryption_key – Optional encryption key; default: None
  • host – default is localhost connection. Only change this if you intend on connecting to a remote VIP instance. This is an advanced functionality.
  • log_levelint from 0 to 2. 0: quiet, 1: help, 2: debug. Help level will print messages that guide the user of important internal events. Debug level will print messages that expose a greater level of the internal state, useful for development and debugging purposes. Each level will print what is also printed at lower levels.
  • figsize(int, int) sets the figure size for showing any plots returned from VIP. The resolution of the plots shown is controlled by the ‘imsize’ parameter in the function calls. The default is [8, 8].
Raises:

AuthenticationException – if the auth token is not provided and cannot be found in the expected locations.

ad(features=None, exclude=None, return_anomalies_df=True, plus_minus='both', stdev=0.5, and_or='and', apply=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, keep_missing_value_columns=True)

Alias to anomaly_detection

add_column(data, name=None)

Add a pandas series to the currently loaded dataset in VIP. Uses column dtype to determine column type in VIP.

Parameters:
  • datapandas.core.Series object that contains a column of the user’s data.
  • name – if not None, sets this as the name of the series when it is added.
Returns:

None

add_rows(data)

Append a pandas data frame of rows to the currently loaded dataset in VIP.

Parameters:datapandas.core.frame.DataFrame object that contains rows of the user’s data.
Returns:None
anomaly_detection(features=None, exclude=None, return_anomalies_df=True, plus_minus='both', stdev=0.5, and_or='and', apply=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, keep_missing_value_columns=True)

Runs anomaly detection in VIP

Parameters:
  • features – List of column names that user wants to analyze for outliers
  • exclude – List of column names to exclude in the analysis; this overrides any features listed in the features parameter.
  • plus_minus – Include outliers that are above, below, or above and below the desired standard deviation mark. Defaults to both. Can be “both”, “plus”, or “minus”
  • stdev – User defined standard deviation on which to classify outliers.
  • and_or – “and” identifies data points that are outliers in all input features. “or” identifies data points that are outliers in any of the input features.
  • applybool for whether to apply the result to the halo dimension.
  • return_anomalies_df – Whether to return the output of the process to the notebook. Defaults to True.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • keep_missing_value_columnsbool for whether to keep features with more than 50% missing values as part of the input for anomaly detection. Default is True.
Returns:

None

clustering(num_clusters=None, features=None, exclude=None, keep_missing_value_columns=True, apply=True, return_clusters_df=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True)

Runs K-means clustering in VIP

Parameters:
  • num_clustersint between 1 and 16, specifying the number of clusters to compute. Default is None and enables ‘auto’-mode where the number of clusters to compute is algorithmically determined based on stability.
  • features – List of column names that user wants to analyze
  • exclude – List of column names to exclude in the analysis; this overrides any features listed in the features parameter.
  • return_clusters_df – Whether to return the output of the process to the notebook. Defaults to True.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • applybool determining whether to apply the clustering result to the color dimension. Default is True.
  • keep_missing_value_columnsbool for whether to keep features with more than 50% missing values as part of the input for clustering. Default is True.
Returns:

pandas.DataFrame containing the results of the clustering. If return_data is false, this returns None.

clustering_coefficient(apply=True, use_color_normalization=True, return_clustering_coefficient_df=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True)

Runs the clustering coefficient algorithm on the visible network that is currently loaded in VIP.

Parameters:
  • return_clustering_coefficient_dfbool determining whether to return a pandas.DataFrame containing the clustering coefficient results to the caller. Defaults to True.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • applybool determining whether to apply the clustering coefficient result to the color dimension. Default is True. When True, color_type is automatically changed to gradient.
  • use_color_normalizationbool determining whether to use softmax color normalization when the clustering coefficient result has been applied to color. Default is True.
Returns:

pandas.DataFrame containing the results of the clustering coefficient. If return_clustering_coefficient_df is False, this returns None.

convert_column(column, column_type: str)

Converts column to the specified type.

Parameters:
  • column – expects column name (str) or a pandas.Series
  • column_type – {“Continuous”, “Categorical”}
Returns:

None

static convert_json_to_networkx(network)

Converts a network represented in VIP’s JSON format into a NetworkX object.

Parameters:networkstr of path to JSON file or dict representing the JSON as a dictionary.
Returns:networkx.Graph object.
static convert_networkx_to_json(network, path=None)

Converts a network represented as a NetworkX object into VIP’s JSON format.

Parameters:
  • networknetworkx.Graph an undirected NetworkX graph
  • pathstr of path to write JSON to or None to omit writing to file. Defaults is None.
Returns:

dict representing the JSON as a dictionary.

convex_hull(show_points=True, x=None, y=None, z=None, color=None, size=None, shape=None, transparency=None, halo=None, halo_highlight=None, pulsation=None, pulsation_highlight=None, playback=None, playback_highlight=None, arrow=None, groupby=None, x_scale=None, y_scale=None, z_scale=None, size_scale=None, transparency_scale=None, halo_scale=None, arrow_scale=None, color_type=None, x_normalization=None, y_normalization=None, z_normalization=None, size_normalization=None, transparency_normalization=None, arrow_normalization=None, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, color_bins=None, color_bin_dist=None, color_inverted=None, name=None)

Generates Convex Hull plot in VIP. Expects column name or pandas data series dimension parameters.

Parameters:
  • show_points – Setting for how to view the convex hull. Valid options are {True, False, “show”, “hide”}
  • x – X dimension
  • y – Y dimension
  • z – Z dimension
  • color – Color dimension. Automatically uses quartile/categorical coloring.
  • size – Size dimension. Works best with continuous features
  • shape – Shape dimension. Works best with categorical features
  • transparency – Transparency dimension. Works best with continuous features.
  • halo – Halo dimension. Works with binary features
  • halo_highlight – Optionally select a single value of the feature mapped to the Halo dimension. All points with this value will show a halo.
  • pulsation – Pulsation dimension. Works best with categorical features
  • pulsation_highlight – Optionally select a single value of the feature mapped to the Pulsation dimension. All points with this value will pulsate.
  • playback – Playback dimension. Requires user interaction to be activated; otherwise shows all.
  • playback_highlight – Optionally select a single value of the feature mapped to the Playback dimension. All points with this value will be shown and all other points will be hidden.
  • arrow – Arrow dimension. Works with continuous and categorical features.
  • groupby – Group By dimension. Works with categorical columns.
  • x_scale – Scaling factor for X dimension. Value must be between 5 and 5.
  • y_scale – Scaling factor for Y dimension. Value must be between .5 and 5.
  • z_scale – Scaling factor for Z dimension. Value must be between .5 and 5.
  • size_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • transparency_scale – Scaling factor for Transparency dimension. Value must be between .5 and 5.
  • halo_scale – Scaling factor for Halo dimension. Value must be between .5 and 5.
  • arrow_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • color_type – User can select “bin” or “palette” or None (which uses VIP defaults). For categorical data, the only option is color “palette”. For numeric data, “bin” is the default.
  • color_invertedbool controlling the order of colors for all color types.
  • x_normalization – Normalization setting for X. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • y_normalization – Normalization setting for Y.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • z_normalization – Normalization setting for Z. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • size_normalization – Normalization setting for Size. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • transparency_normalization – Normalization setting for Transparency.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • arrow_normalization – Normalization setting for Arrow. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • export – Specify whether to export a capture of the plot. Defaults to “ortho”. Options are {“ortho”, “front”, “right”, “side” (same as “right”), “top”, “perspective”, None, False}.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • color_bins – sets the number of color bins to use. The max number of bins is 16. You must have at least as many unique values (in the column mapped to color) as the number of bins you set.
  • color_bin_diststr with options: {“equal”, “range”}
  • namestr specifying the name of the plot. Default to None. A name will be automatically generated in VIP.
Returns:

None

delete_dataset(name=None)

Deletes a dataset or network from VIP. This is particularly useful when you have a lot of data loaded into VIP and there is a performance slow down. If ‘dataset_name’ is passed, VIP will delete the dataset or network with the corresponding name. If ‘dataset_name’ is left as None, the currently loaded dataset or network will be deleted from VIP if there is a dataset loaded.

Parameters:namestr specifying the name of the dataset or network to delete from VIP. Defaults to None
Returns:None
ellipsoid(confidence=95.0, show_points=True, x=None, y=None, z=None, color=None, size=None, shape=None, transparency=None, halo=None, halo_highlight=None, pulsation=None, pulsation_highlight=None, playback=None, playback_highlight=None, arrow=None, groupby=None, x_scale=None, y_scale=None, z_scale=None, size_scale=None, transparency_scale=None, halo_scale=None, arrow_scale=None, color_type=None, x_normalization=None, y_normalization=None, z_normalization=None, size_normalization=None, transparency_normalization=None, arrow_normalization=None, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, color_bins=None, color_bin_dist=None, color_inverted=None, name=None)

Generates Ellipsoid plot in VIP. Expects column name or pandas data series dimension parameters.

Parameters:
  • confidencefloat confidence probability that must be in {99.5, 99.0, 97.5, 95.0, 90.0, 80.0, 75.0, 70.0, 50.0, 30.0, 25.0, 20.0, 10.0, 5.0, 2.5, 1.0, 0.5}
  • show_points – Setting for how to view the confidence ellipsoids. Valid options are {True, False, “show”, “hide”}
  • x – X dimension
  • y – Y dimension
  • z – Z dimension
  • color – Color dimension. Automatically uses quartile/categorical coloring.
  • size – Size dimension. Works best with continuous features
  • shape – Shape dimension. Works best with categorical features
  • transparency – Transparency dimension. Works best with continuous features.
  • halo – Halo dimension. Works with binary features
  • halo_highlight – Optionally select a single value of the feature mapped to the Halo dimension. All points with this value will show a halo.
  • pulsation – Pulsation dimension. Works best with categorical features
  • pulsation_highlight – Optionally select a single value of the feature mapped to the Pulsation dimension. All points with this value will pulsate.
  • playback – Playback dimension. Requires user interaction to be activated; otherwise shows all.
  • playback_highlight – Optionally select a single value of the feature mapped to the Playback dimension. All points with this value will be shown and all other points will be hidden.
  • arrow – Arrow dimension. Works with continuous and categorical features.
  • groupby – Group By dimension. Works with categorical columns.
  • x_scale – Scaling factor for X dimension. Value must be between .5 and 5.
  • y_scale – Scaling factor for Y dimension. Value must be between .5 and 5.
  • z_scale – Scaling factor for Z dimension. Value must be between .5 and 5.
  • size_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • transparency_scale – Scaling factor for Transparency dimension. Value must be between .5 and 5.
  • halo_scale – Scaling factor for Halo dimension. Value must be between .5 and 5.
  • arrow_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • color_type – User can select “bin” or “palette” or None (which uses VIP defaults). For categorical data, the only option is color “palette”. For numeric data, “bin” is the default.
  • color_invertedbool controlling the order of colors for all color types.
  • x_normalization – Normalization setting for X. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • y_normalization – Normalization setting for Y.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • z_normalization – Normalization setting for Z. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • size_normalization – Normalization setting for Size. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • transparency_normalization – Normalization setting for Transparency.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • arrow_normalization – Normalization setting for Arrow. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • export – Specify whether to export a capture of the plot. Defaults to “ortho”. Options are {“ortho”, “front”, “right”, “side” (same as “right”), “top”, “perspective”, None, False}.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • color_bins – sets the number of color bins to use. The max number of bins is 16. You must have at least as many unique values (in the column mapped to color) as the number of bins you set.
  • color_bin_diststr with options: {“equal”, “range”}
  • namestr specifying the name of the plot. Default to None. A name will be automatically generated in VIP.
Returns:

None

figsize

This is used as the setting for the matplotlib figure size when displaying the image of plots generated by VIP. The default value is (8, 8)

Returns:(int, int)
filter(feature_name, min=None, max=None, include=None, exclude=None, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, keep_missing_value_columns=True)
Parameters:
  • feature_name – Name of feature to add filter to
  • min – If feature is continuous, set the lower bound of the filter to “min”
  • max – If feature is continuous, set the upper bound of the filter to “max”
  • include – If feature is categorical, set these categories to be visible
  • exclude – If feature is categorical, set these categories to be invisible
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • keep_missing_value_columnsbool for whether to keep features with more than 50% missing values as part of the input for filtering. Default is True.
Returns:

None

get_column(feature_name)

Gets the column named <feature_name> from the currently loaded dataset

Parameters:feature_name – Name of column to get
Returns:pandas.core.Series
get_dataset(name=None)

Gets the entire loaded dataset from the software in its current state

Parameters:name – If specified, get the dataset named <name>. Else, gets the currently loaded dataset.
Returns:pandas.DataFrame
get_network(as_edgelist=False)

This function fetches the network data for the currently loaded dataset. The data can be returned as an edgelist (pandas.DataFrame) or as a networkx.Graph object. When the data is returned as a networkx.Graph object, it will also encode the additional columns of data that were recorded for each node in the network. By default, the function returns the data as a networkx.Graph object.

Parameters:as_edgelistbool determining whether to return the data as a pandas.DataFrame.
Returns:networkx.Graph object by default. If the as_edgelist is set to True, then this method returns a pandas.DataFrame containing the weighted edgelist.
get_screen(export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True)

Exports a snapshot of the visible mapping in VIP and fetches a Plot object. If save_to_local_history is set to True, the VipPlot instance will be appended to the local_history

Returns:None
get_visible_points()

Returns indices of points visible in VIP in a pandas DataFrame.

Returns:pandas.DataFrame with one column containing an indicator of whether each point is currently visible in VIP.
graph_distance(apply=True, use_color_normalization=True, return_centralities_df=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True)

Runs the graph distance algorithms on the visible network that is currently loaded in VIP. The graph distance algorithms include betweenness centrality, closeness centrality, and eccentricity.

Parameters:
  • return_centralities_dfbool determining whether to return a pandas.DataFrame containing the centralities to the caller. Defaults to True.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • applybool determining whether to apply the betweeenness centrality result to the color dimension. Default is True. When True, color_type is automatically changed to gradient.
  • use_color_normalizationbool determining whether to use softmax color normalization when the betweenness centrality result has been applied to color. Default is True.
Returns:

pandas.DataFrame containing the results of the graph distance algorithms. If return_centralities_df is False, this returns None.

hist(x=None, y=None, z=None, color=None, size=None, shape=None, transparency=None, halo=None, halo_highlight=None, pulsation=None, pulsation_highlight=None, playback=None, arrow=None, groupby=None, x_scale=None, y_scale=None, z_scale=None, size_scale=None, transparency_scale=None, halo_scale=None, arrow_scale=None, color_type=None, x_normalization=None, y_normalization=None, z_normalization=None, size_normalization=None, transparency_normalization=None, arrow_normalization=None, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, color_bins=None, color_bin_dist=None, color_inverted=False, volume_by=None, x_bins=None, y_bins=None, z_bins=None, name=None)

Generates Histogram in VIP. Expects column name or pandas data series dimension parameters.

Parameters:
  • x – X dimension
  • y – Y dimension
  • z – Z dimension
  • color – Color dimension. Automatically uses quartile/categorical coloring.
  • size – Size dimension. Works best with continuous features
  • shape – Shape dimension. Works best with categorical features
  • transparency – Transparency dimension. Works best with continuous features.
  • halo – Halo dimension. Works with binary features
  • halo_highlight – Optionally select a single value of the feature mapped to the Halo dimension. All points with this value will show a halo.
  • pulsation – Pulsation dimension. Works best with categorical features
  • pulsation_highlight – Optionally select a single value of the feature mapped to the Pulsation dimension. All points with this value will pulsate.
  • playback – Playback dimension. Requires user interaction to be activated; otherwise shows all.
  • groupby – Group By dimension. Works with categorical columns.
  • arrow – Arrow dimension. Works with continuous and categorical features. The arrow dimension is not visible for this plot type.
  • x_scale – Scaling factor for X dimension. Value must be between .5 and 5.
  • y_scale – Scaling factor for Y dimension. Value must be between .5 and 5.
  • z_scale – Scaling factor for Z dimension. Value must be between .5 and 5.
  • size_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • transparency_scale – Scaling factor for Transparency dimension. Value must be between .5 and 5.
  • halo_scale – Scaling factor for Halo dimension. Value must be between .5 and 5.
  • arrow_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • color_type – User can select “bin” or “palette” or None (which uses VIP defaults). For categorical data, the only option is color “palette”. For numeric data, “bin” is the default.
  • color_invertedbool controlling the order of colors for all color types.
  • x_normalization – Normalization setting for X. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • y_normalization – Normalization setting for Y.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • z_normalization – Normalization setting for Z. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • size_normalization – Normalization setting for Size. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • transparency_normalization – Normalization setting for Transparency.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • arrow_normalization – Normalization setting for Arrow. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • export – Specify whether to export a capture of the plot. Defaults to “ortho”. Options are {“ortho”, “front”, “right”, “side” (same as “right”), “top”, “perspective”, None, False}.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • color_bins – sets the number of color bins to use. The max number of bins is 16. You must have at least as many unique values (in the column mapped to color) as the number of bins you set.
  • color_bin_diststr with options: {“equal”, “range”}
  • volume_by – setting for metric used for height of histogram bins; {“count”, “avg”, “sum”, “uniform”}
  • x_binsint between 1 and 1000 that sets the number of bins to use in the ‘x’ dimension
  • y_binsint between 1 and 1000 that sets the number of bins to use in the ‘y’ dimension
  • z_binsint between 1 and 1000 that sets the number of bins to use in the ‘z’ dimension
  • namestr specifying the name of the plot. Default to None. A name will be automatically generated in VIP.
Returns:

None

history(index=None, name=None, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True)

Allows users to re-plot mappings in VIP’s history entries for the current dataset. The user must specify a desired index (negative indexing is allowed) or pass the name of the desired plot. If there are multiple history entries with the requested name, the last entry with the requested name will be plotted. Users have the ability to rename a plot through the software. The user should not specify an index and a name in the same function call.

Parameters:
  • indexint index to be used on the list of previously created plots through VIP. Default value is None. For the past 1…N plots, access via index=[-1 (latest), -N] or index=[0, N - 1 (latest)].
  • namestr plot name checked against the list of previously created plots through VIP. Default value is None
  • export – Specify whether to export a capture of the plot. Defaults to “ortho”.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
Returns:

None

insights()

Runs insights in VIP

Returns:None
line(x=None, y=None, z=None, show_points=True, color=None, size=None, shape=None, transparency=None, halo=None, halo_highlight=None, pulsation=None, pulsation_highlight=None, playback=None, playback_highlight=None, arrow=None, groupby=None, x_scale=None, y_scale=None, z_scale=None, size_scale=None, transparency_scale=None, halo_scale=None, arrow_scale=None, color_type=None, x_normalization=None, y_normalization=None, z_normalization=None, size_normalization=None, transparency_normalization=None, arrow_normalization=None, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, color_bins=None, color_bin_dist=None, viewby=None, color_inverted=None, name=None)

Generates line plot in VIP. Expects column name or pandas data series dimension parameters.

Parameters:
  • x – X dimension
  • y – Y dimension
  • z – Z dimension
  • show_points – Setting for how to view the confidence ellipsoids. Valid options are {True, False, “show”, “hide”}
  • color – Color dimension. Automatically uses quartile/categorical coloring.
  • size – Size dimension. Works best with continuous features
  • shape – Shape dimension. Works best with categorical features
  • transparency – Transparency dimension. Works best with continuous features.
  • halo – Halo dimension. Works with binary features
  • halo_highlight – Optionally select a single value of the feature mapped to the Halo dimension. All points with this value will show a halo.
  • pulsation – Pulsation dimension. Works best with categorical features
  • pulsation_highlight – Optionally select a single value of the feature mapped to the Pulsation dimension. All points with this value will pulsate.
  • playback – Playback dimension. Requires user interaction to be activated; otherwise shows all.
  • playback_highlight – Optionally select a single value of the feature mapped to the Playback dimension. All points with this value will be shown and all other points will be hidden.
  • arrow – Arrow dimension. Works with continuous and categorical features.
  • groupby – Group By dimension. Works with categorical columns.
  • x_scale – Scaling factor for X dimension. Value must be between .5 and 5.
  • y_scale – Scaling factor for Y dimension. Value must be between .5 and 5.
  • z_scale – Scaling factor for Z dimension. Value must be between .5 and 5.
  • size_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • transparency_scale – Scaling factor for Transparency dimension. Value must be between .5 and 5.
  • halo_scale – Scaling factor for Halo dimension. Value must be between .5 and 5.
  • arrow_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • color_type – User can select “bin” or “palette” or None (which uses VIP defaults). For categorical data, the only option is color “palette”. For numeric data, “bin” is the default.
  • color_invertedbool controlling the order of colors for all color types.
  • x_normalization – Normalization setting for X. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • y_normalization – Normalization setting for Y.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • z_normalization – Normalization setting for Z. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • size_normalization – Normalization setting for Size. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • transparency_normalization – Normalization setting for Transparency.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • arrow_normalization – Normalization setting for Arrow. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • export – Specify whether to export a capture of the plot. Defaults to “ortho”. Options are {“ortho”, “front”, “right”, “side” (same as “right”), “top”, “perspective”, None, False}.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • color_bins – sets the number of color bins to use. The max number of bins is 16. You must have at least as many unique values (in the column mapped to color) as the number of bins you set.
  • color_bin_diststr with options: {“equal”, “range”}
  • viewby – :class:’str’ Specify the line plot series grouping dimension. Options are {“color”, “groupby”}. The default option is “color”
  • namestr specifying the name of the plot. Default to None. A name will be automatically generated in VIP.
Returns:

None

load_data(data, dataset_name=None)

Loads pandas.DataFrame into VIP. Uses column dtype to determine column type in VIP.

Parameters:
  • datapandas.DataFrame object that contains the users data.
  • dataset_name – optionally pass in a name for this dataset to show in Virtualitics
Returns:

None

load_network(network, network_name=None, edge_weight_format='similarity', export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True)

Loads a network dataset into VIP. Datasets can be loaded as networkx.Graph objects, VIP’s JSON format as a string to a file or Python dictionary, or pandas.DataFrame (for edgelists) objects. The Virtualitics API does not support Adjacency Matrix format. VIP automatically computes structure (community detection and Force Directed Layout - ForceAtlas3D) upon load of the network dataset.

Parameters:
  • network – Can be a networkx.Graph object, pandas.DataFrame containing an edgelist, str of path to JSON file, or dict representing the JSON as a dictionary.
  • network_namestr containing the desired name of the network dataset.
  • edge_weight_formatstr containing edge weight format for this data (given that the data is weighted). “Similarity” should be used when larger edge weights indicate a closer/tighter relationship between the adjacent nodes. “Distance” should be used when larger edge weight represent a looser/weaker relationship between the adjacent nodes.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
Returns:

None

load_project(path)

Loads VIP project file into software from a path local to the machine running VIP. Note that any project currently open will be discarded. To save the project first, please use VIP.save_project().

Parameters:pathstring
Returns:None
local_history

This is a list of VipPlot instances that were generated by plotting request methods (e.g. VIP.show(), VIP.hist(), etc.) or AI routine methods (e.g. VIP.smart_mapping(), VIP.pca(), etc.). To control whether a VipPlot object will be added to ‘local_history’, specify the ‘save_to_local_history’ parameter in your plotting/AI routine requests. The ‘local_history’ list is different from the VIP.history() method, which allows the user to access VipPlot objects saved to the Virtualitics Immersive Platform History panel.

Returns:[VipPlot]
log_level

int from 0 to 2. 0: quiet, 1: help, 2: debug. Help level will print messages that guide the user of important internal events. Debug level will print messages that expose a greater level of the internal state, useful for development and debugging purposes. Each level will print what is also printed at lower levels.

Returns:int
maps2d(x=None, y=None, z=None, color=None, size=None, shape=None, transparency=None, halo=None, halo_highlight=None, pulsation=None, pulsation_highlight=None, playback=None, playback_highlight=None, arrow=None, groupby=None, z_scale=None, size_scale=None, transparency_scale=None, halo_scale=None, arrow_scale=None, color_type=None, z_normalization=None, color_normalization=None, size_normalization=None, transparency_normalization=None, arrow_normalization=None, export='front', imsize=(2048, 2048), path=None, save_to_local_history=True, map_provider='ArcGIS', map_style='Topographic', heatmap_enabled=False, heatmap_intensity=None, heatmap_radius=None, heatmap_radius_unit=None, heatmap_feature=False, return_data=False, color_bins=None, color_bin_dist=None, color_inverted=None, name=None)

Generates 2D Map plot in VIP. Expects column name or pandas data series dimension parameters.

Parameters:
  • x – X dimension
  • y – Y dimension
  • z – Z dimension
  • color – Color dimension. Automatically uses quartile/categorical coloring.
  • size – Size dimension. Works best with continuous features
  • shape – Shape dimension. Works best with categorical features
  • transparency – Transparency dimension. Works best with continuous features.
  • halo – Halo dimension. Works with binary features
  • halo_highlight – Optionally select a single value of the feature mapped to the Halo dimension. All points with this value will show a halo.
  • pulsation – Pulsation dimension. Works best with categorical features
  • pulsation_highlight – Optionally select a single value of the feature mapped to the Pulsation dimension. All points with this value will pulsate.
  • playback – Playback dimension. Requires user interaction to be activated; otherwise shows all.
  • playback_highlight – Optionally select a single value of the feature mapped to the Playback dimension. All points with this value will be shown and all other points will be hidden.
  • groupby – Group By dimension. Works with categorical columns.
  • arrow – Arrow dimension. Works with continuous and categorical features. The arrow dimension is not visible for this plot type.
  • z_scale – Scaling factor for Z dimension. Value must be between .5 and 5.
  • size_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • transparency_scale – Scaling factor for Transparency dimension. Value must be between .5 and 5.
  • halo_scale – Scaling factor for Halo dimension. Value must be between .5 and 5.
  • arrow_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • color_type – User can select “gradient”, “bin”, or “palette” or None (which uses VIP defaults). For categorical data, the only option is color “palette”. For numeric data, “bin” is the default but “gradient” can also be used.
  • color_invertedbool controlling the order of colors for all color types.
  • z_normalization – Normalization setting for Z. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • color_normalization – Normalization setting for color. This can only be set if the color type is set to “Gradient”. The options are “Log10”, “Softmax”, “IHST”
  • size_normalization – Normalization setting for Size. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • transparency_normalization – Normalization setting for Transparency.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • arrow_normalization – Normalization setting for Arrow. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • export – Specify whether to export a capture of the plot. Defaults to “ortho”. Options are {“ortho”, “front”, “right”, “side” (same as “right”), “top”, “perspective”, None, False}.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • map_provider – {“ArcGIS”, “Stamen”, “OpenStreetMap”}
  • map_style – depends on the map_provider. See documentation for options.
  • heatmap_enabledbool setting for whether to use heatmap of the mapped data.
  • heatmap_intensityfloat to determine the intensity of the heatmap. heatmap_enabled must be True for this parameter to be used.
  • heatmap_radiusfloat determining the radius of sensitivity for heatmap functionality. heatmap_enabled must be True for this parameter to be used.
  • heatmap_radius_unit – determines the units of the heatmap_radius. Must be a str and one of {“Kilometers”, “Miles”, “NauticalMiles”}. heatmap_enabled must be True for this parameter to be used.
  • heatmap_featurebool to determine whether to compute a heatmap feature (computes density of points).
  • return_databool to determine whether to send back the computed heatmap feature.
  • color_bins – sets the number of color bins to use. The max number of bins is 16. You must have at least as many unique values (in the column mapped to color) as the number of bins you set.
  • color_bin_diststr with options: {“equal”, “range”}
  • namestr specifying the name of the plot. Default to None. A name will be automatically generated in VIP.
Returns:

None or pd.DataFrame if return_data is True for heatmap_feature

maps3d(x=None, y=None, z=None, color=None, size=None, shape=None, transparency=None, halo=None, halo_highlight=None, pulsation=None, pulsation_highlight=None, playback=None, playback_highlight=None, groupby=None, arrow=None, z_scale=None, size_scale=None, transparency_scale=None, halo_scale=None, arrow_scale=None, color_type=None, z_normalization=None, color_normalization=None, size_normalization=None, transparency_normalization=None, arrow_normalization=None, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, lat_long_lines=True, country_lines=None, country_labels=None, globe_style='natural', heatmap_enabled=False, heatmap_intensity=None, heatmap_radius=None, heatmap_radius_unit=None, heatmap_feature=False, return_data=False, color_bins=None, color_bin_dist=None, color_inverted=None, name=None)

Generates 3D Map plot in VIP. Expects column name or pandas data series dimension parameters.

Parameters:
  • x – X dimension
  • y – Y dimension
  • z – Z dimension
  • color – Color dimension. Automatically uses quartile/categorical coloring.
  • size – Size dimension. Works best with continuous features
  • shape – Shape dimension. Works best with categorical features
  • transparency – Transparency dimension. Works best with continuous features.
  • halo – Halo dimension. Works with binary features
  • halo_highlight – Optionally select a single value of the feature mapped to the Halo dimension. All points with this value will show a halo.
  • pulsation – Pulsation dimension. Works best with categorical features
  • pulsation_highlight – Optionally select a single value of the feature mapped to the Pulsation dimension. All points with this value will pulsate.
  • playback – Playback dimension. Requires user interaction to be activated; otherwise shows all.
  • playback_highlight – Optionally select a single value of the feature mapped to the Playback dimension. All points with this value will be shown and all other points will be hidden.
  • arrow – Arrow dimension. Works with continuous and categorical features. The arrow dimension is not visible for this plot type.
  • groupby – Group By dimension. Works with categorical columns.
  • z_scale – Scaling factor for Z dimension. Value must be between .5 and 5.
  • size_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • transparency_scale – Scaling factor for Transparency dimension. Value must be between .5 and 5.
  • halo_scale – Scaling factor for Halo dimension. Value must be between .5 and 5.
  • arrow_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • color_type – User can select “gradient”, “bin”, or “palette” or None (which uses VIP defaults). For categorical data, the only option is color “palette”. For numeric data, “bin” is the default but “gradient” can also be used.
  • color_invertedbool controlling the order of colors for all color types.
  • z_normalization – Normalization setting for Z. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • color_normalization – Normalization setting for color. This can only be set if the color type is set to “Gradient”. The options are “Log10”, “Softmax”, “IHST”
  • size_normalization – Normalization setting for Size. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • transparency_normalization – Normalization setting for Transparency.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • arrow_normalization – Normalization setting for Arrow. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • export – Specify whether to export a capture of the plot. Defaults to “ortho”. Options are {“ortho”, “front”, “right”, “side” (same as “right”), “top”, “perspective”, None, False}.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • lat_long_linesbool visibility setting for Latitude/Longitude lines.
  • country_linesbool visibility setting for country border lines.
  • country_labelsbool visibility setting for country labels.
  • globe_style – {“natural”, “dark”, “black ocean”, “blue ocean”, “gray ocean”, “water color”, “topographic”, “moon”, “night”}
  • heatmap_enabledbool setting for whether to use heatmap of the mapped data.
  • heatmap_intensityfloat to determine the intensity of the heatmap. heatmap_enabled must be True for this parameter to be used.
  • heatmap_radiusfloat determining the radius of sensitivity for heatmap functionality. heatmap_enabled must be True for this parameter to be used.
  • heatmap_radius_unit – determines the units of the heatmap_radius. Must be a str and one of {“Kilometers”, “Miles”, “NauticalMiles”}. heatmap_enabled must be True for this parameter to be used.
  • heatmap_featurebool to determine whether to compute a heatmap feature (computes density of points).
  • return_databool to determine whether to send back the computed heatmap feature.
  • color_bins – sets the number of color bins to use. The max number of bins is 16. You must have at least as many unique values (in the column mapped to color) as the number of bins you set.
  • color_bin_diststr with options: {“equal”, “range”}
  • namestr specifying the name of the plot. Default to None. A name will be automatically generated in VIP.
Returns:

None or pd.DataFrame if return_data is True for heatmap_feature

network_extractor(node_column, associative_columns, pivot_type='mean', export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, bypass_warning=False)

Network extractor is a beta functionality (please submit feedback to “support@virtualitics.com”). With this method, you can extract network structures from non-network data. You must specify a column containing entities you would like to use as nodes as the ‘node_column.’ Furthermore, you must specify a list containing at least one column of values that will be used to find associations between the selected nodes. There can be multiple rows of data about any given node. This tool is especially useful for analyzing categorical columns of data.

Parameters:
  • node_columnpandas.Series containing values which will be treated as nodes in a network.
  • associative_columns – [pandas.Series] containing list of columns that will be used to find associations between the nodes.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • bypass_warningbool; whether to bypass warning from Network Extractor tool that warns the user that the variety and size of the data will require large computational resources and memory. Use with care.
Returns:

None

network_structure(apply=True, return_structure_df=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True)

Runs the network structure algorithms on the visible network that is currently loaded in VIP. Network structure algorithms include community detection and ForceAtlas3D. The results will also included degree and weighted degree results.

Parameters:
  • return_structure_dfbool determining whether to return a pandas.DataFrame containing the structure results to the caller. Defaults to True.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • applybool determining whether to map the network structure. Default is True.
Returns:

pandas.DataFrame containing the results of the network structure. If return_structure_df is False, this returns None.

normalize(norm_type='Softmax', export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True)

Normalizes the axis for spatial dimensions in VIP if applicable.

Parameters:
  • norm_type – The type of normalization to apply to the data. Can be “softmax”, “log10”, or “ihst”
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
Returns:

None

pagerank(damping_factor=0.85, apply=True, use_color_normalization=True, return_pagerank_df=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True)

Runs PageRank algorithm on the visible network that is currently loaded in VIP.

Parameters:
  • damping_factorfloat between 0 and 1 representing the damping factor for the PageRank algorithm. Defaults to 0.85 which is widely considered a good value. Users are recommended not to change this unless they are familiar with the PageRank algorithm.
  • return_pagerank_df – Whether to return the output of the process to the notebook. Defaults to True.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • applybool determining whether to apply the pagerank result to the color dimension. Default is True. When True, color_type is automatically changed to gradient.
  • use_color_normalizationbool determining whether to use softmax color normalization when the pagerank result has been applied to color. Default is True.
Returns:

pandas.DataFrame containing the results of the pagerank. If return_pagerank_df is false, this returns None.

pca(num_components, features=None, exclude=None, apply=True, return_components_df=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, keep_missing_value_columns=True)

Runs Principal Component Analysis (PCA) in VIP

Parameters:
  • num_componentsint for the number of principle components to compute from the input data. The number of components must be within [1, 10] and cannot be greater than the number of features to run on.
  • features – List of column names that user wants to analyze
  • exclude – List of column names to exclude in the analysis; this overrides any features listed in the features parameter.
  • return_components_df – Whether to return the output of the process to the notebook. Defaults to True.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • applybool determining whether to apply the first 3 computed components to the spatial dimensions. Default is True.
  • keep_missing_value_columnsbool for whether to keep features with more than 50% missing values as part of the input for pca. Default is True.
Returns:

if return_data is True, this returns a pandas.DataFrame containing the user specified number of principal components. Otherwise, this returns None.

pca_ad(features=None, exclude=None, return_anomalies_df=True, threshold=1, apply=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, keep_missing_value_columns=True)

Alias to pca_anomaly_detection

Parameters:
  • features – List of column names that user wants to analyze for outliers
  • exclude – List of column names to exclude in the analysis; this overrides any features listed in the features parameter.
  • threshold – Percent threshold on which to classify outliers. Takes values from 0 to 100 exclusive. Defaults to a threshold of 1.
  • return_anomalies_df – Whether to return the output of the process to the notebook. Defaults to True.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • applybool determining whether to apply the anomaly detection result to the halo dimension. Default is True.
  • keep_missing_value_columnsbool for whether to keep features with more than 50% missing values as part of the input for pca based anomaly detection. Default is True.
Returns:

None

pca_anomaly_detection(features=None, exclude=None, return_anomalies_df=True, threshold=1, apply=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, keep_missing_value_columns=True)

PCA based Anomaly Detection.

Parameters:
  • features – List of column names that user wants to analyze for outliers
  • exclude – List of column names to exclude in the analysis; this overrides any features listed in the features parameter.
  • threshold – Percent threshold on which to classify outliers. Takes values from 0 to 100 exclusive. Defaults to a threshold of 1.
  • return_anomalies_df – Whether to return the output of the process to the notebook. Defaults to True.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • applybool determining whether to apply the anomaly detection result to the halo dimension. Default is True.
  • keep_missing_value_columnsbool for whether to keep features with more than 50% missing values as part of the input for pca based anomaly detection. Default is True.
Returns:

None

plot(plot_type='scatter', x=None, y=None, z=None, color=None, size=None, shape=None, transparency=None, halo=None, halo_highlight=None, pulsation=None, pulsation_highlight=None, playback=None, playback_highlight=None, arrow=None, groupby=None, x_scale=None, y_scale=None, z_scale=None, size_scale=None, transparency_scale=None, halo_scale=None, arrow_scale=None, color_type=None, color_normalization=None, x_normalization=None, y_normalization=None, z_normalization=None, size_normalization=None, transparency_normalization=None, arrow_normalization=None, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, color_bins=None, color_bin_dist=None, color_inverted=None, name=None)

Requests VIP to make the specified plot. Expects column name or pandas.Series dimension parameters. Plot type is expected to be string.

Parameters:
  • plot_type – {“scatter”, “hist”, “line”, “maps3d”, “maps2d”, “ellipsoid”, “surface”, “convex_hull”}; default is “scatter”
  • x – X dimension
  • y – Y dimension
  • z – Z dimension
  • color – Color dimension. Automatically uses quartile/categorical coloring.
  • size – Size dimension. Works best with continuous features
  • shape – Shape dimension. Works best with categorical features
  • transparency – Transparency dimension. Works best with continuous features.
  • halo – Halo dimension. Works with binary features
  • halo_highlight – Optionally select a single value of the feature mapped to the Halo dimension. All points with this value will show a halo.
  • pulsation – Pulsation dimension. Works best with categorical features
  • pulsation_highlight – Optionally select a single value of the feature mapped to the Pulsation dimension. All points with this value will pulsate.
  • playback – Playback dimension. Requires user interaction to be activated; otherwise shows all.
  • playback_highlight – Optionally select a single value of the feature mapped to the Playback dimension. All points with this value will be shown and all other points will be hidden.
  • arrow – Arrow dimension. Works with continuous and categorical features.
  • groupby – Group By dimension. Works with categorical columns.
  • x_scale – Scaling factor for X dimension. Value must be between .5 and 5.
  • y_scale – Scaling factor for Y dimension. Value must be between .5 and 5.
  • z_scale – Scaling factor for Z dimension. Value must be between .5 and 5.
  • size_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • transparency_scale – Scaling factor for Transparency dimension. Value must be between .5 and 5.
  • halo_scale – Scaling factor for Halo dimension. Value must be between .5 and 5.
  • arrow_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • color_type – User can select “gradient”, “bin”, or “palette” or None (which uses VIP defaults). For categorical data, the only option is color “palette”. For numeric data, “bin” is the default but “gradient” can also be used.
  • color_invertedbool controlling the order of colors for all color types.
  • color_normalization – Normalization setting for color. This can only be set if the color type is set to “Gradient”. The options are “Log10”, “Softmax”, “IHST”
  • x_normalization – Normalization setting for X. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • y_normalization – Normalization setting for Y.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • z_normalization – Normalization setting for Z. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • size_normalization – Normalization setting for Size. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • transparency_normalization – Normalization setting for Transparency.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • arrow_normalization – Normalization setting for Arrow. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • export – Specify whether to export a capture of the plot. Defaults to “ortho”. Options are {“ortho”, “front”, “right”, “side” (same as “right”), “top”, “perspective”, None, False}.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • color_bins – sets the number of color bins to use. The max number of bins is 16. You must have at least as many unique values (in the column mapped to color) as the number of bins you set.
  • color_bin_diststr with options: {“equal”, “range”}
  • namestr specifying the name of the plot. Default to None. A name will be automatically generated in VIP.
Returns:

None

pull_new_columns()

Gets new columns that were added to the currently loaded dataset since the last invocation of this method. This does not include columns from the initial loading of a dataset (call get_dataset() to access these) or columns created from via ML routines, such as clustering and PCA, that have not been added to the feature list.

Returns:pandas.DataFrame
remove_all_filters(export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True)
Parameters:
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
Returns:

None

remove_filter(feature_name, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True)
Parameters:
  • feature_name – Name of feature to remove any filter on if it exists
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
Returns:

None

save_project(filename: str, overwrite=False)

Saves VIP project to the specified filepath.

Parameters:
  • filename – absolute or relative path to the desired save location.
  • overwritebool that controls whether to write over a file that may exist at the specified path.
Returns:

None

scatter(x=None, y=None, z=None, color=None, size=None, shape=None, transparency=None, halo=None, halo_highlight=None, pulsation=None, pulsation_highlight=None, playback=None, playback_highlight=None, arrow=None, groupby=None, x_scale=None, y_scale=None, z_scale=None, size_scale=None, transparency_scale=None, halo_scale=None, arrow_scale=None, color_type=None, color_normalization=None, x_normalization=None, y_normalization=None, z_normalization=None, size_normalization=None, transparency_normalization=None, arrow_normalization=None, color_inverted=None, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, color_bins=None, color_bin_dist=None, name=None)

Generates scatter plot in VIP. Expects column name or pandas data series dimension parameters.

Parameters:
  • x – X dimension
  • y – Y dimension
  • z – Z dimension
  • color – Color dimension. Automatically uses quartile/categorical coloring.
  • size – Size dimension. Works best with continuous features
  • shape – Shape dimension. Works best with categorical features
  • transparency – Transparency dimension. Works best with continuous features.
  • halo – Halo dimension. Works with binary features
  • halo_highlight – Optionally select a single value of the feature mapped to the Halo dimension. All points with this value will show a halo.
  • pulsation – Pulsation dimension. Works best with categorical features
  • pulsation_highlight – Optionally select a single value of the feature mapped to the Pulsation dimension. All points with this value will pulsate.
  • playback – Playback dimension. Requires user interaction to be activated; otherwise shows all.
  • playback_highlight – Optionally select a single value of the feature mapped to the Playback dimension. All points with this value will be shown and all other points will be hidden.
  • arrow – Arrow dimension. Works with continuous and categorical features.
  • groupby – Group By dimension. Works with categorical columns.
  • x_scale – Scaling factor for X dimension. Value must be between .5 and 5.
  • y_scale – Scaling factor for Y dimension. Value must be between .5 and 5.
  • z_scale – Scaling factor for Z dimension. Value must be between .5 and 5.
  • size_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • transparency_scale – Scaling factor for Transparency dimension. Value must be between .5 and 5.
  • halo_scale – Scaling factor for Halo dimension. Value must be between .5 and 5.
  • arrow_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • color_type – User can select “gradient”, “bin”, or “palette” or None (which uses VIP defaults). For categorical data, the only option is color “palette”. For numeric data, “bin” is the default but “gradient” can also be used.
  • color_normalization – Normalization setting for color. This can only be set if the color type is set to “Gradient”. The options are “Log10”, “Softmax”, “IHST”
  • color_invertedbool controlling the order of colors for all color types.
  • x_normalization – Normalization setting for X. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • y_normalization – Normalization setting for Y.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • z_normalization – Normalization setting for Z. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • size_normalization – Normalization setting for Size. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • transparency_normalization – Normalization setting for Transparency.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • arrow_normalization – Normalization setting for Arrow. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • export – Specify whether to export a capture of the plot. Defaults to “ortho”. Options are {“ortho”, “front”, “right”, “side” (same as “right”), “top”, “perspective”, None, False}.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • color_bins – sets the number of color bins to use. The max number of bins is 16. You must have at least as many unique values (in the column mapped to color) as the number of bins you set.
  • color_bin_diststr with options: {“equal”, “range”}
  • namestr specifying the name of the plot. Default to None. A name will be automatically generated in VIP.
Returns:

None

set_camera_angle(angle)

Sets the camera angle in VIP (does not effect export camera angle).

Parameters:anglestr controlling camera angle in VIP. {“Default”, “Top”, “Front”, “Side”}
Returns:None
set_gridbox_tickmarks_view(gridbox=None, tickmarks=None)

Sets the visibility of the gridbox and tickmarks. Expects one or both of gridbox and tickmarks to be not None.

Parameters:
  • gridboxbool controlling visibility of gridbox. True sets to “show”, False sets to “hide”
  • tickmarksbool controlling visibility of tickmarks. True sets to “show”, False sets to “hide’
Returns:

None

shape_options(render_mode)

Updates optimization mode of software by setting the shape options render mode.

Parameters:render_modestr to set the shape options (formerly point render) mode. Can be {“Shapes”, “Default”, “2D”, “Points”, “Point Cloud”, or “PointCloud”}. The “Default” case yields 2D billboard rendering of the data points.
Returns:None
show(plot: virtualitics.vip_plot.VipPlot, display=True, save_to_local_history=True, export='ortho', imsize=(2048, 2048), path=None)

Recreates a plot in VIP from a VipPlot instance.

Parameters:
  • plot – VipPlot instance that contains all important details to send to VIP
  • displaybool flag for whether to show this plot to the user
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • export – Specify whether to export a capture of the plot. defaults to “ortho”. If the plot type is “MAPS2D”, the export setting will be set to “front” regardless of requested parameter, unless the user passes None/False.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
Returns:

None

smart_mapping(target, features=None, exclude=None, export='ortho', imsize=(2048, 2048), return_results_df=False, path=None, save_to_local_history=True, keep_missing_value_columns=True)

Runs smart mapping in VIP.

Parameters:
  • target – Target column that the user wants to find insights about; this feature will be dropped automatically from Smart Mapping input regardless of what is listed in the features and exclude parameters.
  • features – List of column names that user wants to analyze in comparison to target
  • exclude – List of column names to exclude in the analysis; this overrides any features listed in the features parameter.
  • return_results_dfbool for whether to return the feature ranking and correlation groups pd.DataFrame. The default is False; in which case the head of the feature ranking pd.DataFrame is displayed.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • keep_missing_value_columnsbool for whether to keep features with more than 50% missing values as part of the input for smart mapping. Default is True.
Returns:

if ‘return_results_df’ is True, this returns the feature importance and correlation groups of the input features as a pd.DataFrame.

statistics()

Runs statistics in VIP

Returns:None
stats()

Alias for statistics

surface(show_points=False, x=None, y=None, z=None, color=None, size=None, shape=None, transparency=None, halo=None, halo_highlight=None, pulsation=None, pulsation_highlight=None, playback=None, playback_highlight=None, arrow=None, groupby=None, x_scale=None, y_scale=None, z_scale=None, size_scale=None, transparency_scale=None, halo_scale=None, arrow_scale=None, color_type=None, color_normalization=None, x_normalization=None, y_normalization=None, z_normalization=None, size_normalization=None, transparency_normalization=None, arrow_normalization=None, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, color_bins=None, color_bin_dist=None, color_inverted=None, name=None)

Generates Surface plot in VIP. Expects column name or pandas data series dimension parameters.

Parameters:
  • show_points – Setting for how to view the surface. Valid options are {True, False, “show”, “hide”}
  • x – X dimension
  • y – Y dimension
  • z – Z dimension
  • color – Color dimension. Automatically uses quartile/categorical coloring.
  • size – Size dimension. Works best with continuous features
  • shape – Shape dimension. Works best with categorical features
  • transparency – Transparency dimension. Works best with continuous features.
  • halo – Halo dimension. Works with binary features
  • halo_highlight – Optionally select a single value of the feature mapped to the Halo dimension. All points with this value will show a halo.
  • pulsation – Pulsation dimension. Works best with categorical features
  • pulsation_highlight – Optionally select a single value of the feature mapped to the Pulsation dimension. All points with this value will pulsate.
  • playback – Playback dimension. Requires user interaction to be activated; otherwise shows all.
  • playback_highlight – Optionally select a single value of the feature mapped to the Playback dimension. All points with this value will be shown and all other points will be hidden.
  • arrow – Arrow dimension. Works with continuous and categorical features.
  • groupby – Group By dimension. Works with categorical columns.
  • x_scale – Scaling factor for X dimension. Value must be between .5 and 5.
  • y_scale – Scaling factor for Y dimension. Value must be between .5 and 5.
  • z_scale – Scaling factor for Z dimension. Value must be between .5 and 5.
  • size_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • transparency_scale – Scaling factor for Transparency dimension. Value must be between .5 and 5.
  • halo_scale – Scaling factor for Halo dimension. Value must be between .5 and 5.
  • arrow_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • color_type – User can select “gradient”, “bin”, or “palette” or None (which uses VIP defaults). For categorical data, the only option is color “palette”. For numeric data, “bin” is the default but “gradient” can also be used.
  • color_invertedbool controlling the order of colors for all color types.
  • color_normalization – Normalization setting for color. This can only be set if the color type is set to “Gradient”. The options are “Log10”, “Softmax”, “IHST”
  • x_normalization – Normalization setting for X. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • y_normalization – Normalization setting for Y.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • z_normalization – Normalization setting for Z. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • size_normalization – Normalization setting for Size. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • transparency_normalization – Normalization setting for Transparency.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • arrow_normalization – Normalization setting for Arrow. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • export – Specify whether to export a capture of the plot. Defaults to “ortho”. Options are {“ortho”, “front”, “right”, “side” (same as “right”), “top”, “perspective”, None, False}.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • color_bins – sets the number of color bins to use. The max number of bins is 16. You must have at least as many unique values (in the column mapped to color) as the number of bins you set.
  • color_bin_diststr with options: {“equal”, “range”}
  • namestr specifying the name of the plot. Default to None. A name will be automatically generated in VIP.
Returns:

None

switch_dataset(name: str)

Switches Dataset context in VIP.

Parameters:namestr for the name of the dataset or network to bring into context.
Returns:None
threshold_ad(features=None, exclude=None, return_anomalies_df=True, threshold=1, apply=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, keep_missing_value_columns=True)

Alias to pca_anomaly_detection

Parameters:
  • features – List of column names that user wants to analyze for outliers
  • exclude – List of column names to exclude in the analysis; this overrides any features listed in the features parameter.
  • threshold – Percent threshold on which to classify outliers. Takes values from 0 to 100 exclusive. Defaults to a threshold of 1.
  • return_anomalies_df – Whether to return the output of the process to the notebook. Defaults to True.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • applybool determining whether to apply the anomaly detection result to the halo dimension. Default is True.
  • keep_missing_value_columnsbool for whether to keep features with more than 50% missing values as part of the input for pca based anomaly detection. Default is True.
Returns:

None

threshold_anomaly_detection(features=None, exclude=None, return_anomalies_df=True, threshold=1, apply=True, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, keep_missing_value_columns=True)

Alias to pca_anomaly_detection

Parameters:
  • features – List of column names that user wants to analyze for outliers
  • exclude – List of column names to exclude in the analysis; this overrides any features listed in the features parameter.
  • threshold – Percent threshold on which to classify outliers. Takes values from 0 to 100 exclusive. Defaults to a threshold of 1.
  • return_anomalies_df – Whether to return the output of the process to the notebook. Defaults to True.
  • export – Specify whether to export a capture of the plot. Can be None/False or “ortho”, “front”, “side” or “right”, “top”, or “perspective”
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • applybool determining whether to apply the anomaly detection result to the halo dimension. Default is True.
  • keep_missing_value_columnsbool for whether to keep features with more than 50% missing values as part of the input for pca based anomaly detection. Default is True.
Returns:

None

violin(x=None, y=None, z=None, color=None, size=None, shape=None, transparency=None, halo=None, halo_highlight=None, pulsation=None, pulsation_highlight=None, playback=None, playback_highlight=None, arrow=None, groupby=None, x_scale=None, y_scale=None, z_scale=None, size_scale=None, transparency_scale=None, halo_scale=None, arrow_scale=None, color_type=None, color_normalization=None, x_normalization=None, y_normalization=None, z_normalization=None, size_normalization=None, transparency_normalization=None, arrow_normalization=None, export='ortho', imsize=(2048, 2048), path=None, save_to_local_history=True, color_bins=None, color_bin_dist=None, color_inverted=None, name=None)

Generates violin plot in VIP. Expects column name or pandas data series dimension parameters.

Parameters:
  • x – X dimension
  • y – Y dimension
  • z – Z dimension
  • color – Color dimension. Automatically uses quartile/categorical coloring.
  • size – Size dimension. Works best with continuous features
  • shape – Shape dimension. Works best with categorical features
  • transparency – Transparency dimension. Works best with continuous features.
  • halo – Halo dimension. Works with binary features
  • halo_highlight – Optionally select a single value of the feature mapped to the Halo dimension. All points with this value will show a halo.
  • pulsation – Pulsation dimension. Works best with categorical features
  • pulsation_highlight – Optionally select a single value of the feature mapped to the Pulsation dimension. All points with this value will pulsate.
  • playback – Playback dimension. Requires user interaction to be activated; otherwise shows all.
  • playback_highlight – Optionally select a single value of the feature mapped to the Playback dimension. All points with this value will be shown and all other points will be hidden.
  • arrow – Arrow dimension. Works with continuous and categorical features.
  • groupby – Group By dimension. Works with categorical columns.
  • x_scale – Scaling factor for X dimension. Value must be between 5 and 5.
  • y_scale – Scaling factor for Y dimension. Value must be between .5 and 5.
  • z_scale – Scaling factor for Z dimension. Value must be between .5 and 5.
  • size_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • transparency_scale – Scaling factor for Transparency dimension. Value must be between .5 and 5.
  • halo_scale – Scaling factor for Halo dimension. Value must be between .5 and 5.
  • arrow_scale – Scaling factor for Size dimension. Value must be between .5 and 5.
  • color_type – User can select “gradient”, “bin”, or “palette” or None (which uses VIP defaults). For categorical data, the only option is color “palette”. For numeric data, “bin” is the default but “gradient” can also be used.
  • color_invertedbool controlling the order of colors for all color types.
  • color_normalization – Normalization setting for color. This can only be set if the color type is set to “Gradient”. The options are “Log10”, “Softmax”, “IHST”
  • x_normalization – Normalization setting for X. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • y_normalization – Normalization setting for Y.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • z_normalization – Normalization setting for Z. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • size_normalization – Normalization setting for Size. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • transparency_normalization – Normalization setting for Transparency.This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • arrow_normalization – Normalization setting for Arrow. This can only be set if the feature mapped to this dimension is numerical and continuous. The options are “Log10”, “Softmax”, “IHST”
  • export – Specify whether to export a capture of the plot. Defaults to “ortho”. Options are {“ortho”, “front”, “right”, “side” (same as “right”), “top”, “perspective”, None, False}.
  • imsize – size of the returned dimension; [w, h]. Only used if export is not None. Defaults to (2048, 2048)
  • save_to_local_historybool; whether to save VipPlot object to this.local_history list. Default value is True.
  • path – Filepath to save snapshot; filepath should end with a jpg/jpeg/png/bmp extension
  • color_bins – sets the number of color bins to use. The max number of bins is 16. You must have at least as many unique values (in the column mapped to color) as the number of bins you set.
  • color_bin_diststr with options: {“equal”, “range”}
  • namestr specifying the name of the plot. Default to None. A name will be automatically generated in VIP.
Returns:

None

virtualitics.vip_plot

class virtualitics.vip_plot.VipPlot(data_set_name=None, plot_type='scatter', x=None, y=None, z=None, color=None, size=None, shape=None, transparency=None, halo=None, halo_highlight=None, pulsation=None, pulsation_highlight=None, playback=None, playback_highlight=None, arrow=None, groupby=None, x_scale=None, y_scale=None, z_scale=None, size_scale=None, transparency_scale=None, halo_scale=None, arrow_scale=None, color_type=None, color_normalization=None, x_normalization=None, y_normalization=None, z_normalization=None, size_normalization=None, transparency_normalization=None, arrow_normalization=None, show_points=None, confidence=None, map_mode=None, globe_style=None, lat_long_lines=None, country_lines=None, country_labels=None, heatmap_enabled=None, heatmap_intensity=None, heatmap_radius=None, heatmap_radius_unit=None, map_provider=None, map_style=None, color_bins=None, color_bin_dist=None, hist_volume_by=None, viewby=None, x_bins=None, y_bins=None, z_bins=None, color_inverted=None, log_level=0, name=None, _dataset_type=None)

The plot class contains all essential details of a plot in VIP.

arrow

Arrow dimension (Extra dimension). Should be set to str of the feature name to be mapped to arrow dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that arrow dimension will not be mapped.

Returns:str
arrow_normalization

Arrow normalization setting. Must be set str and match with one of the normalization options listed here: {“softmax”, “Log10”, “IHST”, None}. Arrow normalization is only applicable when ‘arrow’ dimension has been mapped. Default is ‘None’ which implies that normalization will not be applied to the ‘arrow’ dimension.

Returns:str
arrow_scale

Arrow scale setting. Must be set to float with value between .5 and 5. Default value ‘None’ leaves VIP to default scaling value.

Returns:float
color

Color dimension (appearance dimension). Should be set to :class:’str’ of the feature name to be mapped to color dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that color dimension will not be mapped. Default color type depends on column type (continuous or categorical).

Returns:str feature name to map to color dimension
color_bin_dist

Color bin distribution setting. Must be a str that matches one of {“equal”, “range}. Default of ‘None’ leaves the color bin distribution in VIP as default (‘equal’). Color bin distribution is only applicable when a feature has been mapped ‘color’

Returns:str
color_bins

Color bin setting. Must be set to int between 1 and 16. The color bin setting is only applicable when ‘color’ dimension has been mapped. Default value of ‘None’ will set color bins to the min(unique values of the feature mapped to color, 4).

Returns:int
color_inverted

Color Inversion state. Must be a bool. Default of False leaves the color bins, palette, or gradient as is. Value of True inverts the color order regardless of color type. Color inversion is only applicable when a feature has been mapped to ‘color’

Returns:None
color_normalization

Color normalization setting. Must be set str and match with one of the Normalization options listed here: {“Softmax”, “Log10”, “IHST”, None}. Color normalization is only applicable when ‘color’ dimension is mapped and color type has been set to ‘gradient.’ Default is ‘None’ which implies that normalization will not be applied to ‘color’ dimension.

Returns:str
color_type

Color type setting. Must be set to str and match one of the following {“gradient”, “bin”, “palette”, None}. Default value ‘None’ leaves VIP to default color type based, which is dependent on the feature mapped to color. Color type setting is only applicable when the ‘color’ dimension has been mapped.

Returns:str
confidence

Confidence setting. Must be set to a float and match one of {99.5, 99.0, 97.5, 95.0, 90.0, 80.0, 75.0, 70.0, 50.0, 30.0, 25.0, 20.0, 10.0, 5.0, 2.5, 1.0, .5}. Show points is only applicable when ‘plot_type’ is “CONFIDENCE_ELLIPSOID”. Default is ‘None’ which implies VIP will use the default confidence interval for the Ellipsoid plot.

Returns:float
country_labels

Country labels setting. Must be set to bool or str and match on of {“show”, True, “hide”, False}. ‘country_labels’ is only applicable when the plot type is set to ‘MAPS3D’. Default is ‘None’ which implies VIP will use the default for country labels.

Returns:bool
country_lines

Country Lines setting. Must be set to bool or str and match on of {“show”, True, “hide”, False}. ‘country_lines’ is only applicable when the plot type is set to ‘MAPS3D’. Default is ‘None’ which implies VIP will use the default for country lines.

Returns:bool
data_set_name

str Name of the dataset to use when creating the plot. default: None implies use the currently loaded dataset.

Returns:str
get_best_export_view()

Determines if there is only one good view of the plot that will be generated.

Returns:str if there is a better view or None otherwise.
get_params()

Prepares a dictionary that contains the plot dimensions and all settings to be sent over in an API request.

Returns:dict
get_plot_type()

Getter for the hidden attribute that is managed by the plot_type(val) method.

Returns:str
globe_style

Globe style setting. Must be set to str that matches one of {“natural”, “dark”, “black ocean”, “blue ocean”, “gray ocean”, “water color”, “topographic”, “moon”, “night”}. Globe style setting is only applicable when ‘plot_type’ is set to “MAPS3D”. Default is ‘None’ which implies VIP will use the default globe style.

Returns:str
groupby

Groupby dimension (refine dimension). Should be set to str of the feature name to be mapped to groupby dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that groupby dimension will not be mapped.

Returns:str
halo

Halo dimension (Extra dimension). Should be set to str of the feature name to be mapped to halo dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that halo dimension will not be mapped.

Returns:str
halo_highlight

Halo highlight setting. Must be set to a string and match one of the values of the feature mapped to “halo”.

Returns:class:string or numeric
halo_scale

Halo scale setting. Must be set to float with value between .5 and 5. Default value ‘None’ leaves VIP to default scaling value.

Returns:float
heatmap_enabled

Heatmap enabled setting. Must be set to bool. Heatmaps are only applicable for geospatial plots. Default value is None which implies that VIP will not generate heatmap visualizations.

Returns:bool
heatmap_intensity

Heatmap intensity setting. Must be set to a float between 0 and 1. Heatmaps are only applicable for geospatial plots. Heatmap intensity setting is only applicable if the heatmap_enabled is set to True.

Returns:float
heatmap_radius

Heatmap radius setting. Must be set to a float between 0 and 1. Heatmaps are only applicable for geospatial plots. Heatmap radius setting is only applicable if the heatmap_enabled is set to True.

Returns:float
heatmap_radius_unit

Heatmap radius unit setting. Must be set to a float between 0 and 1. Heatmaps are only applicable for geospatial plots. Heatmap radius setting is only applicable if the heatmap_enabled is set to True.

Returns:str and one of {“Kilometers”, “Miles”, “NauticalMiles”}.
hist_volume_by

Histogram volume by setting. Must be set to str and match with one of {“count”, “avg”, “sum”, “uniform”}. Histogram volume by is only applicable if the ‘plot_type’ is ‘HISTOGRAM’. Default value is ‘None’ which implies VIP will use the default setting for volume by on histogram plots.

Returns:str
is_geospatial_plot()

Checks if the current plot type is a geospatial plot type. This is used when determining whether certain plot settings are applicable.

Returns:bool
is_spatial_dimension_used()

Checks if any of the ‘x’, ‘y’, or ‘z’ properties are not None. This is used before attempting to map appearance, refinement, or extra dimensions.

Returns:bool
lat_long_lines

Latitude/Longitude Lines setting. Must be set to bool or str and match on of {“show”, True, “hide”, False}. ‘lat_long_lines’ is only applicable when the plot type is set to ‘MAPS3D’. Default is ‘None’ which implies VIP will use the default for latitude/longitude lines.

Returns:bool
log_level

int from 0 to 2. 0: quiet, 1: help, 2: debug

Returns:int
map_provider

Map provider setting. Must be set to str and match with one of {“ArcGIS”, “Stamen”, “OpenStreetMap”} or None, which is the default and sets VIP to use the default map provider for relevant plots. Map provider is only applicable when plot type is set to ‘MAPS2D’.

Returns::class`str`
map_provider_style(provider=None, style=None)
Parameters:
  • provider – Map provider setting. Must be set to str and match with one of {“ArcGIS”, “Stamen”, “OpenStreetMap”} or None, which is the default and sets VIP to use the default map provider for relevant plots. Map provider is only applicable when plot type is set to ‘MAPS2D’.
  • style – Map style settings. Must be set to str and match one of the following depending on the map provider: ArcGIS: {“Topographic”, “Ocean”, “Imagery”, “Gray”}, OpenStreetMap: {“Mapnik”}, Stamen: {“Dark”, “Light”, “Watercolor”, “Terrain”}. Map style is only applicable when plot_type is set to ‘MAPS2D’. The default is None which implies VIP will use the default map style for the currently set map provider.
Returns:

None

map_style

Map style settings. Must be set to str and match one of the following depending on the map provider: ArcGIS: {“Topographic”, “Ocean”, “Imagery”, “Gray”}, OpenStreetMap: {“Mapnik”}, Stamen: {“Dark”, “Light”, “Watercolor”, “Terrain”} Map style is only applicable when plot_type is set to ‘MAPS2D’. The default is None which implies VIP will use the default map style for the currently set map provider.

Returns:str
playback

Playback dimension (refine dimension). Should be set to str of the feature name to be mapped to playback dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that playback dimension will not be mapped.

Returns:str
playback_highlight

Playback highlight setting. Must be set to a string and match one of the values of the feature mapped to “playback”.

Returns:class:string or numeric
plot_type(val)

Changes the plot type for the object. The passed value must be a str and the valid values are {“scatter”, “histogram”, “line”, “violin”, “ellipsoid”, “convex_hull”, “surface”, “maps2d”, “maps3d”}. Default value of None implies “scatter” plot, which is the default plot type in VIP. Changing the plot type may clear some plot settings based on the state of the plot object with the old plot type. This is to ensure that an illegal VipPlot object instance is not created.

Parameters:valstr
Returns:None
pulsation

Pulsation dimension (Extra dimension). Should be set to str of the feature name to be mapped to pulsation dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that pulsation dimension will not be mapped.

Returns:str
pulsation_highlight

Pulsation highlight setting. Must be set to a string and match one of the values of the feature mapped to “pulsation”.

Returns:class:string or numeric
shape

Shape dimension (appearance dimension). Should be set to str of the feature name to be mapped to shape dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that shape dimension will not be mapped.

Returns:str
show_points

Show points setting. Must be set to a bool. Show points is only applicable when ‘plot_type’ is set to one of the surface or line plot types: {“CONFIDENCE_ELLIPSOID”, “CONVEX_HULL”, “SURFACE”, “LINE_PLOT”}

Returns:bool
size

Size dimension (appearance dimension). Should be set to :class:’str’ of the feature name to be mapped to size dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that size dimension will not be mapped.

Returns:str
size_normalization

Size normalization setting. Must be set str and match with one of the normalization options listed here: {“softmax”, “Log10”, “IHST”, None}. Size normalization is only applicable when ‘size’ dimension has been mapped. Default is ‘None’ which implies that normalization will not be applied to the ‘size’ dimension.

Returns:str
size_scale

Size scale setting. Must be set to float with value between .5 and 5. Default value ‘None’ leaves VIP to default scaling value.

Returns:float
transparency

Transparency dimension (Extra dimension). Should be set to str of the feature name to be mapped to transparency dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that transparency dimension will not be mapped.

Returns:str
transparency_normalization

Transparency normalization setting. Must be set str and match with one of the normalization options listed here: {“softmax”, “Log10”, “IHST”, None}. Transparency normalization is only applicable when ‘transparency’ dimension has been mapped. Default is ‘None’ which implies that normalization will not be applied to the ‘transparency’ dimension.

Returns:str
transparency_scale

Transparency scale setting. Must be set to float with value between .5 and 5. Default value ‘None’ leaves VIP to default scaling value.

Returns:float
viewby

Line plot view by setting. Must be set to str and match with one of {“color”, “groupby”}. View by is only applicable if the ‘plot_type’ is ‘LINE_PLOT’. Default value is ‘None’ which implies VIP will use the default setting for view by on line plots.

Returns:str
x

X dimension (Spatial dimension). Should be set to str of the feature name to be mapped to X dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that X dimension will not be mapped.

Returns:str feature name to map to X dimension.
x_bins

X bins setting. Must be a int between 1 and 1000. X bins is only applicable if the ‘plot_type’ has been set to “HISTOGRAM”. If there are multiple spatial dimensions (X, Y, Z) mapped, there are additional constraints for permissible values.

Returns:int between 1 and 1000
x_normalization

X normalization setting. Must be set to str and match with one of the Normalization options listed here: {“Softmax”, “Log10”, “IHST”, None}. X normalization is only applicable when ‘x’ dimension is mapped. X normalization is not applicable for Geospatial plots.

Returns:str
x_scale

X scale setting. Must be set to float with value between .5 and 5. Default value ‘None’ leaves VIP to default scaling value. X scale is only applicable when the X dimension is being used. X scale is not applicable for Geospatial plot types (‘maps2d’, ‘maps3d’).

Returns:float
y

Y dimension (Spatial dimension). Should be set to str of the feature name to be mapped to Y dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that Y dimension will not be mapped.

Returns:str feature name to map to Y dimension.
y_bins

Y bins setting. Must be a int between 1 and 1000. Y bins is only applicable if the ‘plot_type’ has been set to “HISTOGRAM”. If there are multiple spatial dimensions (X, Y, Z) mapped, there are additional constraints for permissible values.

Returns:int between 1 and 1000
y_normalization

Y normalization setting. Must be set to str and match with one of the Normalization options listed here: {“Softmax”, “Log10”, “IHST”, None}. Y normalization is only applicable when ‘y’ dimension is mapped. Y normalization is not applicable for Geospatial plots.

Returns:str
y_scale

Y scale setting. Must be set to float with value between .5 and 5. Default value ‘None’ leaves VIP to default scaling value. Y scale is only applicable when the Y dimension is being used. Y scale is not applicable for Geospatial plot types (‘maps2d’, ‘maps3d’).

Returns:float
z

Z dimension (Spatial dimension). Should be set to str of the feature name to be mapped to Z dimension in VIP. If a pandas.Series is passed, the name attribute will be used and must match a feature name in the specified dataset in VIP. Default is None which implies that Z dimension will not be mapped.

Returns:str feature name to map to Z dimension.
z_bins

Z bins setting. Must be a int between 1 and 1000. Z bins is only applicable if the ‘plot_type’ has been set to “HISTOGRAM”. If there are multiple spatial dimensions (X, Y, Z) mapped, there are additional constraints for permissible values.

Returns:int between 1 and 1000
z_normalization

Z normalization setting. Must be set to str and match with one of the Normalization options listed here: {“Softmax”, “Log10”, “IHST”, None}. Z normalization is only applicable when ‘z’ dimension is mapped. Z normalization is not applicable for Geospatial plots.

Returns:str
z_scale

Z scale setting. Must be set to float with value between .5 and 5. Default value ‘None’ leaves VIP to default scaling value. Z scale is only applicable when the Z dimension is being used.

Returns:float