Vol 3: GETTING STARTED WITH CUBE AND BUILDING YOUR MODEL FROM SCRATCH

When approaching a new software, and specifically our Cube software for Land Use and Transportation Modeling, we want to be sure that we are undertaking the correct steps to get started and are able to use the software properly.  We generally have the following questions:

  1. How do I obtain a license, where do I download the software and how do I install it correctly?
  2. What does the interface look like and where do I open the different windows that I need?
  3. Where can I find help in using the software? (e.g. training courses, demonstration models and useful examples and tips?)
  4. What is the input data that I need, and what about its format?
  5. How do I build a model from scratch and what are the main components of my model?

This article will guide you through the answers to the above 5 questions and take you to the point of being able to start building your own models.

 

HERE’S HOW:

1. SOFTWARE INSTALLATION

First of all, a valid license is necessary. This could be a temporary/testing license for evaluation purposes, or a purchased license. Both of these types of licenses can be requested from our sales team via the form found at: http://www.citilabs.com/contact/. Please feel free to ask any question as Citilabs is committed to helping you find the most suitable solution to your needs.  An overview of the licensing system for our software is available in the document here.

Once you have obtained the license you need, you can download the software from our download page at: http://www.citilabs.com/support/downloads/. Detailed instructions of how to install the software are available here.

 

2. OPENING CUBE AND CUBE INTERFACE

Double click on the Cube icon in our desktop to open Cube.

image001

Once you open Cube for the first time, and after a successful installation and activation of the license, the Cube Welcome Window will appear as below:

image003

 

Clicking on “Download Cubetown” allows you to reach the web-page: http://www.citilabs.com/support/learning-center/ for downloading the “Cubetown” demonstration model.  Once the Cubetown demonstration model is downloaded, run as administrator the cubetown610setup.exe installer.  This will install the demonstration model within the C: drive (or where specified by the user) as below:

image004

 

To open the Cubetown demonstration model, it is necessary to double click on the “Discover Cube.Cat” file, within the Cubetown folder, or to click on "Discover Cube Catalog" in the Welcome Window when re-opening it.

The Cube Voyager Demo Model is a 25-zone “4-step” Voyager passenger demand forecasting model with feedback to trip distribution. The following applications are also available within the same catalog:

  • Cube Land Demo application
  • Cube Analyst Demo application
  • Cube Cargo Demo application
  • Cube Avenue Demo application

Cube Base is the user interface for the entire Cube system and provides interactive data input and analysis, GIS functionality through the ArcGIS engine, model building and documentation, and scenario development and comparison. Links between the model, the data, and GIS are a single click away, making the development and application of models easy to use.

 

cubebase

Scenario Manager provides a very clear way to manage different scenarios, without the need for folders and file locations in the computer.

Application Manager uses a flow-chart system for designing, coding, documenting and running the model. Input and output data is shown in the context of the model and can be immediately viewed or edited by double-clicking on them. Application Manager makes it easy to present a model in a clear way to others.

Cube GIS: Cube includes GIS features that are native to Cube. Cube is a GIS system in its own right and is compatible with the world’s most widely used standard GIS system, ESRI’s ArcGIS.

 

 

3. HELP IN USING THE SOFTWARE

The best way to get quickly up to speed with Cube is to undertake one of our training courses. We run training courses online or onsite, and these can be “standard” courses, or courses customized to your specific needs/data or projects. Please find more details at: http://www.citilabs.com/citilabs_blog/expert-together-training-support-services/ or visit our events page at: http://www.citilabs.com/events/ for currently available courses.

Several “help-channels” are available for current users or users that are evaluating the software.  They are directly available by clicking on the question mark (top right corner) of the Cube window:

image006

 

If you have any issue in using the software or need technical assistance, you can also write to our support e-mail channels: EU_Support@citilabs.com for European users, and GeneralSupport@citilabs.com for any other country.

An open forum for smart users is also available at: http://community.citilabs.com/ with a FAQ session by Citilabs and several “How-To” tips.

image007

 

 

4. INPUT DATA AND FORMAT

Zonal data, record data, matrices and networks with different formats can be processed in Cube (text files, DBF files, ESRI shape files, geodatabase tables and datasets).

Cube exploits the availability of a complete transportation GIS based on ESRI’s leading technology dealing directly with geodatabases and shape files. Conversion from and to these formats is direct in Cube Voyager, and common practice is to use geodatabases (file - GDB, personal - MDB) for storing data and directly reading and writing to and from them in the modelling steps.

Cube also has its proprietary binary formats for the main “ingredients” of the model, allowing reduced disk storage requirements, and storing large data in light files for faster processing of input/output.

 

 

5. BUILDING MY MODEL STEP-BY-STEP

We can identify 8 main steps that we can follow to build our model in Cube from scratch. They are explained below:

1st step: Create the Folder Structure

The preliminary step when building your model is to create a folder to store all your model files.  This folder is called the “catalog folder” (e.g. “TrainingModel_Structure”).  We refer to a Cube model as a “catalog”, as you will understand when learning about the catalog file in step 2.

