This document is a guided walkthrough of the “Predictive Modeling” tutorial App. In this App, we demonstrate how machine learning can be effectively implemented and then enhanced within an App running on the Virtualitics AI Platform (VAIP).

In this tutorial, we use house pricing data to train a model that identifies “flippable” properties. We then use various Elements (such as Plots, Tables, and Infographics) to present the output of the model in ways that provide explainability and insights for informed decision-making.

If you want to review the App in use while also reviewing the code, you can download the code and use the Command Line Interface (CLI) to deploy this App in the VAIP and progress through it as you follow this walkthrough. For more on using the CLI to deploy an App, see this article.

Note: Only a subset of the code used to build the App can be found in this walkthrough; the full script can be downloaded from the bottom of this page.

The data for this walkthrough can be found at the bottom of this page and was sourced from Kaggle.

If this is your first introduction to Virtualitics Apps, also consider the “Hello World!” tutorial App. It is our beginner level tutorial App and primarily focuses on the core aspects of App development.

Constructing the App

When creating App scripts, we recommend organizing your file in the following order:

1. Imports

2. Step Definitions

3. App and Pages Creation

This sequential organization can be seen in the full script for this App provided as a download below.  However, for the purpose of this walkthrough, we will go through each Step and its corresponding Page together.

Imports

Every App begins by importing the key classes, which include Card, Section, Page, and Step. It is also important to import the various Elements to be used.

You will also need to import:

• Element and plot types from the Virtualitics SDK

• Packages required for creating plots, such as Plotly Express

• Packages you’ll use for data processing, such as NumPy and Pandas

# Import Virtualitics AI Application internal elements
from virtualitics_sdk import (
    App, Step, StepType, Card, Page, Section, StoreInterface, Dataset, Model, PlotlyPlot,
    InfographData, Infographic, InfographicOrientation, CustomEvent, Table, XAIDashboard, 
    Column, Row, InfographDataType, Dataset, AssetType, DataEncoding, Explainer
)

# Import external libraries
import pandas as pd
import plotly.express as px
from sklearn.model_selection import train_test_split
from xgboost import XGBRegressor

Importing Data

This App is written to pull a dataset from the VAIP Cloud storage system. In order for it to execute correctly, you'll first need to upload the house_prices.csv file (downloadable below) with the label house_prices through the Asset Uploader.

Important: If you do not label this asset as listed above, the App will not be able to locate the asset.

To add this asset using the Asset Uploader:

1. From the VAIP Home Page, click Assets in the left navigation bar.
2. Click New Asset on the top right of the screen.
3. Fill in the Asset Uploader form, ensuring the label is as listed above.
   
   

Building the App

Once you have the correct data asset uploaded, you're ready to create Steps. Steps are the primary building blocks of a App; they orchestrate all backend and frontend tasks performed on each page. Let's explore this App's Steps and their corresponding Pages:

1. Investment Dashboard

2. Scenario Planning Dashboard

1. Investment Dashboard

In this Step, a model for identifying "flippable" houses is built. Its output is then used, along with contextual information from the dataset, to build a dashboard of insight-rich elements. 

The model is built, trained, and applied in the same way as any of the popular modeling libraries in Python. However, by taking the extra step of rolling up the model of choice into a Virtualitics AI Platform Model, users are able to leverage powerful tools that are specific to the Virtualitics AI Platform, as explored in the following Step.

Notice that the trained model is saved as an Asset, allowing it to be accessed in both the Assets tab and future Steps.

# Build model
store_interface.update_progress (40, "Creating Model")
xgb = Model(
   model=XGBRegressor(
      learning_rate=0.1, 
      n_jobs=-1, 
      n_estimators=100, 
      max_depth=5, 
      eval_metric='mae', 
      random_state=42
   ),
   label="xgb",
   name="house sale price predictor"
)

# Train model and save as asset
xgb.fit(train_data[ohe_features], train_data[target_col])
store_interface.save_asset(xgb)

