App Building Guide 1: Hello, World! (VAIP 1.23+) – Virtualitics

This document is a guided walkthrough of the “Hello, World!” tutorial App. It is recommended that you open this App in the Virtualitics AI Platform (VAIP) and progress through it as you follow this walkthrough.

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 downloaded from the bottom of this page.

Before starting this walkthrough, it is important to have some understanding of the class structure and hierarchy within the Virtualitics SDK. Please review our in-depth documentation on familiarizing with App structure and the Virtualitics SDK.

Overall, it is important to keep in mind the following:

Steps orchestrate all of the backend and frontend tasks associated with a Page.
Pages must contain at least one Section and display everything a user will see at the conclusion of a Step.
Sections contain Cards and Elements and can be used to display and separate groups with their own titles and descriptions.
Cards are card-style UI elements and contain one or more Elements.
Elements contain the content that will be displayed to users (e.g. Infographic, Scatterplot).

Constructing the App

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

Imports
Step Definitions
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 Step, Page, Section, and Card. 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 you’ll use for data processing, such as NumPy and Pandas

# Import classes from the Virtualitics SDK
from virtualitics_sdk import (
    App, Step, StepType, Page, Section, Card, CustomEvent, DataSource, Dropdown, NumericRange, 
    DateTimeRange, TextInput, Table, InfographData, InfographDataType, Infographic, Column, Dataset,
    StoreInterface, create_bar_plot, create_line_plot, create_scatter_plot,
)

# Import internal VAIP classes to use Virtualitics Explore in your app
from predict_backend.predict_pyvip.predict_pyvip import PredictpyVIP
from predict_backend.store.websocket_store import websocket_store

# Import external packages
from virtualitics import vip_annotation
import pandas as pd
import collections
import random
import string
from datetime import datetime

Here, you will also create constants for titles that you'll use throughout the App.

DROPDOWN_TITLE = (
    "Dropdown Title: Which stock do you want to do an individual analysis on?"
)
RANGE_TITLE = "Choose : how many company do you want to show?"
DATE_TITLE = "Date Range Title (Optional): Choose a date range for the analysis"
TEXT_INPUT_TITLE = "Text Field: Type a sentence to get a word count analysis!"

Building the App

Steps are the primary building blocks of a App. They orchestrate all backend and frontend tasks performed on each page. We will now go through each of this App's Steps and their corresponding Pages:

Data Upload
Data Query
Data Visualization
Additional Elements
Saving Assets

1. Data Upload

This first Step uses the DataSource Element to provide the user with a means of uploading data. It is added to a Card and then placed into a Section, all of which displays on a Page.

Note: Since there is only one Section on this Page, the Section's title can be left as an empty string.

This Step also includes a specification that the data must be uploaded as a CSV file and provides additional information to help guide the user.

# This step has the user upload the dataset we'll be using
class DataUpload(Step):
    dataset_name = "SP 500 Dataset"

    def run(self, flow_metadata):
        # Get store_interface and then current page and section
        store_interface = StoreInterface(**flow_metadata)
        page = store_interface.get_page()
        section = page.get_section_by_title("")

        # Set section title
        upload_section_title = "Loading Data from Databases, Datastores, and Data Lakes"
        section.title = upload_section_title

        # Create DataUpload Card
        guide_link = "https://docs.virtualitics.com/hc/en-us/articles/24988865488659"
        data_link = "https://docs.virtualitics.com/hc/en-us/articles/34931948678163"

        upload_subtitle1 = (
            f"To learn more about how to load data from databases, datastores,"
            f" and data lakes, check out this link: {guide_link}"
        )
        upload_subtitle2 = (
            f"You can find the relevant data for this tutorial here: {data_link}"
        )
        upload_subtitle = upload_subtitle1 + "\n \n" + upload_subtitle2

        data_upload_card = Card(
            title="Data Source Title (Optional): Upload the stock ticker data!",
            content=[
                DataSource(
                    title="S&P 500 Dataset",
                    options=["csv"],
                    description=upload_subtitle,
                    show_title=False,
               )
            ],
        )

        # Add card to section, set section title and subtitle, and update page
        page.add_card_to_section(data_upload_card, "")

        store_interface.update_page(page)

In the Step definition, a DataUpload Element is added to a Card and then placed in the empty Section that is fetched using StoreInterface.

The Section is also given a title and subtitle within the Step.

Note: This can also be done when first instantiating the Section. Whether the title and subtitle of a Section is assigned in its instantiation or within a Step is a matter of personal preference.

# Build data upload step
data_upload_section = Section("", [])
data_upload_page = Page(
    "Getting Data Into the Platform", [data_upload_section]
)
data_upload_step = DataUpload(
    title="Data Upload",
    description="Upload the S&P 500 data.",
    parent="Inputs",
    type=StepType.INPUT,
    page=data_upload_page,
)

