1wxGUI.gmodeler(1) GRASS GIS User's Manual wxGUI.gmodeler(1)
2
7 The Graphical Modeler is a wxGUI component which allows the user to
8 create, edit, and manage simple and complex models using an easy-to-use
9 interface. When performing analytical operations in GRASS GIS, the op‐
10 erations are not isolated, but part of a chain of operations. Using the
11 Graphical Modeler, a chain of processes (i.e. GRASS GIS modules) can be
12 wrapped into one process (i.e. model). Subsequently it is easier to ex‐
13 ecute the model later on even with slightly different inputs or parame‐
14 ters.
15 Models represent a programming technique used in GRASS GIS to concate‐
16 nate single steps together to accomplish a task. It is advantageous
17 when the user see boxes and ovals that are connected by lines and rep‐
18 resent some tasks rather than seeing lines of coded text. The Graphical
19 Modeler can be used as a custom tool that automates a process. Created
20 models can simplify or shorten a task which can be run many times and
21 it can also be easily shared with others. Important to note is that
22 models cannot perform specified tasks that one cannot also manually
23 perform with GRASS GIS. It is recommended to first to develop the
24 process manually, note down the steps (e.g. by using the Copy button in
25 module dialogs) and later replicate them in model.
26 The Graphical Modeler allows you to:
28 • define data items (raster, vector, 3D raster maps)
30 • define actions (GRASS commands)
32 • define relations between data and action items
34 • define loops (e.g. map series) and conditions (if-else state‐
36 ments)
37 • define model variables
39 • parameterize GRASS commands
41 • define intermediate data
43 • validate and run model
45 • save model properties to a file (GRASS Model File|*.gxm)
47 • export model to Python script
49 • export model to Python script in the form of a PyWPS process
51 • export model to image file
53 Main dialog
55 The Graphical Modeler can be launched from the Layer Manager menu File
56 -> Graphical modeler or from the main toolbar . It’s also available as
57 stand-alone module g.gui.gmodeler.
58 The main Graphical Modeler menu contains options which enable the user
60 to fully control the model. Directly under the main menu one can find
61 toolbar with buttons (see figure below). There are options including
62 (1) Create new model, (2) Load model from file, (3) Save current model
63 to file, (4) Export model to image, (5) Export model to Python script,
64 (6) Add command (GRASS module) to model, (7) Add data to model, (8)
65 Manually define relation between data and commands, (9) Add loop/series
66 to model, (10) Add comment to model, (11) Redraw model canvas, (12)
67 Validate model, (13) Run model, (14) Manage model variables, (15) Model
68 settings, (16) Show manual, (17) Quit Graphical Modeler.
69 Figure: Components of Graphical Modeler menu toolbar.
71 There is also a lower menu bar in the Graphical modeler dialog where
73 one can manage model items, visualize commands, add or manage model
74 variables, define default values and descriptions. The Python editor
75 dialog window allows seeing workflows written in Python code, either as
76 a basic Python script, or as a PyWPS script. The rightmost tab of the
77 bottom menu is automatically triggered when the model is activated and
78 shows all the steps of running GRASS modeler modules; in the case some
79 errors occur in the calculation process, they are are written at that
80 place.
81 Figure: Lower Graphical Modeler menu toolbar.
82 Components of models
84 The workflow is usually established from four types of diagrams. Input
85 and derived model data are usually represented with oval diagrams. This
86 type of model elements stores path to specific data on the user’s disk.
87 It is possible to insert vector data, raster data, database tables,
88 etc. The type of data is clearly distinguishable in the model by its
89 color. Different model elements are shown in the figures below.
90 • (A) raster data:
92 • (B) relation:
94 • (C) GRASS module:
96 • (D) loop:
98 • (E) database table:
100 • (F) 3D raster data:
102 • (G) vector data:
104 • (H) disabled GRASS module:
106 • (I) comment:
108 Figure: A model to perform unsupervised classification using MLC
109 (i.maxlik) and SMAP (i.smap).
110 Another example:
112 Figure: A model to perform estimation of average annual soil loss
113 caused by sheet and rill erosion using The Universal Soil Loss Equa‐
114 tion.
115 Example as part of landslide prediction process:
117 Figure: A model to create parametric maps used by geologists to predict
118 landslides in the area of interest.
119
121 In this example the zipcodes_wake vector data and the elev_state_500m
122 raster data from the North Carolina sample dataset (original raster and
123 vector data) are used to calculate average elevation for every zone.
124 The important part of the process is the Graphical Modeler, namely its
125 possibilities of process automation.
126 The workflow shown as a series of commands
128 In the command console the procedure looks as follows:
129 # input data import
130 r.import input=elev_state_500m.tif output=elevation
131 v.import input=zipcodes_wake.shp output=zipcodes_wake
132 # computation region settings
133 g.region vector=zipcodes_wake
134 # raster statistics (average values), upload to vector map table calculation
135 v.rast.stats -c map=zipcodes_wake raster=elevation column_prefix=rst method=average
136 # univariate statistics on selected table column for zipcode map calculation
137 v.db.univar map=zipcodes_wake column=rst_average
138 # conversion from vector to raster layer (due to result presentation)
139 v.to.rast input=zipcodes_wake output=zipcodes_avg use=attr attribute_column=rst_average
140 # display settings
141 r.colors -e map=zipcodes_avg color=bgyr
142 d.mon start=wx0 bgcolor=white
143 d.barscale style=arrow_ends color=black bgcolor=white fontsize=10
144 d.rast map=zipcodes_avg bgcolor=white
145 d.vect map=zipcodes_wake type=boundary color=black
146 d.northarrow style=1a at=85.0,15.0 color=black fill_color=black width=0 fontsize=10
147 d.legend raster=zipcodes_avg lines=50 thin=5 labelnum=5 color=black fontsize=10
148 Defining the workflow in the Graphical Modeler
150 To start performing above steps as an automatic process with the Graph‐
151 ical Modeler press the icon or type g.gui.gmodeler. The simplest way
152 of inserting elements is by adding the complete GRASS command to the
153 Command field in the GRASS command dialog (see figure below). With
154 full text search one can do faster module hunting. Next, the label and
155 the command can be added. In case that only a module name is inserted,
156 after pressing the Enter button, the module dialog window is displayed
157 and it is possible to set all of the usual module options (parameters
158 and flags).
159 Figure: Dialog for adding GRASS commands to model.
161 Managing model parameters
163 All used modules can be parameterized in the model. That causes launch‐
164 ing the dialog with input options for model after the model is run. In
165 this example, input layers (zipcodes_wake vector map and
166 elev_state_500m raster map) are parameterized. Parameterized elements
167 show their diagram border slightly thicker than those of unparameter‐
168 ized elements.
169 Figure: Model parameter settings.
170 The final model, the list of all model items, and the Python code win‐
172 dow with Save and Run option are shown in the figures below.
173 Figure: A model to perform average statistics for zipcode zones.
174 Figure: Items with Python editor window.
176 For convenience, this model for the Graphical Modeler is also available
178 for download here.
179 The model is run by clicking the Run button . When all inputs are set,
181 the results can be displayed as shown in the next Figure:
182 Figure: Average elevation for ZIP codes using North Carolina sample
183 dataset as an automatic calculation performed by Graphical Modeler.
184 Managing model properties
186 When the user wants to run the model again with the same data or the
187 same names, it is necessary to use --overwrite option. It will cause
188 maps with identical names to be overwritten. Instead of setting it for
189 every module separately it is handy to change the Model Property set‐
190 tings globally. This dialog includes also metadata settings, where
191 model name, model description and author(s) of the model can be speci‐
192 fied.
193 Figure: Model properties.
194 Defining variables
196 Another useful trick is the possibility to set variables. Their content
197 can be used as a substitute for other items. Value of variables can be
198 values such as raster or vector data, integer, float, string value or
199 they may constitute some region, mapset, file or direction data type.
200 Then it is not necessary to set any parameters for input data. The dia‐
201 log with variable settings is automatically displayed after the model
202 is run. So, instead of model parameters (e.g. r.import a v.import, see
203 the Figure Run model dialog above) there are Variables.
204 Figure: Model with variable inputs.
205 The key point is the usage of % before the substituting variable and
207 settings in the Variables dialog. For example, in the case of a model
208 variable raster that points to an input file path and which value is
209 required to be used as one of inputs for a particular model, it should
210 be specified in the Variables dialog with its respective name (raster),
211 data type, default value and description. Then it should be set in the
212 module dialog as input called %raster.
213 Figure: Example of raster file variable settings.
214 Figure: Example of raster file variable usage.
215 Saving the model file
217 Finally, the model settings can be stored as a GRASS GIS Model file
218 with *.gxm extension. The advantage is that it can be shared as a reus‐
219 able workflow that may be run also by other users with different data.
220 For example, this model can later be used to calculate the average pre‐
222 cipitation for every administrative region in Slovakia using the precip
223 raster data from Slovakia precipitation dataset and administration
224 boundaries of Slovakia from Slovak Geoportal (only with a few clicks).
225 Handling intermediate data
227 There can be some data in a model that did not exist before the process
228 and that it is not worth it to maintain after the process executes.
229 They can be described as being Intermediate by single clicking using
230 the right mouse button, see figure below. All such data should be
231 deleted following model completion. The boundary of intermediate compo‐
232 nent is dotted line.
233 Figure: Usage and definition of intermediate data in model.
234 Using the Python editor
236 By using the Python editor in the Graphical Modeler the user can add
237 Python code and then run it with Run button or just save it as a Python
238 script *.py. The result is shown in the Figure below:
239 Figure: Python editor in the wxGUI Graphical Modeler. In the Script
240 type combobox, the user can also choose a PyWPS export instead of a ba‐
241 sic Python script. A PyWPS process based on the model will be generated
242 then; for the PyWPS script, the Run button is disabled as users are ex‐
243 pected to include this script in their web processing service and not
244 to run it on itself.
245 Figure: Python editor in the wxGUI Graphical Modeler - set to PyWPS.
246 Defining loops
248 In the example below the MODIS MOD13Q1 (NDVI) satellite data products
249 are used in a loop. The original data are stored as coded integer val‐
250 ues that need to be multiplied by the value 0.0001 to represent real
251 ndvi values. Moreover, GRASS GIS provides a predefined color table
252 called ndvi to represent ndvi data. In this case it is not necessary
253 to work with every image separately.
254 The Graphical Modeler is an appropriate tool to process data in an ef‐
255 fective way using loop and variables (%map for a particular MODIS image
256 in mapset and %ndvi for original data name suffix). After the loop
257 component is added to model, it is necessary to define series of maps
258 with required settings of map type, mapset, etc.
259 Figure: MODIS data representation in GRASS GIS after Graphical Modeler
260 usage.
261 When the model is supplemented by all of modules, these modules should
263 be ticked in the boxes of loop dialog. The final model and its results
264 are shown below.
265 Figure: Model with loop.
266 Figure: MODIS data representation in GRASS GIS after Graphical Modeler
268 usage.
269 The steps to enter in the command console of the Graphical Modeler
271 would be as follows:
272 # note that the white space usage differs from the standard command line usage
273 # rename original image with preselected suffix
274 g.rename raster = %map,%map.%ndvi
275 # convert integer values
276 r.mapcalc expression = %map = %map.%ndvi * 0.0001
277 # set color table appropriate for nvdi data
278 r.colors = map = %map color = ndvi
279
281 wxGUI
282 wxGUI components
283 See also selected user models available from GRASS Addons repository.
285 See also the wiki page (especially various video tutorials).
287
289 Martin Landa, GeoForAll Lab, Czech Technical University in Prague,
290 Czech Republic
291 PyWPS support by Ondrej Pesek, GeoForAll Lab, Czech Technical Univer‐
292 sity in Prague, Czech Republic
293 Various manual improvements by Ludmila Furkevicova, Slovak University
294 of Technology in Bratislava, Slovak Republic
295
297 Available at: wxGUI Graphical Modeler source code (history)
298 Accessed: Saturday Oct 28 18:20:08 2023
300 Main index | GUI index | Topics index | Keywords index | Graphical in‐
302 dex | Full index
303 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
305GRASS 8.3.1 wxGUI.gmodeler(1)