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

Only a subset of the code used to build the Flow can be found in this walkthrough. The full script can be found here.

The data for this walkthrough can be downloaded here: sp500_dataset.csv 

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 Flow development and the Virtualitics SDK.

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

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

Constructing the Flow

When creating flow scrips, we recommend organizing your file in the following order:

1. Imports
2. Step Definitions
3. Flow and Pages Creation

This sequential organization can be seen in the full script for this flow provided in the section above. However, for the purpose of this walkthrough, we will go through each step and its corresponding page together as it will make for easier reading.

Imports

We begin every flow by importing our key classes, which include Card, Section, Page, and Step. We also import the various Elements we’ll be using.

# Import key flow classes
from predict_backend.flow.flow import Flow
from predict_backend.flow.step import Step, StepType
from predict_backend.page import Page, PageType, Section, Card
from predict_backend.store.store_interface import StoreInterface

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

Create Flow Object

Here, we create our actual Flow object and can also assign an image to be associated with it on the Virtualitics AI Platform homepage. See this article for more guidance on setting Flow tile images.

# 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)

Our Flow can be seen here on the Virtualitics AI Platform home page.

Build Steps and Pages

Steps are the primary building blocks of a flow. They orchestrate all backend and frontend tasks performed on each page. We will now go through each of this Flow’s steps and their corresponding pages:

1. Data Upload
2. Data Query
3. Data Visualization
4. Additional Elements
5. Saving Assets

1. Data Upload

Here, we start by creating an empty Section that we then place into a Page with the title "Getting Data Into the Platform." We then instantiate our DataUpload Step, which we defined above, and apply it to the Page.

# Build data upload step
data_upload_section = Section("", [])
data_upload_page = Page("Getting Data Into the Platform", PageType.INPUT, {}, [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
)

In our Step definition, we add a DataUpload Element to a Card and then place it in the empty Section we fetch using StoreInterface. We also give the Section a title and subtitle within the Step, even though we could’ve also done so when first instantiating the Section. Whether you assign the title and subtitle of a Section in its instantiation or within a Step is a matter of personal preference.

# This step has the user upload the dataset we'll be using
class DataUpload(Step):
    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/self-service-flow-code-examples/configure-a-connection"
        data_link = "https://docs.virtualitics.com/en_US/create-a-new-flow/hello-world"
        upload_subtitle1 = f"To learn more about how to load data from databases, datastores, 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)

Altogether, this creates the following page, which prompts the user to upload specified S&P 500 data in CSV format:

2. Data Query

Once again, we start by creating a Section and Page and then instantiate our defined Step.

In our Step, we create Elements to collect user input. Since some of these inputs will be used to query the data uploaded in the previous step, we’ll want to access that data to determine the bounds to be set within the relevant input Elements. We can do this 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())

We can then build data input Elements, such as a Dropdown selection, using the bounds we’ve just calculated.

# Create dropdown card
stock_dropdown_title = "Dropdown Title (Optional): Which stock do you want to do an individual analysis on?"
stock_dropdown = Dropdown(
   options=stock_names, 
   title=stock_dropdown_title,
   description="Description for dropdown (Optional)"
)

As this Step contains some data processing, we also use the StoreInterface method “update_progress()” to keep the user posted on the progression of the Step as it runs. The percent completion and message used will be displayed at the bottom of the Page in real time as seen here:

# This step updates the user on the progress of the step as it processes
store_interface.update_progress(5, "Creating query selection options")

3. Visualize Data

In this Step we retrieve the query parameters input by the user in the previous one by, again, using the StoreInterface get_element_value() method.

# Fetch query parameters from previous step
stock_dropdown_title = "Dropdown Title (Optional): Which stock do you want to do an individual analysis on?"
stock_analyzing = store_interface.get_element_value(data_query_step.name, stock_dropdown_title)

Our 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, we can place plots in a Dashboard. Dashboards are great for displaying Elements in a row-wise and column-wise manner. 

# Create a dashboard and add our plot elements to it
plots_dashboard = Dashboard([Column([scatter_plot, line_plot, bar_plot])])
# Add the dashboard to card
plots_card = Card("Plots", [plots_dashboard])

4. Additional Elements

In this next Step we demonstrate two more robust capabilities in the Virtualitics AI Platform: Infographics and the ability to create powerful, multi-dimensional visualizations. 

Infographics are an excellent Element for displaying KPIs, progress statuses, and other summarizing information. A related article on creating the Infographic in this flow can be found here.

The Virtualitics AI Platform also has the ability to connect with Virtualitics' AI-powered data visualization and exploration tool. This allows us to render extremely useful and robust visualizations and then display them in a Page within a Flow. It also enables us to open an active Flow’s data in a project with which the user can immediately interact. This is what we do in this Step and it’s accomplished using a CustomEvent. See this article for detailed information on creating custom events.

5. Saving Assets

Assets such as Datasets and Models can be saved in a user’s Virtualitics AI Platform 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 you want to save, as well as a label and name for it.

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

Assets can be found under “Assets” in the Virtualitics AI Platform sidebar.

Completing a Flow

The final step in constructing a flow involves chaining together each Step in the Flow object we created at the start. To do this, we pass an ordered list of our Steps to the Flow’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
])

After completing this final step, your Flow file can be uploaded to the Virtualitics AI Platform using the “Create Flow” button in the top right of the home page of your workspace:

You’ll be alerted if any errors are detected in your Flow. If no errors are detected, your Flow will appear on the home page of your workspace!