Decision Support Framework User Guides
DSF 203
DSF SWAT Interface
March 2004
Mekong River Commission
Water Utilisation Project Component A: Development of Basin
Modelling Package and Knowledge Base (WUP-A)
Decision Support Framework User Guides
DSF 203
DSF SWAT Interface
March 2004
Halcrow Group Limited
Burderop Park Swindon Wiltshire SN4 0QD
Tel +44 (0)1793 812479 Fax +44 (0)1793 812089
www.halcrow.com
Halcrow Group Limited has prepared this report in accordance with the
instructions of their client, Mekong River Commission, for their sole and
specific use. Any other persons who use any information contained
herein do so at their own risk.
© Halcrow Group Limited 2016
Mekong River Commission
Water Utilisation Project Component A: Development of Basin
Modelling Package and Knowledge Base (WUP-A)
Decision Support Framework User Guides
DSF 203
DSF SWAT Interface
March 2004
Halcrow Group Limited
Burderop Park Swindon Wiltshire SN4 0QD
Tel +44 (0)1793 812479 Fax +44 (0)1793 812089
www.halcrow.com
Halcrow Group Limited has prepared this report in accordance with the
instructions of their client, Mekong River Commission, for their sole and
specific use. Any other persons who use any information contained
herein do so at their own risk.
© Halcrow Group Limited 2016
Decision Support Framework User Guides
DSF 203
DSF SWAT Interface
Contents Amendment Record
This report has been issued and amended as follows:
Issue
Revision
Description
Date
Signed
1
0
Submitted as part of draft
Final Report
Dec 2003
MFW
2
1
Re-submitted as part of Final
Report
March
2004
MFW
Contents
1
Introduction
1.1 The DSF-SWAT Interface
2
1
2
Preparing and Running the Model
2.1 Introduction
2.2 Main Form
2.2.1 Apply Climate Change Factors
2.2.2 Edit/Review Model Data Text Files
2.2.3 The Map View
2.2.4 Model Detail
2.2.5 Running a SWAT Model
3
3
3
4
5
6
9
9
3
Reviewing Model Results
3.1 Introduction
3.2 Selecting Model Output Data
3.2.1 Watershed Summary Model Results
3.2.2 Sub-Basin / Main Channel Model Results
3.2.3 Hydrological Response Unit Results
3.2.4 Selecting Model Areas – Sub-Basins and HRUs
3.3 Selecting Output File Variables
3.3.1 Selecting Output File Variables
3.3.2 Selecting datasets to chart
3.4 Charting and Exporting Model Results
10
10
10
12
12
13
13
14
15
16
17
4
Saving Model Results to the DSF
4.1 Time-Series Data
4.1.1 Factored and Unfactored Data
19
19
19
1
Introduction
1.1
The DSF-SWAT Interface
The DSF-SWAT interface provides the DSF ‘operator’ with a simple
GUI from which they can ‘run’ models. It is initiated from the main DSF
interface, when the user has selected to ‘Run / Edit’ a DSF development
scenario SWAT model from the ‘Simulation Model Launcher’.
All model results generated form a SWAT model run will be associated
with a particular DSF development scenario, and may be used as input
data to additional simulation models (e.g., IQQM, iSIS) or in the DSF
impact analysis tools.
The DSF-SWAT interface provides the following functionality:








1
Apply climate change factors to the selected SWAT model subbasins on a month-by-month basis.
Directly edit and / or review SWAT model text files.1
Display DSF ‘views’ and load ESRI shapefiles into the map
control to assist in spatially locating model features of interest.
Run DSF SWAT models.2
Select model results from each of the six SWAT output files:
Watershed Summary File; Sub-Basin Output File; Main Channel
Output File; Hydrological Response Unit (HRU) Output File;
HRU Impoundment Output File; and Reservoir Output File.3
View up to two different model results variables on the same
chart: an unlimited number of model features may be selected.4
View calibration data / results from previous model runs or other
DSF Knowledge Base datasets on the same chart.
Export model results time-series data to a comma separated text
file, for evaluation in the DSF Time-Series Impact Analysis
Tools.
Editing of SWAT model text files is currently restricted to editing of the sub-basin management files – to
enable the DSF ‘operator’ to model land use change scenarios.
2
The DSF SWAT model must be configured to produce daily model results as text files.
3
The results from the sub-basin output file are the principal results used by the DSF Simulation Modelling
and Impact Analysis processes.
4
The HRU Impoundment Output File and Reservoir Output File are currently not supported.
Doc No Rev: 1 Date: March 2004
106761707
1

