SWIM Interface Tutorial

Software Version: 0.9.3
Document Revision: 6
Date Created: July 31st 2017
Date Modified: Aug 12 2019
Creator: Luis Garnica
Status: Needs Update

The purpose of this document is to provide a guided walkthrough for the SWIM user interface. This document covers: obtaining access to the user interface, main screen options, step through creation of a user scenario, access to previous runs, cross-scenario comparison and user registration.

Used Terms

Term Description
User Scenario A personalized model input composed of user defined parameters and execution metadata.
Input Parameter A value that defines input to a target model.
Output Variable A model term that has been assigned a value after model execution.

User Interface Access

The modeling interface can be accessed directly by opening the Internet browser and navigating to: https://water.cybershare.utep.edu/swim/home. Alternatively it can be accessed through the project home page and selecting: Tools > SWIM Interface on the main menu.

Figure 1 Figure 01: SWIM Interface button on the public site main screen navigation bar

Main Screen Layout

Once access has been obtained, the page will display an introductory description of the system, and overview of the integrated water sustainability modeling framework.

The SWIM website contains the following main menu options:

  • Home: Redirects to the project homepage.
  • Introduction: Introductory description of the modeling interface.
  • Create Scenario: User interface for the specification, execution and output visualization of a modeling scenario.
  • Public Scenarios: Listing of all previously executed model runs that are openly available for consult.
  • Documentation: Overall system documentation website.
  • Login: User login, registration and access to personal user scenarios.

Figure 2 Figure 02: SWIM Interface main screen

Create Scenario

The create scenario workflow is divided into six steps to specify, run and visualize a user scenario. The user has the option to select a canned scenario on step 1 and directly skip to step 3, or go step by step with the option to personalize user changeable parameters in step 2.

The user workflow steps are described below:

  • Step 1 – Scenarios: Selection of predefined water supply scenarios.
  • Step 2 – Customize: Customization of specific input parameters.
  • Step 3 – Review and Run: Parameter listing and model execution.
  • Step 4 – Model Outputs: Execution summary and output variable visualizations.
  • Step 5 – Model Provenance: User workflow and data trace visualization.

Figure 3 Figure 03: Scenarios screen and Create Scenario main screen

Step 1: Scenarios

The purpose of this step is to select a base water supply scenario that will define a set of predefined input parameters, i.e.: if the base supply scenario is selected, parameters such as: annual water inflows at San Marcial, reservoir precipitation, and evaporation values will be set to observed data values from the selected time range.

Available scenarios are fully colored and clickable, non-available scenarios are faded and disabled. When a scenario is selected, a green border will appear on the chosen scenario image.

Water Supply Scenarios:

Base Water Supply: Uses observed data between 1994 and 2015.
Reduced Inflows at San Marcial Gauge: Reduces inflows by 10%.

Within Scenarios are multiple categories that allow further customization of the scenario:

  • Water Inflows: Selection of a base water supply scenario.
  • Policy: Selection of a base policy proposal.
  • Population: Set population growth or decrease trends.
  • Technology: Substitute natural resources with technology used to obtain water.

Figure 4 Figure 04: Customize screen under Create Scenario

Step 2: Customize

This step allows the user to personalize specific input parameter values that will be submitted to the model.

Stakeholder Choices are divided into the following input categories:

  • Urban: Municipal and Industrial input parameters.
  • Agriculture: Agricultural parameters - i.e. crop yield, crop prices.
  • Scenario: Natural water supply conservation limits in reference to starting year.

Figure 5 Figure 05: Example of user changeable parameters under Customize

Parameter Division:

  • User Changeable Parameters: The values for these type of parameters can be directly manipulated by the user with available input widgets such as: sliders, text fields and editable tables.

Input parameter widgets also come in the form of data tables. The figure below shows user changeable parameters for the agriculture category, the far-right column of each table (Value) can be modified directly.

Figure 6 Figure 06: Example of data table widgets under Customize

The figure below shows an example of an input parameter widget box. Each box contains the following elements:

  • Parameter title.
  • Parameter description.
  • Input widget to visualize and/or modify parameter values that can come in the form of text fields, sliders or data tables.
  • Parameter value units. i.e. USD/ton - (US dollars per ton).
  • Default source where the initial value came from.