# Apply trained model to test set
test_target = test_data[target_col]
test_pred = xgb.predict(test_data[ohe_features])
test_results = pd.DataFrame(
    {'ActualPrice':test_target, 'PredictedPrice':test_pred}
)

Throughout the rest of this Step, both an Infographic and series of Plots are created. They are then organized inside of a Card.  A "Recommendation" Infographic is also placed at the bottom of the Page, which gives the user the opportunity to run a Custom Event.

Altogether, this creates the Investment Dashboard.

2. Scenario Planning Dashboard

One of the greatest challenges involved with the use of machine learning is the ability to explain a model’s decisions to end users.

To address this, an Explainable AI (XAI) module can be built, which allows users to interact with their data and find explanations for a model’s behavior.

Before any XAI elements are built, an Explainer from our trained model needs to be created.

# Create explainer for model
explainer = Explainer(
    model=xgb, 
    training_data=explain_dataset, 
    output_names=["SalePrice"], 
    mode='regression',
    label="explainer", 
    name="ensemble model", 
    use_shap=True, 
    use_lime=False
)

store_interface.save_asset(explainer)

Building the XAI Dashboard

After some additional preprocessing steps (which can be found in the full App script), the Model, Explainer, and some additional inputs can be used to build an XAI Dashboard. 

# Create the Explainer Dashboard
store_interface.update_progress(
    70, "Creating Scenario Planning" + "Tool Dashboard"
)

xai_dash = XAIDashboard(
    xgb, 
    explainer, 
    prediction_dataset, 
    "LandContour", 
    "PredictedPrice", 
    "PredictedPrice", 
    title="",
    bounds=bounds, 
    description=XAIDashboard.xai_dashboard_description(), 
    train_data=explain_dataset, 
    expected_title="Avg. Listed Price",
    predicted_title="Predicted Price", 
    encoding=DataEncoding.ONE_HOT,
)
current_page.add_content_to_section(xai_dash, "")

Building an XAI Plot

A user can select any sample on the XAI Dashboard, change its feature values, and then click the “Predict” button. This will produce an explanation infographic that will display the new model prediction along with the likelihood of such a sample existing.

An XAI Plot can also be built, which takes a sample and visualizes how each of its feature values are influencing the model’s prediction.

# More than one sample instance can be used
titles = [
    "This House's Predicted Price is 30% Higher than Its Listed Price"
]
plots = explainer.explain(
    explain_instances[ohe_features], 
    method='manual', 
    titles=titles, 
    expected_title="Avg. Listed Price", 
    predicted_title="Predicted Price", 
    return_as="plots"
)

# Updating Progress and add plots to page
xai_plots_card = Card(
    title="Explanation of a Flippable House",
    content=plots,
)
current_page.add_card_to_section(xai_plots_card, "")

store_interface.update_progress(90, "Updating page")

store_interface.update_page(current_page)

Users can interact with the plot to gain more insight on each feature.

Creating the App Object

Here, the actual App Object is created and an image is assigned to be associated with it on the VAIP Home page.

# Instantiate app and assign image
app_description = (
    "New to writing Virtualitics Apps? "
    + "Check out this Predictive Modeling tutorial app."
)
image_link = "https://predict-tutorials.s3-us-gov-west-1.amazonaws.com/predictive_modeling_tile.jpeg"
predictive_modeling = App(
                      "Predictive Modeling Tutorial", app_description, image_link
)

If set up successfully, this will show the App and the relevant tile image on the VAIP Home page once the App has been uploaded.

Completing an App

The final step in constructing an App involves chaining together each Step in the App Object that was created at the start.

To do this, an ordered list of the Steps is passed to the App's chain() method.

# Chain together the steps of the app
predictive_modeling.chain([executive_dashboard_step, scenario_planning_step])

Deploying an App

After completing this final step, the App file can be deployed to the VAIP using the CLI. For more on using the CLI to deploy this App, see this article.