Import model results time-series data to the DSF Knowledge
Base.
The DSF-SWAT interface does not provide the functionality to edit the
model input data. This task must be pre-prepared by a specialist modeller
outside of the DSF-SWAT interface application.
Doc No Rev: 1 Date: March 2004
106761707
2
2
Preparing and Running the Model
2.1
Introduction
When a user selects to ‘Edit / Run’ a SWAT model from the main DSF
Interface, the selected SWAT model is extracted from the DSF
Knowledge Base to the DSF temporary folder – typically located on the
user’s client machine. The main DSF interface initialises the DSF-SWAT
interface to use the extracted model.
2.2
Main Form
The DSF-SWAT Interface ‘Main Form’ enables the user to edit and run
the SWAT model – see Figure 1 below.
Figure 1: DSF-SWAT Interface Main Form
The title of the selected SWAT model is displayed in the Main Form title
bar. The top half of the main form allows the user to: ‘Apply Climate
Change Factors’; and ‘Edit/Review Model Data Text Files’. The bottom
Doc No Rev: 1 Date: March 2004
106761707
3
half of the main form provides: a map view of a DSF view and the ability
to import additional GIS map layers, assisting the user to ‘locate’ the
model being run; model start date and end date information; functionality
to run the model and view the results.
2.2.1
Apply Climate Change Factors
The first tabbed page on the main form allows the user to apply climate
change factors for each sub-basin on a monthly basis for precipitation,
temperature, solar radiation and relative humidity (see Figure 1). The
factors that the user must specify vary according to the selected
parameter:




Precipitation factors must be specified as a percentage change
(+ or -)
Temperature factors must be specified as a degrees centigrade
change (+ or -)
Solar radiation factors must be specified as a MJ/m^2/day
change (+ or -)
Relative humidity factors must be specified as a fraction
The required climate change variable must be selected from the dropdown list. The user may enter climate change factors into the grid in one
of three ways:



Selecting a single sub-basin for a single month and entering the
climate change factor
Checking ‘Apply Global Edit’ and selecting a single month and
entering the climate change factor – this will apply the same
factor across all sub-basins
Selecting a range of months (and sub-basins) and entering the
climate change factor – this will apply the factor to all selected
‘cells’
Before changing the selected climate change variable, the user must
ensure that they confirm any changes by pressing the ‘Save Changes’
button.
Doc No Rev: 1 Date: March 2004
106761707
4
2.2.2
Edit/Review Model Data Text Files
The second tabbed page on the main form allows the user to review the
model data text files that comprise the SWAT model and, where specified by
the DSF administrator5, edit the model data text files (see Figure 2). The
SWAT model exported from the DSF must be ‘editable’, i.e., not an
‘accepted’ model, to allow text file editing.
Figure 2: Edit / Review Model Data Text Files
The ‘Select Model Input File Type’ drop-down list gives a listing of all
types of model data text files. Those types of files that have been specified
as editable are shown in the drop-down list with a suffix indicating its
editable status. The ‘Select Model Input File’ list gives a listing of all
individual files that are of the specified type, or where no files of the
specified type are available, all individual files.
After selecting the type and individual file of interest, the user may click
on the ‘View File’ button to display the file in the adjacent text box.
Where an editable file is displayed, double-clicking the text box will popup a new window enabling the user to edit the text file and save changes.
The ‘File, Save’ menu item only becomes enabled after the user has made
changes to the text. The user must be careful when making edits that the
edited data remains in the same format as the original file. It is important to
note that the editing of model text files does not check that the edited file is in the
required format.
5
The DSF Administrator can set model data text files to editable through use of the DSF-SWAT interface
application database.
Doc No Rev: 1 Date: March 2004
106761707
5
Figure 3: Editing SWAT Management Input Files
2.2.3
The Map View
The DSF-SWAT interface map viewer enables the user to visualise the
loaded simulation model. The view shown is selected by the user from the
main DSF interface, prior to initialising the DSF-SWAT interface. The
user is also provided with the facilities to display a variety of additional
information and to change the configuration of the view.
Doc No Rev: 1 Date: March 2004
106761707
6
(a)
Figure 4: Map Tool Bar
The Map Tool Bar