Figure 7 Figure 07: Close up view of Input Parameter Widget Box under Customize

Step 3: Review and Run

The review and run step can be accessed directly at any time without having to specify scenarios or stakeholder choices, which allows the user to submit a model execution under default input values.

The review and run screen presented below contains a dynamic table listing all input parameters handled by the interface. The table shows parameter name, description, upper bound, lower bound, units, type and source for each input parameter. The table can be dynamically searched or sorted as required.

Figure 8 Figure 08: Review and Run screen under Create Scenario

Clicking on a row within the dynamic table of the Review and Run screen opens a Details sub-section, displaying the table information about the selected parameter in a clearer format.

Figure 9 Figure 09: Details sub-section of the Review and Run screen under Create Scenario

The Run Scenario green button will trigger a popup window to capture model metadata before submitting the user scenario for execution. All fields are required to enable the submit button.

If logged in, the user can specify if the scenario will be available to public, or just for private records.

Figure 10 Figure 10: Metadata and Execution modal window that appears when the Run Scenario button is clicked in the Review and Run screen

Step 4: Model Outputs

Once the execution of the model is complete the interface automatically switches to the Model Outputs section. This section contains all output variable values and metadata generated from the model execution.

The output section is divided into different categories and subsections:

  • Summary: Global aggregated values of interest generated
  • Urban: Municipal and industrial output variables.
  • Agriculture: Agricultural use output variables.
  • Storage: Yearly levels on aquifer and reservoirs
  • Flows: Economic river flow benefits.
  • Map: Spatial visualization of project area, water sources and gages.
  • JSON: Raw JSON format output of the executed user scenario.

The summary sub-section presents aggregated data generated from the overall model execution and is divided into two sections: Global Average Values (Figure 10) and Global Total Values (Figure 11).

Figure 11 Figure 11: A few of the output categories shown under Global Average Values in the Summary sub-section of Model Outputs

Global Average Values contains a set of output boxes with model generated values and information about each variable.

Each output variable box contains the following elements:

  • Variable Name (output)
  • Variable Description (output)
  • Model outputs compared with outputs from the historical period of 1995-2015
  • Measurement units of displayed values, i.e. 1000 USD/yr.

Figure 12 Figure 12: Global Total Values section in the Summary sub-section of Model Outputs

In Global Total Values, the Discounted Net Present Value of Benefits variable and the Total Agricultural Benefits variable are contained within boxes that contain the following elements:

  • Variable Name (output)
  • Variable Description (output)
  • Total output
  • Measurement units of displayed values, i.e. 1000 USD/yr.

The Total Surface Water and Total Agricultural Benefits by Period variables in Global Total Values, as well as all output variables within the Urban, Agriculture, Storage, and Flows sub-sections of Model Outputs, are contained within boxes that contain the following elements:

  • Variable Name (output)
  • Variable Description (output)
  • Visualization buttons located on the upper right side.
  • Visualization widget (single value, tabular data or line-chart) (Figure 12 & Figure 13).
  • Measurement units of displayed values, i.e. 1000 USD/yr.

Figure 13 Figure 13: Close up of output variable box with tabular data

The visualization buttons allow the user to switch between different views of data representation for a specific output variable. Chart visualizations are processed on demand once the chart-button is triggered.

Figure 14 Figure 14: Close up of output variable box with line-chart

The tabular data view allows the user to filter, sort or export selected data into a csv file. Options are available by clicking on the top right corner of the table widget.

Figure 15 Figure 15: Example of data filtering feature in tabular data view of output variable box

The Map sub-section of Model Outputs opens up an ArcGIS map of the USDA CAP Project Study area. It maps Gauge Stations, the Rio Grande River, Aquifers, Irrigation Districts, and Sub-basins.

Figure 16 Figure 16: ArcGIS map of the USDA CAP Project Study Area

The JSON sub-section of Model Outputs opens a JSON file containing all of the model output data.

Figure 17 Figure 17: JSON File of Model Outputs

Step 5: Model Provenance

This step generates a tree-based visualization of user workflow provenance and water model metadata; this allows users to trace the execution workflow and data sources for the current model run.

