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 image file
51 Main dialog
53 The Graphical Modeler can be launched from the Layer Manager menu File
54 -> Graphical modeler or from the main toolbar . It’s also available as
55 stand-alone module g.gui.gmodeler.
56 The main Graphical Modeler menu contains options which enable the user
58 to fully control the model. Directly under the main menu one can find
59 toolbar with buttons (see figure below). There are options including
60 (1) Create new model, (2) Load model from file, (3) Save current model
61 to file, (4) Export model to image, (5) Export model to Python script,
62 (6) Add command (GRASS modul) to model, (7) Add data to model, (8) Man‐
63 ually define relation between data and commands, (9) Add loop/series to
64 model, (10) Add comment to model, (11) Redraw model canvas, (12) Vali‐
65 date model, (13) Run model, (14) Manage model variables, (15) Model
66 settings, (16) Show manual, (17) Quit Graphical Modeler.
67 Figure: Components of Graphical Modeler menu toolbar.
69 There is also a lower menu bar in the Graphical modeler dialog where
71 one can manage model items, visualize commands, add or manage model
72 variables, define default values and descriptions. The Python editor
73 dialog window allows seeing workflows written in Python code. The
74 rightmost tab of the bottom menu is automatically triggered when the
75 model is activated and shows all the steps of running GRASS modeler
76 modules. In case of errors in the calculation process, it is written at
77 that place.
78 Figure: Lower Graphical Modeler menu toolbar.
79 Components of models
81 The workflow is usually established from four types of diagrams. Input
82 and derived model data are usually represented with oval diagrams. This
83 type of model elements stores path to specific data on the user’s disk.
84 It is possible to insert vector data, raster data, database tables,
85 etc. The type of data is clearly distinguishable in the model by its
86 color. Different model elements are shown in the figures below.
87 • (A) raster data:
89 • (B) relation:
91 • (C) GRASS module:
93 • (D) loop:
95 • (E) database table:
97 • (F) 3D raster data:
99 • (G) vector data:
101 • (H) disabled GRASS module:
103 • (I) comment:
105 Figure: A model to perform unsupervised classification using MLC
106 (i.maxlik) and SMAP (i.smap).
107 Another example:
109 Figure: A model to perform estimation of average annual soil loss
110 caused by sheet and rill erosion using The Universal Soil Loss Equa‐
111 tion.
112 Example as part of landslide prediction process:
114 Figure: A model to perform creation of parametric maps used by geolo‐
115 gists to predict landslides in the area of interest.
116
118 In this example the zipcodes_wake vector data and the elev_state_500m
119 raster data from the North Carolina sample dataset (original raster and
120 vector data) are used to calculate average elevation for every zone.
121 The important part of the process is the Graphical Modeler, namely its
122 possibilities of process automation.
123 The workflow shown as a series of commands
125 In the command console the procedure looks as follows:
126 # input data import
127 r.import input=elev_state_500m.tif output=elevation
128 v.import input=zipcodes_wake.shp output=zipcodes_wake
129 # computation region settings
130 g.region vector=zipcodes_wake
131 # raster statistics (average values), upload to vector map table calculation
132 v.rast.stats -c map=zipcodes_wake raster=elevation column_prefix=rst method=average
133 # univariate statistics on selected table column for zipcode map calculation
134 v.db.univar map=zipcodes_wake column=rst_average
135 # conversion from vector to raster layer (due to result presentation)
136 v.to.rast input=zipcodes_wake output=zipcodes_avg use=attr attribute_column=rst_average
137 # display settings
138 r.colors -e map=zipcodes_avg color=bgyr
139 d.mon start=wx0 bgcolor=white
140 d.barscale style=arrow_ends color=black bgcolor=white fontsize=10
141 d.rast map=zipcodes_avg bgcolor=white
142 d.vect map=zipcodes_wake type=boundary color=black
143 d.northarrow style=1a at=85.0,15.0 color=black fill_color=black width=0 fontsize=10
144 d.legend raster=zipcodes_avg lines=50 thin=5 labelnum=5 color=black fontsize=10
145 Defining the workflow in the Graphical Modeler
147 To start performing above steps as an automatic process with the Graph‐
148 ical Modeler press the icon or type g.gui.gmodeler. The simplest way
149 of inserting elements is by adding the complete GRASS command to the
150 Command field in the GRASS command dialog (see figure below). With
151 full text search one can do faster module hunting. Next, the label and
152 the command can be added. In case that only a module name is inserted,
153 after pressing the Enter button, the module dialog window is displayed
154 and it is possible to set all of the usual module options (parameters
155 and flags).
156 Figure: Dialog for adding GRASS commands to model.
158 Managing model parameters
160 All used modules can be parameterized in the model. That causes launch‐
161 ing the dialog with input options for model after the model is run. In
162 this example, input layers (zipcodes_wake vector map and
163 elev_state_500m raster map) are parameterized. Parameterized elements
164 show their diagram border slightly thicker than those of unparameter‐
165 ized elements.
166 Figure: Model parameter settings.
167 The final model, the list of all model items, and the Python code win‐
169 dow with Save and Run option are shown in the figures below.
170 Figure: A model to perform average statistics for zipcode zones.
171 Figure: Items with Python editor window.
173 For convenience, this model for the Graphical Modeler is also available
175 for download here.
176 The model is run by clicking the Run button . When all inputs are set,
178 the results can be displayed as shown in the next Figure:
179 Figure: Average elevation for ZIP codes using North Carolina sample
180 dataset as an automatic calculation performed by Graphical Modeler.
181 Managing model properties
183 When one wants to run model again with the same data or the same names,
184 it is necessary to use --overwrite option. It will cause maps with
185 identical names to be overwritten. Instead of setting it for every mod‐
186 ule separately it is handy to change the Model Property settings glob‐
187 ally. This dialog includes also metadata settings, where model name,
188 model description and author(s) of the model can be specified.
189 Figure: Model properties.
190 Defining variables
192 Another useful trick is the possibility to set variables. Their content
193 can be used as a substitute for other items. Value of variables can be
194 values such as raster or vector data, integer, float, string value or
195 they may constitute some region, mapset, file or direction data type.
196 Then it is not necessary to set any parameters for input data. The dia‐
197 log with variable settings is automatically displayed after model is
198 run. So, instead of model parameters (e.g. r.import a v.import, see the
199 Figure Run model dialog above) there are Variables.
200 Figure: Model with variable inputs.
201 The key point is the usage of % before the substituting variable and
203 settings in Variables dialog. For example, in case of a model variable
204 raster that points to an input file path and which value is required to
205 be used as one of inputs for a particular model, it should be specified
206 in the Variables dialog with its respective name (raster), data type,
207 default value and description. Then it should be set in the module dia‐
208 log as input called %raster.
209 Figure: Example of raster file variable settings.
210 Figure: Example of raster file variable usage.
211 Saving the model file
213 Finally, the model settings can be stored as a GRASS GIS Model file
214 with *.gxm extension. The advantage is that it can be shared as a reus‐
215 able workflow that may be run also by other users with different data.
216 For example, this model can later be used to calculate the average pre‐
218 cipitation for every administrative region in Slovakia using the precip
219 raster data from Slovakia precipitation dataset and administration
220 boundaries of Slovakia from Slovak Geoportal (only with a few clicks).
221 Handling intermediate data
223 There can be some data in a model that did not exist before the process
224 and that it is not worth it to maintain after the process executes.
225 They can be described as being Intermediate by single clicking using
226 the right mouse button, see figure below. All such data should be
227 deleted following model completion. The boundary of intermediate compo‐
228 nent is dotted line.
229 Figure: Usage and definition of intermediate data in model.
230 Using the Python editor
232 By using the Python editor in the Graphical Modeler one can add Python
233 code and then run it with Run button or just save it as a Python script
234 *.py. The result is shown in the Figure below:
235 Figure: Python editor in the wxGUI Graphical Modeler.
236 Defining loops
238 In the example below the MODIS MOD13Q1 (NDVI) satellite data products
239 are used in a loop. The original data are stored as coded integer val‐
240 ues that need to be multiplied by the value 0.0001 to represent real
241 ndvi values. Moreover, GRASS GIS provides a predefined color table
242 called ndvi to represent ndvi data. In this case it is not necessary
243 to work with every image separately.
244 The Graphical Modeler is an appropriate tool to process data in an ef‐
245 fective way using loop and variables (%map for a particular MODIS image
246 in mapset and %ndvi for original data name suffix). After the loop
247 component is added to model, it is necessary to define series of maps
248 with required settings of map type, mapset, etc.
249 Figure: MODIS data representation in GRASS GIS after Graphical Modeler
250 usage.
251 When the model is supplemented by all of modules, these modules should
253 be ticked in the boxes of loop dialog. The final model and its results
254 are shown below.
255 Figure: Model with loop.
256 Figure: MODIS data representation in GRASS GIS after Graphical Modeler
258 usage.
259 The steps to enter in the command console of the Graphical Modeler
261 would be as follows:
262 # note that the white space usage differs from the standard command line usage
263 # rename original image with preselected suffix
264 g.rename raster = %map,%map.%ndvi
265 # convert integer values
266 r.mapcalc expression = %map = %map.%ndvi * 0.0001
267 # set color table appropriate for nvdi data
268 r.colors = map = %map color = ndvi
269
271 wxGUI
272 wxGUI components
273 See also selected user models available from GRASS Addons repository.
275 See also the wiki page (especially various video tutorials).
277
279 Martin Landa, OSGeoREL, Czech Technical University in Prague, Czech Re‐
280 public
281 Various manual improvements by Ludmila Furkevicova, Slovak University
282 of Technology in Bratislava, Slovak Republic
283
285 Available at: wxGUI Graphical Modeler source code (history)
286 Accessed: Saturday Jan 21 20:42:04 2023
288 Main index | GUI index | Topics index | Keywords index | Graphical in‐
290 dex | Full index
291 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
293GRASS 8.2.1 wxGUI.gmodeler(1)