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