Inside the catalog folder, you should create the folder structure for your model, defining some subfolders storing specific files. The folder structure is completely up to the model developer. An example is provided below, with the sub-folders:

  • image008Apps: to store the applications files and the files automatically named from Cube when building the model applications in Application Manager
  • Input: to store all the user provided input files
  • Media: to store banner images or other files useful to customize your model and visualizations
  • Output: to store all or selected output files (e.g. to store an output GDB to contain the different scenario specific output networks)

 

It is important that all of the files used inside your model are stored in the catalog folder (within the specific sub-folder).  This way, every time you copy the entire TrainingModel_Structure folder, all of the links in your catalog will be automatically updated and your model will work properly.

Therefore, start with locating your input files within your Input folder (input network, input matrix, etc.) and locate your "media" files within the Media folder (banner, images, etc.).

 

2nd step: Create a New Catalog

The Catalog File (.cat) is the only file in which you must remember its name and location. The Catalog File is indeed the ‘root’ of a model, and everything else is linked to it.

The Catalog tracks the major components of your model:

  • Applications (Model Processes)
  • Catalog Keys (User Input Data to be Scenario Specific)
  • Scenario Data (Unique Sets of Scenario Specific Catalog Keys)

To create a new catalog:

  • Choose File > New > Catalog

image009

 

  • Save the new Catalog within your main catalog folder with a name that represents your model (e.g. \TrainingModel_Structure\Training_Model.cat)

image010

The Scenario Manager opens for the new Catalog along the left-side of the window.  In addition, a “Base” folder is created inside your catalog folder representing the scenario specific directory ({Scenario_Dir}).  Please note that the name of the “Base” scenario can be modified through the Scenario Manager, by right clicking on the scenario name (do not directly modify the name of the folder in Windows Explorer).

 

3rd step: Create a New Application

Applications are the Model Processes saved in a file with extension .app.  A single Catalog may have many Applications (e.g. Passenger Forecasting, Freight Forecasting, Land-Use Forecasting, Sub-Area Analysis, Impact Studies, etc.).

The Application file is a single page that tracks data flows and organizes modeling functions. These functions may be either from Cube Libraries or User Defined.

To create a new application:

  • Select File > New > Application

image011

 

  • An “Application Information” window will open, where you should:
    • Enter the Application Name (e.g. Training Model)
    • Enter the Application Code which is used for File Naming (e.g. TM)
    • Select the Application Type (Voyager)
    • Optionally, enter a Description for the Application, browse to the Background File (e.g. Banner.bmp), etc.

image012

 

  • Click OK and save the .app file in a suitable location (e.g. \TrainingModel_Structure\Apps\ TrainingModel00.app)

In order for the Catalog to track the Application, it must be added to the Application Window, therefore:

  • Right-click in the App Window
  • Select “Add Application” choosing the .app file to include
  • Save All and select “Scenario > Refresh” to display the Application Name in the App Window

image013

 

4th step: Design the Flow-Chart of your Model with Sub-Applications

Applications may be nested to provide the model flow-chart structure using sub-groups.  Sub-groups are Application files nested in the “Parent” Application (at the upper level), and they may contain other sub-groups.

Input and output files can be made public to make them visible and available at the “parent level”:

  • In order to directly link files from the output side of one program processing step to the input side of another, they must be present on the same level
  • For readability, it is best to have all files which are ‘external’ to the sub-group (overall input and outputs of the group) to be exposed to the parent application

image014

It is suggested to properly include sub-groups within your parent applications, splitting the model in different steps depending on the specific task undertaken by the sub-groups. This allows you to:

  • Have a tidier visualization of the process
  • Be able to run sub-groups independently, without the need for running the entire model
  • Reduce the number of programs within the same applications (e.g. Cube Voyager programs), but organizing them in sub-groups

To add sub-groups in your flow chart process:

  • From the Home Tab, click: “Add” > “New Sub-Group…”

image015

  • Create the sub-groups that you need for your model. For example: Network Processing (NP), Matrix Processing (MP), Demand Modelling (DM), HW Modelling (HM), PT Modelling (PM)

image016

 

To enter a sub-group, just double click on it, or click to the sub-application name in the App Window. To go back to parent, you can right click and select “Go to Parent”, use the “Go to Parent” button in the ribbon, or press F9 as a short cut.

 

5th step: Use Catalog Keys for Scenario Specific Inputs

Catalog Keys are the inputs to the model that are unique for each scenario and are tracked by the scenario manager. The Catalog Keys may be numeric variables, file names, or text strings.

The model applier and model developer modes can be set for the catalog (setting through Files > Options). The Catalog Keys are available to the model applier to be accessed and changed through the Scenario Panel (image below – can be opened by double clicking on the specific scenario in the Scenario Manager window). These keys can be reserved to the developer if the intention is to have their values scenario specific but not accessible to the model applier. The model developer defines both keys and the user menu (Scenario Panel).

image017

 

Catalog Keys can then be used within the script of the Cube programs or within the definition of the inputs/outputs (e.g. an input network for a Cube Voyager program can be linked to the specific catalog key). They can be identified in the process by the usage of curly brackets {Catalog_key_name}.