Mouse Pointer

Pan Tool

Zoom-In Tool

Zoom-Out Tool

Zoom to Theme

Zoom to Full Extent

Select (disabled)
 Add Theme
where;

Tools

Buttons
The toolbar contains a number of useful buttons and tools. A button
performs an action as soon as it is clicked. In contrast, a tool is selected
first and then requires some form of user input. While active a tool
appears pressed down. Buttons do not remain pressed after clicking them.
(i)
Buttons
(a)
Zoom to Full Extent – when clicked the view is zoomed
to fit all of the loaded layers (including those that are not
visible).
(b) Zoom to Selected Layer – when clicked the view is
zoomed to fit the currently selected layer (in the GIS
themes table) to the full window.
(ii)
Tools
All of the following tools perform actions on the currently active layer.
The active layer is the one selected (and highlighted) in the GIS themes
table. The table is located in the ‘View Information’ frame alongside the
map view. It is by default hidden, however the user can view the contents
by clicking on the table header, which always remains visible. A second
click on the header will hide the rest of the table again. See section
2.2.3(b) for more details on the ‘View Information’ frame.
(a)
Mouse Pointer – this returns the on-screen mouse
pointer to its default function from the pan or zoom
tools.
(b) Pan Function – when selected (shown by the mouse
pointer changing to a hand symbol) this tool enables the
user to move around the map view by moving the mouse
in the required pan direction while holding down the left
mouse button.
Doc No Rev: 1 Date: March 2004
106761707
7
(c)
(d)
(e)
(b)
Zoom in Tool - this tool enables the user to select a
specific zoom extent using the mouse. Once this tool is
selected (shown by the mouse pointer changing to a
magnifying glass symbol), the user can zoom in to any
region of the map display. First press and hold the left
mouse button at one corner of the area of interest. Still
holding the mouse button, drag across the area of
interest. A dashed rectangular outline will appear. This
represents the extent of the zoomed area, as the mouse is
dragged the rectangle increases in size. The mouse
should be dragged until the rectangle encompasses the
area of interest. When the mouse button is released the
map will be rescaled so that the rectangular region
dragged just fills the map window.
Zoom out Tool - this tool enables the user to zoom out
from the displayed view. Once this tool is selected
(shown by the mouse pointer changing to a magnifying
glass symbol), the user can zoom out by following a
similar procedure to the zoom in tool. The user can
create a dashed rectangular outline on the view by
pressing and holding the left mouse button and then
dragging across the view. As the mouse is dragged, the
rectangle increases in size. The size of the rectangle
relates to the extent that the current view will zoom out.
The smaller the rectangle the greater the relative change
in zoom. When the mouse button is released the map
will be rescaled.
Add Theme Tool – this tool enables the user to add a
spatial dataset to the map view. The user is presented
with a standard browse tool from which can be selected
map themes. When the user clicks the ‘OK’ button the
selected theme will be added to the map view as the topmost theme.
The View Information Frame
The map view information frame is located alongside the map view. It
provides the user with useful information about the current map view and
also provides the capability to make changes to the map display. A typical
view information frame is displayed in Figure 5.
Figure 5: Map View Information – 1
A table is provided in the top-left corner of the frame that lists all GIS
themes currently loaded onto the map view. Initially this is hidden and the
user must click on the header to reveal the full table as shown in Figure 6.
Doc No Rev: 1 Date: March 2004
106761707
8
The text box below the GIS themes table displays the title of the currently
active theme. The active theme on the map view will be shown
highlighted in the table. Only one theme may be highlighted at any one
time, but the user can change the active theme by changing the
highlighted theme in the table. The top-most theme always appears at the
top of the table, though the user can change the theme order by dragging
rows up or down with the mouse.
Figure 6: Map View Information – 2
The list box in the bottom-left corner of the frame is populated with all
field data types associated with the features of the active theme. The user
may select any of these and then display the field values alongside the
appropriate features on the map view by clicking the ‘Label Layer’ check
box to true. It should be noted that when labels are visible on the map
view, they will not resize if the user zooms in or out. To resize the labels
the user should click the ‘Label Layer’ check box off and then back on
again after zooming is complete.
The view information window also illustrates the current scale of the map
view and the current cursor Easting and Northing. The cursor
coordinates are displayed as “X” and “Y” values specified in metres and
are continuously updated while the cursor is over the map area.
2.2.4
Model Detail
The model detail frame specifies the model start date, end date and
frequency, according to the pre-selected model input data. It is important to
note that the DSF-SWAT interface does not provide the functionality to edit the model
input data. The user may choose to select a model sub-period using the
drop-down ‘date picker’ control provided, prior to running the SWAT
model. No checks are made to ensure that the user selected start dates
and end dates are valid.
2.2.5
Running a SWAT Model
A SWAT model is run by simply clicking on the ‘Run’ button – SWAT is
run in the background in a hidden window. The mousepointer changes to
an hourglass to indicate that the model is being run. When the model has
finished running, the ‘Results’ button becomes enabled, allowing the user
to review and save model results to the DSF.
Doc No Rev: 1 Date: March 2004
106761707
9
3
Reviewing Model Results
3.1
Introduction
The successful completion of a SWAT simulation will mean that results
files will have been generated. The DSF-SWAT interface provides users
with the capability to produce charts to view the model results and
compare them against ‘calibration’ datasets. Results files can also be
exported out of the DSF-SWAT interface application, enabling their
assessment in the DSF impact analysis tools. If the results are then
deemed satisfactory, the results can then be saved to the DSF Knowledge
Base.
3.2
Selecting Model Output Data
After selecting to view the model ‘Results’ from the main form, the
selection of the type of results to be reviewed must be made. SWAT
produces six types of model results: Sub-basin Output; Main Channel
Output; Hydrological Response Unit (HRU) Output; HRU
Impoundment Output; Reservoir Output; and a Watershed Summary
Output. The selection of the required type, and location, of model output
data is made from the first tabbed page of the ‘SWAT Model Results’
form (see Figure 7). Also shown on the first tab are a summary of the
model details and the map view and map view information.
Doc No Rev: 1 Date: March 2004
106761707
10
Figure 7: SWAT Model Results
The type of model results to review must be specified from the ‘Select
Data’ frame. The options within the frame available will vary according to
the schematisation of the SWAT model: The ‘HRU Impoundment
Output’ and ‘Reservoir Output’ check boxes will be disabled if the SWAT
model does not contain any impoundments or reservoirs (see Figure 8).
Where the SWAT model imported into the DSF does not contain the file
‘hrulandusesoilrepswat.txt’ file, all options relating to HRU’s will be
hidden (see Figure 9).
Doc No Rev: 1 Date: March 2004
106761707
11
Figure 8: SWAT Model Results – With HRU option
Figure 9: SWAT Model Results – Without HRU option
Depending on the selection of the type of results file to review, it may
then be necessary to specify the location of the required results from the
available grids.
3.2.1
Watershed Summary Model Results
If Watershed Summary results have been selected, there is no further
option available to select the location of the results – the results apply at
the scale of the watershed (the whole model).
3.2.2
Sub-Basin / Main Channel Model Results
If Sub-Basin or Main Channel results have been selected, there is a further
option available to select the location of the results. The grid immediately
adjacent to the ‘Select Data’ frame is populated with model Sub-Basins.
By default, all sub-basins are highlighted as selected. Selection of
individual sub-basins may be made by clicking on the appropriate grid
row – multiple selections may be made by use of the ‘Ctrl’ or ‘Shift’ key.
Doc No Rev: 1 Date: March 2004
106761707
12
3.2.3
Hydrological Response Unit Results
If Hydrological Response Unit (HRU) results have been selected, there is
a further option available to select the location of the results. A second
grid below the ‘Sub-Basin’ grid is populated with model HRUs for the
selected Sub-Basins6. By default, all HRUs are highlighted as selected.
Selection of individual HRUs may be made by clicking on the appropriate
grid row – multiple selections may be made by use of the ‘Ctrl’ or ‘Shift’
key (see Figure 10).
3.2.4
Selecting Model Areas – Sub-Basins and HRUs
The map view & view information may be used to assist in the selection
of model areas (see section 2.2.3). If the SWAT model has been originally
produced using the SWAT ‘ArcView’ interface, map themes may be
available that define the extent of the watershed, sub-basins, HRUs and
channel reaches. These themes will be cross-referenced with a feature
identifier used by the SWAT model. For example, Figure 10, shows the
map theme produced by the SWAT ‘ArcView’ interface for model subbasins (watsub.shp). The ‘SUBBASIN’ field has been selected and used to
label the map view. These labelled sub-basins correspond to the rows in
the grid adjacent to the ‘Select Data’ frame.
6
Each Sub-Basin may contain one or more HRU.
Doc No Rev: 1 Date: March 2004
106761707
13
Figure 10: Selection of Sub-Basin and HRU results
3.3
Selecting Output File Variables
Having selected the type and location of required output, the next stage in
reviewing model results is to select the model variables to chart and / or
save to the DSF Knowledge Base. The ‘Selected Output File Variables’
tabbed page is divided into two sections: a frame at the top of the page,
‘Output Files’, showing grid(s) that list the available model output
variables, and a grid at the bottom of the page showing the selected
variables available to chart / save.
Doc No Rev: 1 Date: March 2004
106761707
14
3.3.1
Selecting Output File Variables
The ‘Output Files’ frame may contain up to four separate grids,
depending on the selection made in selection model output data (see
section 3.2). Figure 11 shows only a single grid in the frame – where the
user has selected to view only ‘Sub-Basin’ output data.
Figure 11: Selecting Output File Variables
The frame grid(s) list all available model variables for the selected type of
result file(s). Each grid shows the variable name, if it is ‘selected’, if it is
‘converted’ and a variable description. The variable names and
descriptions are as used throughout the SWAT application. The ‘selected’
status of the variable may be changed by clicking on the appropriate
check-box. Default variables are pre-selected. The ‘converted’ status of
the variable is pre-selected and cannot be changed through the DSFSWAT interface7. The conversion enables SWAT variables to be viewed
7
Model variables are pre-selected and converted according to values set in the DSF-SWAT application
database. The DSF Administrator is able to edit the pre-selected variables in the application database.
Doc No Rev: 1 Date: March 2004
106761707
15
and saved in the DSF Knowledge Base using standard DSF variable units,
e.g., flow in cumecs.
3.3.2
Selecting datasets to chart
The selected output file variables are shown in the grid at the bottom of
the form as ‘Datasets available to save / chart’. Selection of datasets to
chart is made by clicking on the appropriate grid rows – multiple
selections may be made by use of the ‘Ctrl’ or ‘Shift’ key. Charting is
restricted to a maximum of two different variables; the only restriction on
the number of datasets that may be charted at any one time is that of
chart clarity.
The DSF-SWAT interface also allows the user to select ‘calibration data’
to chart against model datasets. Such calibration data may either be
observed data, exported from the DSF Knowledge Base, or modelled data
from previous SWAT model runs, exported from the DSF-SWAT
interface (see section 3.4). The user should select the ‘Calibration Data’
column for the required model dataset – a button becomes visible at the
right hand side of the grid cell. Clicking on the button enables the user to
‘browse’ for the calibration dataset (see Figure 12). After selecting the
required file, the path and file name are added to the ‘Calibration Data’
column (not shown).
Doc No Rev: 1 Date: March 2004
106761707
16
Figure 12: Adding ‘calibration’ data before charting
3.4
Charting and Exporting Model Results
The DSF-SWAT time-series viewer is initiated by clicking on the ‘Chart’
button, after a selection of datasets has been made from the ‘Datasets
available to save / chart’ grid. The time-series viewer provides simple
charting functionality to:





Doc No Rev: 1 Date: March 2004
106761707
Turn on and off selected datasets by checking the dataset title in
the chart legend
‘Pan and zoom’ around the chart: Left-click the mouse and drag
towards the bottom-right to select an area of the chart to zoom
to. Right-click the mouse and drag to pan along the chart. Leftclick the mouse and drag towards the top-left to zoom back to
the full extent of the chart.
Edit chart default values (e.g., formats, scales, labels, . . .)
Print the chart
Copy the chart to external applications
17
An option is also provided to export selected datasets to a CSV ASCII
file. The user must select the dataset from a drop-down list and click on
the button to pop up a window enabling them to navigate to the required
location. By default, the dataset title is specified as the file name.
Figure 13: Charting model results
Doc No Rev: 1 Date: March 2004
106761707
18
4
Saving Model Results to the DSF
4.1
Time-Series Data
If the user is satisfied with the results obtained from a model simulation
then time-series datasets can be extracted from the SWAT results files to
save to the DSF Knowledge Base. These results will be saved associated
to the current DSF development scenario.
Saving results to the DSF is initiated by clicking on the ‘Save to DSF’
button. All ‘selected’ results in the ‘Datasets available to save / chart’ grid
will be saved. The user will then be prompted to specify a status to assign
to the saved data. A selection must be made from the drop down list of
available statuses, as shown in Figure 14. After a selection has been made
the save procedure can be resumed by clicking the ‘OK’ button or by
simply closing the prompt window. The user will be kept informed of
progress throughout the save procedure – the label in the bottom-left of
the ‘SWAT Model Results’ form will update as each dataset is successfully
saved to the DSF.
It should be noted that any existing datasets previously saved from the
current SWAT model will be overwritten by a new save procedure. This is
the case even if different node data or different parameters, compared to
those previously saved, have been selected.
Figure 14: Selecting the Status of Saved Time-Series Data
It is recommended that the user first reviews the model results using the
DSF-SWAT charting and exporting facility before saving to the DSF
Knowledge Base.
4.1.1
Factored and Unfactored Data
The DSF-SWAT Interface saves both ‘factored’ and ‘unfactored’ data to
the DSF Knowledge Base. Such datasets are unique to the DSF
implementation of SWAT and are related to the use of an additional basin
factor file (basins.fac) as input to the SWAT model.
The basins factor file has been created to assist in model calibration.
Simple factors can be applied to the precipitation and evapotranspiration
time-series data inputs to the model, on a sub-basin by sub-basin basis.
Doc No Rev: 1 Date: March 2004
106761707
19
The ‘factored’ data saved to the DSF reflects the time-series data that has
been used as the input to the SWAT model, i.e., it includes the effect of
any factors applied. The ‘unfactored’ data saved to the DSF reflects the
time-series data used prior to the effect of applying such factors. It is
important to note that such factoring is independent of any climate change factors
applied through the DSF-SWAT Interface. Climate change factors may be
applied in addition to the application of model calibration factors.
Doc No Rev: 1 Date: March 2004
106761707
20