Guides & Tutorials

The Flow Team's Guide to Building a Flow

  • Bill's Quick Guide

    A Process for Developing a Step within a Flow

    Developing an entire Flow can be quite a textured process, as often you cannot foresee how the development of the data story needs to proceed until you have observed the data from various Perspectives.  In this guide, rather than providing a process for developing an entire Flow, we provide a process for developing a few Steps that would typically comprise a portion of a Flow.

    Based on the user's preference and experience, the exact sequence of activities in developing a Flow may vary from Step to Step.  The development methodology provided below should provide an effective process for new users. 


    1.  Sketch the information that you wish to present within the Step

    Sometimes a mental sketch will do, and sometimes it will be worth sketching the desired content of the Step on paper or in a drawing tool.  It is important that you make sure that the CSV File for the Step contains the data fields that will provide the values for the Dots, the Chart axes, and the data filters that appear within the Perspective(s) that are needed within the Step.

    Note: If the Charts that you wish to show require the use of non-default uses of color or special ways of connecting the Dots, you may also need to drive these items using data contained in the CSV File(s).  You usually do not need to worry about these factors when you are developing the first draft of the Step, as it is relatively easy to retrofit information into the CSV File as you tune the visual performance of the Flow.


    2.  Generate the CSV File that will be used for populating the data Swarm

    You need to make sure that the CSV File contains the appropriate data required to generate the Charts to be displayed, including the data values, the axis parameters, appropriate filter fields, etc.

    Note 1: Multiple Swarms (Charts) can be displayed within a Step. It is perfectly ok for a Swarm to be a copy of another Swarm.

    Note 2: Usually a Swarm provides data for multiple Steps.  Sometimes an entire Flow is driven by data contained within a single Swarm, with a separate Perspective for each Step.  Filters are often used so that a single Swarm can be conveniently used on multiple Steps.

    Note 3: If after constructing some Steps using a Swarm, you find that you are missing some data elements required for the next Step, don't despair, because you can either:

    1. Add the newly required data to the existing CSV File, and then reload the data into the Swarm
    2. Create a new Swarm that contains the newly required data

    Option 1 above is usually the preferred approach because this option minimizes the number of CSV files that need to be maintained.

    When reloading a CSV file, it is important that no changes be made to the column titles that are already referenced within the Flow for axis labels, filter fields, etc.  It is fine to change the data within columns, but if you change the column titles, you will need to go through each possible reference to those columns throughout the Swarms and Steps.

    A small segment of the Excel sheet that contains data for the "Humanity" Featured Flow is shown below.


    Screenshot 1 - Example spreadsheet representation of a CSV file

    In this example columns B, C, F contain data to populate a Swarm that shows life expectancy by country by year.  The other columns are used to facilitate filtering and to provide control of some desired colorization and some specialized connections. In this example file, connections (col H), labels (col I) and the color of line charts (col N) are contained within the CSV file.  In most cases, you will not need to provide connections, labels, and colorization in the CSV file, but if you want to do something very customized, the capabilities for specifying these items from the CSV file are provided. 


    3.  Log into your Flow Editor session

    You can now return to the Flow Editor Home Page on which you previously registered to use the Flow Editor.

    Log in, and you will see a screen that looks like the screen shown below.


    Screenshot 2 - New user view when first logging in to use the Flow Editor

    Don't worry about the message shown in the screenshot.  The Flow Editor is just trying to tell you that you currently have no Flows.

    If you have already created some Flows, your view after logging in will include thumbnail representations of the Flows in your account.


    Screenshot 3 - User view for a user who has already created some Flows


    4.  Create your Flow

    Click the Create Flow button.


    Screenshot 4 - Screen after user clicks "Create Flow" button

    The Flow Editor creates a Flow with a default name of "New Flow yyyy-mm-dd", auto-creates Swarm 1, and shows in red that the next thing you should do is to define the "Data source" for Swarm 1.

    You can now either click the "Upload" button and navigate to the CSV file that will be used to populate Swarm 1, or you can click the "From Library" button that will enable you to use a CSV file provided by Flow for demo or training purposes.

    For populating Swarm 1, we are going to use the library "Global Life Expectancy" CSV file, so please click the "From Library" button.


    Screenshot 5 - Dialog showing choice of Flow library of demo and training CSV files

    Click the "Select" button for the Global Life Expectancy CSV file.


    Screenshot 6 - View after using the Flow library to populate Swarm 1

    The "Dots" that comprise the Humanity Flow are shown in a "Random" Chart type.

    This random content first Step is sometimes retained in the Flow, as it supports the concept that the interpretation of real-world data requires a great tool in order to adequately convey important information derived from the data.  In this exercise, we will retain this Step.

    At this point, please do a quick scan of the information in the right-hand "Swarm" panel, as doing so will provide you with some insight into the type of information that needs to be defined for each Swarm.


    Screenshot 7 - Swarm pane immediately after populating the Swarm with CSV data

    Some things to notice are (1) The name of the Flow, (2) the "dot size" or 0.005 meters, and (3) the color of the dots.  Note: All sizes and dimensions in Flow are expressed in "meters".  Using meters is not very relevant in a flat-screen environment, but in augmented reality and virtual reality the size is experienced as a fixed thing.  

    You should rename your Flow to something more meaningful than "New Flow".  In our example, the user places the cursor into the text box containing the Flow name, and changes the name to "Humanity v1.0".  It is a Flow best practice to always provide a version number within the name of the Flow.


    Screenshot 8 - Change of name of the Flow


    5.  The "3 Dots" (More) button

    At this point, let's take a quick look at the content that is displayed when you click the "3 Dots" button.


    Screenshot 9 - Functionality available via the "Other" button

    In this Quick Guide, we will not cover most of the items accessed via the "More" button, but you should know that at any time you can "Save" your Flow by clicking the "Save" button or you can create a copy of the Flow by clicking the "Save As" button.

    By default, Flow automatically saves a copy of your Flow every 30-60 seconds.  If you want to explicitly control when Save operations happen, you can uncheck the "autosave" button on the box, and then it will be entirely up to you regarding when your Flow is saved.  Please note that if you uncheck the Autosave option, then if you exit Flow without first saving the flow, all the work you have done since the last Save will be lost.

    By default, the "Advanced (beta)" box is unchecked.  After you become more familiar with the interface, Flow users who are actively designing Flows prefer to check this button.

    You can explore this menu and the "Settings" dialog when you have some time.


    6.  The Objects Timeline

    The main "dashboard device" is now the Objects Timeline, an example of which is shown earlier in Screenshot 7, and which is repeated here for convenience.


    Screenshot 10 - Objects Timeline

    The Objects Timeline provides a highly visual environment in which the Flow designer can create, update and control the visibility of the various data objects (Swarms, Connections, Area Charts, Labels, Text Items, Images, Buttonz) that are contained within a Flow.

    Screenshot 17 shows the Editor screen for an Example Flow that consists of 11 Steps.  

    The functionality of the Objects Timeline is described below:

    1. Each step is represented in the Objects Timeline.  The Steps are numbered sequentially.

    2. Each data object is represented in a way that visually indicates the type of object and the steps on which the object is visible.  Every data object can be made visible or invisible on every step, and whether the object is visible on a particular step is controlled by the cells within the Objects Timeline.  The name of the object is shown to the left of the timeline cells, and each object type is represented by an associated color:

    Swarms - yellow
    Connections - light orange
    Labels (also known as Structures) - medium orange
    Area Charts - Darker orange
    Maps - Brighter orange
    Text objects - Bright blue

    3. Each data object is shown within its grouping in the order in which the data object has been created.

    3.1 Each Swarm is a major object represented within the timeline.  Swarms are used to populate charts or maps (or both).

    3.2 Indented under each Swarm are the Connections, Labels (Structures) and Area Charts that have been created for the Swarm.

    3.3 Other data objects, such as Text Objects, images, etc. are also represented within the Objects Timeline.

    4. The specifications for each data object can be accessed by single clicking the Objects Timeline cell that corresponds to the Step and the data object.  Each time you click a cell within the Objects Timeline the specification panel for that object and Step is displayed on the right-hand side of the screen.  Thus, the matrix of cells within the Objects Timeline is your key for navigating the steps and data objects that comprise your Flow.

    5. To remove the visibility of a data object from a Step, double click the cell that indicates the visibility of the data object within the Step.  Double click the cell again to return the object to being visible on the step.

    6. Adjacent to the Objects Timeline are buttons for creating new steps and for managing existing steps.

    7. To create a new Step

    7.1 Click the Add New Step button

    7.2 You will be prompted to indicate if you want to create a blank new step, or if you want the newly created step to be a cloned copy of the step on which you are currently positioned.

    7.3 To manage steps

    You can display a panel containing the list of steps by clicking the Steps Details button.


    Screenshot 11 - View of Steps Details for a Flow that contains several Steps.

    Please note the "x" located next to the Step name in the Steps Details panel.  Clicking the "x" is how you delete a Step.  As Steps are added to the Flow, an additional screen icon is inserted for each Step.  The small icon at the upper left of the Step icon can be used to drag and drop a Step to a new position within the Flow.


    7.  Continuing the generation of the Humanity Flow

    We will now continue to construct our training Flow.


    Screenshot 12 - Display of data that has been uploaded into the Global Life Expectancy data source

    To view the data that has been uploaded into Swarm 1, please click the Reupload button.

    Note: It's a little confusing that the Choose File button is still active.  The reason it is still active is because at this point, if you have rights to upload your own CSV files, you could replace the data source with another CSV File if you so desired.  For our training exercise, we are happy to use the CSV File from the Flow Library.

    Please feel free to use the horizontal and vertical scroll bars to explore the data.  The Global Life Expectancy dataset from the Flow Library contains 6660 rows and each row contains 14 columns of data.

    Please note that the first row contains titles for columns that are used in specifying the content of axes in charts, filter criteria, and other items used in defining various parameters for the Flow.  A "best practice" is to keep the column titles fairly short, but appropriately descriptive of the data within the column.

    Click the Close button to close the viewing window.


    Some additional notes regarding the CSV file used to populate the Data Source.

    In this case we used a CSV File that was already available within the Flow Library.  When you are using your own CSV File, please make sure that the CSV File contains data that is appropriately structured and sorted.

    Rows of data that for which the value of the "Dot" field is blank, should be omitted from the CSV File that populates the Swarm.  This is especially true for Charts in which the Dots are to be connected with straight lines.

    Similarly, data fields that will be used for axes in the 3-D space (for example Year, Country, etc.) should not be blank.


    8.  Create the next Step

    Click the Add Step button, and then click "Duplicate".  When it is time to create additional Steps, you will always have the choice of creating a blank Step or duplicating the prior Step as the starting point for the next Step.  In this case, it makes most sense to duplicate the next step, because the same Swarm used in Step 1 will be used in
    Step 2.

    When you create a new Step, you are automatically advanced to the new Step.  You will now also see that Step 2 has been appended to the Objects Timeline.

    9.  Specify the behavior for the newly created Step

    The Chart Type for displaying the desired Chart is "Scatterplot", so select this Chart Type.  Scatterplots are a very frequently used Chart type.  In Scatterplots you can arrange the data in up the three axes, and the values along the various axes are provided by specific columns within the CSV File associated with the Swarm.

    In the Scatterplot you can associate the axes with any columns within your CSV File, and for our purposes we are going to set the axes as follows:

    Horizontal axis = time series by Year

    Vertical axis = value of Life Expectancy

    Depth axis = Country


    Screenshot 13 - Swarm view immediately after specifying horizontal, vertical and depth axis parameters

    The changes that have been made from the prior Swarm definition to the current Swarm definition are:

    1. The user changed the type of Chart from "Random" to "Scatterplot".  In response to this, Flow automatically created a new perspective.

    2. The user specified the width, height and depth axes.  In specifying the width axis, the user indicated that the axis is a "timeline", and the time elements are expressed as "Year".

    3. The user specified the Dot size as 0.01.

    Use your mouse to rotate the camera view and to zoom in or out in the 3-D space.  When you reach a view that you wish to have as the starting point when you next access this Step, click the "Set Camera" button in the upper left of the screen.

    Now we need to establish a Connection to appropriately connect the Dots within the line Chart.

    Click the New Connections button.  A new Connection is created with the name "Connections 1: Swarm 1".

    The Swarm is set to Swarm 1, and the Connection Type is auto-set to "category".

    Now set Column to "Country".  This indicates that you want to connect the Dots within the lines for each "Country".  The many lines will look very busy, but if you alter the view of the 3-D space so you are looking down on each Country line, you will see that there are individual connected lines for each Country.

    At this point your screen should look similar to the following screen shot.


    Screenshot 14 - View after connecting the dots by Country using Connection 1

    If the connection does not show up within the Objects Timeline, please double click the Connection 1 cell for
    Step 2.

    Next, let's return to the Swarm view pane that displays information about Swarm 1.  To do this, in the Objects Timeline, click the cell corresponding to Swarm 1 in Step 2.

    Next, if you wish to modify the Dot sizes, please go ahead and do so.

    Now let's also place a default color scheme into the Chart so that each country can be more easily seen.

    Reset the Color dropdown to "Color Scheme" and set the Column to "Country".  Note: If you prefer to set the color by "Continent", please go ahead and make that selection, and you will see the colors change accordingly.  For this exercise we are going to use colorization by Country.

    At this point your screen should look similar to the following screen shot. 


    Screenshot 14 - View after setting color parameters

    If you would like this exact view to be the default view when you access this Step, click the Set Camera button in the upper left-hand portion of the screen.  If you rotate the 3-D space, and then toggle back and forth between Step 1 and Step 2, you will see that the last camera setting has become the default view for Step 2.

    Next, we are going to set the data values that will be popped up when the user clicks on a Dot while viewing the Flow.

    Click the "On select popup" section, and then choose "Overlay" and then click Edit.

    Then in the resulting dialog, select Year, Country and Life Expectancy.   Also, select "Upper right" for the Position at which the information will be displayed.

    By doing this you have indicated that when the user clicks on a dot, the Year, Country and Life Expectancy will be shown in the upper right area of the screen.


    Screenshot 15 - Specification of "On Select Overlay"

    Click the X in the upper right-hand corner of the On Select Overlay dialog to dismiss the dialog box.

    At this point, after a few seconds you will be able to click on a specific Dot, and the information corresponding to the Dot will be displayed in the upper-right of your screen.


    Screenshot 16 - Display of information corresponding to a clicked Dot

    We could specify similar settings for the "On Rollover popup" section, but we will not do this right now.

    Explore some of the outlier data points, especially the points in time where the Life Expectancy suddenly decreased.  Exploring these data points will shown you that sharp declines in Life Expectancy occurred in many countries around 1918 (Spanish Flu pandemic), in many countries during the early 1940's (World War II), in Haiti in 2010 (massive earthquake), and at various other times and places during the 200-year time period shown in the Chart.


    10.  Construct the final Step

    Exploring the outlier data has given us some ideas, so next we will explore in more detail the years around 1918, so we can see how the Spanish Flu Pandemic affected the life expectancy in countries located in Europe.

    To do this exploration, we want to create an additional Step, and we want to use Filters to display just the data subset that is of interest.  The additional Step will be a modification of Step 2.

    Click the Add Step button, and then click Duplicate so that Step 3 will initially be a copy of Step 2.

    You will be auto-positioned into Step 3.

    Now click the Filter section and then click "Create new filter". 


    Screenshot 17 - Initial Filter dialog

    Because we are going to examine the years from 1916 through 1921, set the column of the first filter to Year and set the selection criterion to "between 1915 and 1922".  You can type directly into the Year value boxes when setting the range of Years.  After you set the first filter, you will see an immediate reaction in the view, as data for Years up through 1915 and Years after 1921 will disappear from view.

    In order to eliminate blank space along the horizontal axis, please also change the settings of the "width range min and max" to 1915 and 1922.


    Screenshot 18 - Filtering to show just years between 1915 and 1922

    Because we need a compound filter to accomplish our filtering objective (years and Europe), and because we want to "AND" the multiple selection criteria, change the filter logic from "or" to "and".

    Then click Create New Filter, specify the column as "_Continent", and specify the selection criterion as "is equal to 4".  The column "_Continent" in the CSV File contains a numeric code for each Continent, and the numeric code for Europe is "4".

    At this point your screen should look similar to the following screen shot.


    Screenshot 19 - Additional filtering to show just European countries.

    If you are happy with this default view, click the Set Camera button.


    11.  Add appropriate Text boxes

    We will now add some Text boxes to provide titles for each Step within the Flow.

    For Step 3, let's add some title text "Life Expectancy Variation in Europe due to the Spanish Flu Pandemic".

    Click the Text button in the left-hand pane, and then click Create New. 

    A text box containing text "New Text 1" is displayed in the 3-D space.   The content of the Text object should be entered into the "Text *" area in the Text object specification pane.  You can also set the font size.  You can use the arrows around the Text object in the 3-D space to position the text to the desired position.

    Enter the desired text into the Text area, and enable the "Wrap Text", "Face Camera" and "Animate between Steps" options.

    Modify the Font Size if appropriate.

    Use the Position controls to appropriately position the text box within the 3-D space.  If you want the text to stay stationary when you spin the view using your mouse, set the "Close/Far" setting so that is very close to a value of zero.

    Position the view to your desired default position and click Set Camera.


    Screenshot 20 - Addition of Text object into Step 3

    At this point, your screen should look similar to the screen shot shown above.  This screen shot looks remarkably like the screen shot shown in the first section of this document!

    Next, place some appropriate title text in Steps 1 and 2.

    Then position your flow at Step 1 and run through the Flow to make sure everything is working correctly.


    12.  Touchup

    There are numerous ways in which you can enhance your Flow, and you will discover these with experience.

    One easy thing you can do is to add a thumbnail representation of your Flow that will enable you do identify each of your Flows at a glance.  To add a thumbnail of this Flow, locate on the Step that you want to use in the thumbnail.

    Then click the "Other" button, and click Thumbnail, and then click "Take snapshot".

    From this point onward that image will serve as the thumbnail identifier for your Flow.


    13.  Congratulations and feel free to provide feedback.

    Congratulations on completing the development of your Flow!

    Please feel free to provide any feedback regarding this document and also let us know other documentation and videos that you would like to view. Please send your commentary to

    Thank you!

  • Sierra's video walkthroughs can be found on our YouTube channel.

  • Want to learn how to build a Flow in XR? Check out Michael's video.