The tree structure is divided into the following levels:

  • User-workflow: Trace of workflow steps, parameter definition and sources, model execution and model outputs.
  • Water-model: Metadata information regarding the underlying used models such as, name, description, creators, modeling software, among other attributes.

Each level can be expanded by clicking on the solid nodes.

The first level of the provenance tree shows the user workflow steps which can be expanded to view activity details taken in that step.

Figure 18 Figure 18: First level of provenance tree expanded

The trace of input parameters can be viewed by expanding the following nodes: user-workflow > Step 3: stakeholder-choices > List of Parameters

The input parameters are divided into categories that can be further expanded to focus on specific input. Each input parameter node will expand to show metadata information, default values, and user defined values.

Figure 19 Figure 19: Provenance tree expanded to show metadata information, default values, and user defined values

Public Scenarios

The public scenarios section displays a table listing of all the previously executed user scenarios through the user interface. Each entry displays a unique id, name, date, base scenario, climate scenario and status of the submitted experiment. The table can be sorted and filtered as required.

Figure 20 Figure 20: Public Scenarios main screen

User Scenario Details

Each entry row contains a button under the details column. When the button is triggered the application loads a popup box with general information about the model run (user scenario).

Results can be viewed as a RAW JSON format or can be repopulated into the create scenario workflow.

Figure 21
Figure 21: User Scenario modal window that appears when the Details column of a public scenario is clicked

Figure 22 Figure 22: Raw JSON file produced with the public scenario outputs

Scenario Comparison

Users have the options of comparing up to two scenarios. This can be done by selecting two rows in the Public Scenarios page (selected rows are highlighted) and selecting the "Compare" button underneath.

Figure 23 Figure 23: Bottom of the Public Scenarios page with two scenarios selected

Once the "Compare" button has been selected, the Cross Compare page will open. The Cross Compare page can be divided into three subsections:

  • Summary: Displays summarized information about the two scenarios and the comparison of their outputs.

Figure 24 Figure 24: Summarized information about the two scenarios under the Summary tab on the Cross Comparison page

Figure 25 Figure 25: Summarized comparison of the outputs for both scenarios under the Summary tab on the Cross Comparison page

  • Inputs: Displays a detailed table comparing all inputs for the two scenarios and allows comparison of specific inputs.

Figure 26 Figure 26: Detailed comparison table of all inputs for both scenarios under the Inputs tab on the Cross Comparison page

If the user selects a row, the user will automatically be taken to the Comparison tab under the Inputs tab. This page will show a detailed comparison of the input selected by the user.

Figure 27 Figure 27: Detailed comparison tables of the Agriculture Pumping Capacity input

  • Outputs: Displays a detailed table comparing all outputs for the two scenarios and allows comparison of specific outputs.

Figure 28 Figure 28: Detailed comparison table of all outputs for both scenarios under the Outputs tab on the Cross Comparison page

If the user selects a row, the user will automatically be taken to the Comparison tab under the Output tab. This page will show a detailed comparison of the output selected by the user.

Figure 29 Figure 29: Detailed comparison tables of the Agriculture Return from Pumping to Aquifer output

If the output changes over time, the user can view these changes in a line graph by selecting the "Chart View" button.

Figure 30 Figure 30: Detailed comparison charts of the Agriculture Return from Pumping to Aquifer output

The user can move between the three tabs by either clicking "Next" and "Previous" or by clicking on the tabs directly.

User Registration

Any user has the option to register into the system. Registered users have the capability of separately viewing their own input scenarios with the option to make them public or not before execution.

To register the user must trigger the login dropdown menu located on the far right of the main menu. There is an option to login directly or register into the system.

Figure 31
Figure 31: Sign in dropdown menu on navigation bar

Figure 32 Figure 32: Sign up modal window that appears if you select Register in the sign in dropdown

My Scenarios

Registered users can log into the system and have access to view their own previously executed scenarios.

Figure 33
Figure 33: Dropdown menu on navigation bar

Figure 34 Figure 34: Data table filled with past user scenarios

Contact Information

Luis Antonio Garnica Chavira
Software Engineering Consultant
Git Gud Consulting SAS
luis@gitgudconsulting.com

Dr. Deana Pennington
Associate Professor
Department of Geological Sciences
University of Texas at El Paso
ddpennington@utep.edu