Altogether, this creates a Page which prompts the user to upload specified data in CSV format.

2. Data Query

In this Step, Elements are created to collect user input. Since some of these inputs will be used to query the data uploaded in the previous step, the data needs to be accessed to determine the bounds to be set within the relevant input Elements.

This can be done by using the StoreInterface get_element_value() method and specifying the Page and Element title of the DataUpload Element to return a Pandas DataFrame.

 # Fetch input data and extract query boundaries for stock name and date
data = store_interface.get_element_value(
    data_upload_step.name, "S&P 500 Dataset"
)
stock_names = sorted(data["Name"].unique())
        min_date = datetime.strptime(data["date"].min(), "%Y-%m-%d")
        max_date = datetime.strptime(data["date"].max(), "%Y-%m-%d")

Now, data input Elements, such as a Dropdown selection, can be built using the bounds that have been calculated.

# Create dropdown card
    stock_dropdown = Dropdown(
        options=stock_names,
        title=DROPDOWN_TITLE,
        description="Description for dropdown",
        label="Stock Ticker",
        placeholder="Select One",
    )
    stock_dropdown_card = Card("Dropdown", [stock_dropdown], show_title=False)

This creates a Dropdown selection, which prompts the user to choose their next course of action.

As this Step contains some data processing, the StoreInterface method update_progress() is used to keep the user updated on the progression of the Step as it runs.

# This step updates the user on the progress of the step as it processes
# The first parameter designates the percent to which the progress bar is filled
# The second parameter designates the message that is displayed with the progress bar
store_interface.update_progress(5, "Creating query selection options")

The percent completion and message used will be displayed at the bottom of the Page in real time.

3. Visualize Data

In this Step, the query parameters previously input by the user are retrieved by, again, using the StoreInterface get_element_value() method.

# Fetch query parameters from previous step
    stock_analyzing = store_interface.get_element_value(
        data_query_step.name, DROPDOWN_TITLE
    )

The data can then be queried according to the user-specified parameters and used to create visualizations such as a ScatterPlot.

# Create scatter plot
scatter_plot = create_scatter_plot(
   data[data.ticker == stock_analyzing],
   "volume",
   "pct_change",
   color_by="change_type",
   plot_title=f"Scatter Plot: {stock_analyzing} Volume vs % Change in Daily Price"
)

Additionally, plots can be given more specific layouts. Cards are great for displaying Elements in a row-wise and column-wise manner. They also enable relative ratios to be set to determine Element sizes.

 # Add the plots to a card
plots_card = Card(
    title="Plots", 
    content=[Row([Column([scatter_plot], ratio=[0.7])]),
             Row([Column([line_plot], ratio=[0.7])]),
             Row([Column([bar_plot], ratio=[0.7])]),
             ]
)

4. Additional Elements

In this next Step, which can be viewed in detail in the downloadable script, two more robust capabilities in the VAIP are explored: Infographics and the ability to create powerful, multi-dimensional visualizations.

Infographics are an excellent Element for displaying KPIs, progress statuses, and other summarizing information.

Apps also have the ability to connect with Virtualitics' AI-powered data visualization and exploration tool - Virtualitics Explore. This allows users to render extremely useful and robust visualizations and then display them in a Page within an App. It also enables users to open an active App's data in a project with which the user can immediately interact. This is accomplished using a CustomEvent.

5. Saving Assets

Assets, such as Datasets and Models, can be saved in a user’s VAIP workspace to either be downloaded or accessed later on.

Saving an Asset is as simple as using the StoreInterface save_asset() method and specifying the Asset to be saved, including a label and name.

# Retrieve preprocessed Dataset from previous step and save as an asset
data = store_interface.get_input("Preprocessed Data")
dataset_asset = Dataset(
    dataset=data, label=DataUpload.dataset_name, name=DataUpload.dataset_name
)
store_interface.save_asset(dataset_asset)

Assets can be found by clicking the Assets tab in the left-side navigation bar in the VAIP.

Creating the App Object

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

# Instantiate Flow and assign image
flow_image_link = (
    "https://predict-tutorials.s3-us-gov-west-1.amazonaws.com/hello_world_tile.jpeg"
)
hello_world = Flow(
    "Hello, World!", 
    "A basic introduction to the design and function of Flows.", 
    flow_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 a App

The final step in constructing a 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 steps of flow
hello_world.chain(
    [
        data_upload_step,
        data_query_step,
        data_visualization_step,
        additional_elements_step,
        save_assets_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.

File Downloads

sp500_dataset.zip
10 MB Download
hello_world.py
20 KB Download

App Coding Tutorials