To create a new catalog key (e.g. to store your input roadway network):

  • Right-click in the Keys window and select “Add”

image018

 

  • Within the Edit Key window, enter a Name for the Key (e.g. InputNetwork), a Prompt (e.g. Select the InputNetwork File), select the Type (e.g. File Name), select the Control (e.g. Edit Box)
  • Optionally, you can further customize the definition of the key (e.g. click on “File Filters” > “Add” and enter the Filter Name Geodatabase File (*.mdb), enter the Filter *.mdb, click on Advanced and make sure that ‘Store File Location Relative to Catalog Directory’ is selected)

image019

 

  • Double-click on the ‘Base’ scenario to see the new addition to the user interface and select the proper input (e.g. dataset from a geodatabase)

image020

 

A few suggestions on the usage of catalog keys:

  • Use catalog keys for any scenario specific input that you want to define
  • Use a Name, Prompt and Description that are helpful to immediately understand the role of the key in your model
  • Organize catalog keys in groups, grouping them by relative purpose/usage
  • Sort them in a conceptually logical order for an applier to your model
  • Do not use string catalog keys to define file names. These are not updates if you change location/name for your catalog folder. You should use “File Name” type instead.

 

6th step: Include Programs to achieve Modeling Tasks

We refer here to Cube Voyager programs, but the other modules available (Land, Avenue, Analyst, Cargo) have a very similar structure and can be included in the process with a similar methodology and similar properties.

Cube Voyager has been designed to be an integrated modelling system for transportation planning applications.

Cube Voyager is a library of programs that employ a flexible control language that allows the user to write the script to provide instructions for performing all types of transport modelling operations or data processing tasks.

image021

 

Each program has a specific function and structure. The programs available within the Cube Voyager module are the following:

  • PILOT: Control process flows, call modules, run shell commands, compute/store/retrieve ‘global’ variables
  • NETWORK: Building, Comparing and Manipulating Highway Networks (inputs/outputs)
  • MATRIX: Demand Modeling and Matrix Manipulations/Record Processing
  • HIGHWAY: Pathbuilding, Skimming, and Assignment of Highway Networks
  • PT: All Public Transit Functions
  • GENERATION: Trip Generation (Productions and Attractions) applying linear equations
  • DISTRIBUTION: Trip Distribution based upon impedance (cost) matrices and Productions/Attractions
  • FRATAR: Matrix Growth Factoring

By clicking on one of these programs you include it within the Application Manager flow-chart, for example:

  • Double-click on the “Network Processing” sub-group to enter this sub-group
  • From the Home Tab, under Voyager, click “Network”
  • Templates are available for a number of functionalities, but Cube Voyager also provides also a flexible scripting language built for transport modelers. This allows you to achieve ad-hoc/customized tasks. To enter a program with a default basic structure, but no pre-built template, select the Default Template option in the “Select an Item” window

image022

 

A program has input files, output files, and an execution order:

  • The input files are displayed on the left.
  • The output files are displayed on the right.
  • The execution order is the number attached to the program. This allows you to customize the order in which the program is executed when running the model.

Every program has two key files:

  • Script file (.S) – Contains Program Instructions. Script files are automatically created and maintained by Application Manager (AM). AM keeps track of all of the input and output files, while you should add parameters, process blocks, calculations within the script using the Job Script Editor window available in Cube Base (double click to the script file within AM to open this window).  It is important that you remember to close the script when including inputs and outputs, as the user should NEVER edit the file names and locations in the script, as all changes to the file names and locations should be done in AM.
  • Print File (.PRN) – Contains Run Reports/Results

 

7th step: Linking Input Data Files

Data can be linked as input to a program through Application Manager in the four ways listed below. Right click on the input file you want to include to reach the first three options:

  • Link To File… – A hard link to a specific file. This file cannot be changed when running the model scenarios.
  • Link To Catalog Key… – A soft link to a user input. For each model scenario the user is responsible to verify the input.
  • Link To Token… – Can be a Voyager variable @..@ or an environmental variable %..%

image023

 

  • Create a direct (dynamic) link between program files by simply highlighting the output file you want to connect ‘from’ and then click and drag a link to the file you want to connect ‘to’. This could be done within the same sub-group or between sub-groups.

image024

 

8th step: Adding Scenarios

To add a new scenario, right click on the scenario name and select “Add Child” or “Add Sibling” depending on the level at which you want to add the scenario (note:  “Add Child” is only available for the Base scenario).

image025

 

A new scenario specific sub-folder will be created inside the parent scenario folder (e.g. Scenario_1 sub-folder inside the Base scenario folder).

An internal catalog key named {Scenario_Dir} stores the path of the scenario specific folder (allowing you to link inputs or outputs to this scenario specific location).

 


 

These 8 steps guide you through the set-up of your own model.  You can find more details and additional guidance on the different elements highlighted above in our Cube Base Reference Guide.  Details on scripting for the different Cube Voyager programs can be found in the Cube Voyager Reference Guide.