Debian Codegraph @

gui/wxpython/gmodeler/g.gui.gmodeler.html

raw
1 <!-- meta page description: wxGUI Graphical Modeler -->
2 <!-- meta page index: topic_GUI|GUI -->
3 <h2>DESCRIPTION</h2>
4
5 <p>
6 The <b>Graphical Modeler</b> is a <em><a href="wxGUI.html">wxGUI</a></em>
7 component which allows the user to create, edit, and manage simple and
8 complex models using an easy-to-use interface.
9 When performing analytical operations in GRASS, the
10 operations are not isolated, but part of a chain of operations. Using the
11 Graphical Modeler, a chain of processes (i.e. GRASS modules)
12 can be wrapped into one process (i.e. model). Subsequently it is easier to
13 execute the model later on even with slightly different inputs or parameters.
14 <br>
15 Models represent a programming technique used in GRASS to
16 concatenate single steps together to accomplish a task. It is advantageous
17 when the user see boxes and ovals that are connected by lines and
18 represent 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 it can
21 also be easily shared with others. Important to note is that models cannot
22 perform specified tasks that one cannot also manually perform with GRASS.
23 It is recommended to first to develop the process manually, note down
24 the steps (e.g. by using the <i>Copy</i> button in module dialogs) and later
25 replicate them in model.
26
27 <p>
28 The Graphical Modeler allows you to:
29
30 <ul>
31 <li>define data items (raster, vector, 3D raster maps)</li>
32 <li>define actions (GRASS commands)</li>
33 <li>define relations between data and action items</li>
34 <li>define loops (e.g. map series) and conditions (if-else statements)</li>
35 <li>define model variables</li>
36 <li>parameterize GRASS commands</li>
37 <li>define intermediate data</li>
38 <li>validate and run model</li>
39 <li>save model properties to a file (<i>GRASS Model File|*.gxm</i>)</li>
40 <li>export model to Python script</li>
41 <li>export model to Python script in the form of a PyWPS process</li>
42 <li>export model to an actinia process</li>
43 <li>export model to image file</li>
44 </ul>
45
46 <h3>Main dialog</h3>
47
48 The Graphical Modeler can be launched from the Layer Manager menu
49 <code>File -&gt; Graphical modeler</code> or from the main
50 toolbar <img src="icons/modeler-main.png" alt="icon">. It's also
51 available as stand-alone module <em>g.gui.gmodeler</em>.
52
53 <p>
54 The main Graphical Modeler menu contains options which enable the user
55 to fully control the model. Directly under the main menu one can find
56 toolbar with buttons (see figure below). There are options including
57 (<font size="2" color="red">1</font>) Create new model,
58 (<font size="2" color="red">2</font>) Load model from file,
59 (<font size="2" color="red">3</font>) Save current model to file,
60 (<font size="2" color="red">4</font>) Export model to image,
61 (<font size="2" color="red">5</font>) Export model to a (Python/PyWPS/actinia) script,
62 (<font size="2" color="red">6</font>) Add command (GRASS module) to model,
63 (<font size="2" color="red">7</font>) Add data to model,
64 (<font size="2" color="red">8</font>) Manually define relation between
65 data and commands,
66 (<font size="2" color="red">9</font>) Add loop/series to model,
67 (<font size="2" color="red">10</font>) Add comment to model,
68 (<font size="2" color="red">11</font>) Redraw model canvas,
69 (<font size="2" color="red">12</font>) Validate model,
70 (<font size="2" color="red">13</font>) Run model,
71 (<font size="2" color="red">14</font>) Manage model variables,
72 (<font size="2" color="red">15</font>) Model settings,
73 (<font size="2" color="red">16</font>) Show manual,
74 (<font size="2" color="red">17</font>) Quit Graphical Modeler.
75
76 <p>
77 <center>
78 <img src="g_gui_gmodeler_toolbar.png">
79 <br>
80 <i>Figure: Components of Graphical Modeler menu toolbar.</i>
81 </center>
82
83 <p>
84 There is also a lower menu bar in the Graphical modeler dialog where one can
85 manage model items, visualize commands, add or manage model variables,
86 define default values and descriptions. The Script editor dialog window
87 allows seeing and exporting workflows as basic Python scripts, as PyWPS
88 scripts, or as actinia processes. The rightmost tab of the bottom menu is
89 automatically triggered when the model is activated and shows all the steps
90 of running GRASS modeler modules; in the case some errors occur in
91 the calculation process, they are are written at that place.
92
93 <center>
94 <a href="g_gui_gmodeler_lower_toolbar.png"><img src="g_gui_gmodeler_lower_toolbar.png" width="600" height="354"></a>
95 <br>
96 <i>Figure: Lower Graphical Modeler menu toolbar.
97 </i>
98 </center>
99
100 <h3>Components of models</h3>
101
102 The workflow is usually established from four types of diagrams. Input and
103 derived model data are usually represented with oval diagrams. This type of
104 model elements stores path to specific data on the user's disk. It is
105 possible to insert vector data, raster data, database tables, etc.
106 The type of data is clearly distinguishable in the model by its color.
107 Different model elements are shown in the figures below.
108
109 <ul>
110 <li> (<font size="2" color="red">A</font>) raster data: <img src="g_gui_gmodeler_raster.png" alt="raster" style="margin: 0px 0px -5px 0px"></li>
111 <li> (<font size="2" color="red">B</font>) relation: <img src="g_gui_gmodeler_relation.png" alt="relation" style="margin: 10px 0px 0px 0px"></li>
112 <li> (<font size="2" color="red">C</font>) GRASS module: <img src="g_gui_gmodeler_modul.png" alt="module" style="margin: 0px 0px -5px 0px"></li>
113 <li> (<font size="2" color="red">D</font>) loop: <img src="g_gui_gmodeler_loop.png" alt="loop" style="margin: 15px 0px -5px 0px"></li>
114 <li> (<font size="2" color="red">E</font>) database table: <img src="g_gui_gmodeler_db.png" alt="db" style="margin: 10px 0px -5px 0px"></li>
115 <li> (<font size="2" color="red">F</font>) 3D raster data: <img src="g_gui_gmodeler_raster3d.png" alt="raster3D" style="margin: 10px 0px -5px 0px"></li>
116 <li> (<font size="2" color="red">G</font>) vector data: <img src="g_gui_gmodeler_vector.png" alt="vector" style="margin: 10px 0px -5px 0px"></li>
117 <li> (<font size="2" color="red">H</font>) disabled GRASS module: <img src="g_gui_gmodeler_modulex.png" alt="module" style="margin: 10px 0px -5px 0px"></li>
118 <li> (<font size="2" color="red">I</font>) comment: <img src="g_gui_gmodeler_comment.png" alt="comment" style="margin: 10px 0px -5px 0px"></li>
119 </ul>
120
121 <center>
122 <a href="g_gui_gmodeler_model_classification.png">
123 <img src="g_gui_gmodeler_model_classification.png" width="500"></a>
124 <br>
125 <i>Figure: A model to perform unsupervised classification using MLC
126 (<a href="i.maxlik.html">i.maxlik</a>) and SMAP (<a href="i.smap.html">i.smap</a>).
127 </i>
128 </center>
129
130 <p>
131 Another example:
132
133 <center>
134 <a href="g_gui_gmodeler_model_usle.png">
135 <img src="g_gui_gmodeler_model_usle.png" width="600" height="284"></a>
136 <br>
137 <i>Figure: A model to perform estimation of average annual soil loss
138 caused by sheet and rill erosion using The Universal Soil Loss
139 Equation.</i>
140 </center>
141
142 <p>
143 Example as part of landslide prediction process:
144
145 <center>
146 <a href="g_gui_gmodeler_model_landslides.png">
147 <img src="g_gui_gmodeler_model_landslides.png" width="600" height="290"></a>
148 <br>
149 <i>Figure: A model to create parametric maps used by geologists
150 to predict landslides in the area of interest.</i>
151 </center>
152
153 <h2>EXAMPLE</h2>
154
155 In this example the <code>zipcodes_wake</code> vector data and the
156 <code>elev_state_500m</code> raster data from the North Carolina
157 sample dataset (original <a href="https://grass.osgeo.org/sampledata/north_carolina/nc_rast_geotiff.zip">raster</a> and
158 <a href="https://grass.osgeo.org/sampledata/north_carolina/nc_shape.zip">vector</a>
159 data) are used to calculate average elevation for every
160 zone. The important part of the process is the Graphical Modeler, namely its
161 possibilities of process automation.
162
163 <h3>The workflow shown as a series of commands</h3>
164
165 In the command console the procedure looks as follows:
166
167 <div class="code"><pre>
168 # input data import
169 r.import input=elev_state_500m.tif output=elevation
170 v.import input=zipcodes_wake.shp output=zipcodes_wake
171 # computation region settings
172 g.region vector=zipcodes_wake
173 # raster statistics (average values), upload to vector map table calculation
174 v.rast.stats -c map=zipcodes_wake raster=elevation column_prefix=rst method=average
175 # univariate statistics on selected table column for zipcode map calculation
176 v.db.univar map=zipcodes_wake column=rst_average
177 # conversion from vector to raster layer (due to result presentation)
178 v.to.rast input=zipcodes_wake output=zipcodes_avg use=attr attribute_column=rst_average
179 # display settings
180 r.colors -e map=zipcodes_avg color=bgyr
181 d.mon start=wx0 bgcolor=white
182 d.barscale style=arrow_ends color=black bgcolor=white fontsize=10
183 d.rast map=zipcodes_avg bgcolor=white
184 d.vect map=zipcodes_wake type=boundary color=black
185 d.northarrow style=1a at=85.0,15.0 color=black fill_color=black width=0 fontsize=10
186 d.legend raster=zipcodes_avg lines=50 thin=5 labelnum=5 color=black fontsize=10
187 </pre></div>
188
189 <h3>Defining the workflow in the Graphical Modeler</h3>
190
191 To start performing above steps as an automatic process with the Graphical Modeler
192 press the <img src="icons/modeler-main.png" alt="icon"> icon or
193 type <em>g.gui.gmodeler</em>. The simplest way of inserting elements
194 is by adding the complete GRASS command to the Command field in the GRASS command
195 dialog (see figure below). With full text search one can do faster
196 module hunting. Next, the label and the command can be added. In case that only
197 a module name is inserted, after pressing the <i>Enter</i> button, the
198 module dialog window is displayed and it is possible to set all of the usual
199 module options (parameters and flags).
200
201 <p>
202 <center>
203 <a href="g_gui_gmodeler_dlg_module.png"><img src="g_gui_gmodeler_dlg_module.png"
204 width="400"></a>
205 <br>
206 <i>Figure: Dialog for adding GRASS commands to model.</i>
207 </center>
208
209 <h3>Managing model parameters</h3>
210 All used modules can be parameterized in the model. That causes launching the
211 dialog with input options for model after the model is run. In this example,
212 input layers (<code>zipcodes_wake</code> vector map and <code>elev_state_500m</code>
213 raster map) are parameterized. Parameterized elements show their diagram border
214 slightly thicker than those of unparameterized elements.
215
216 <center>
217 <a href="g_gui_gmodeler_parameter.png">
218 <img src="g_gui_gmodeler_parameter.png" width="500"></a>
219 <br>
220 <i>Figure: Model parameter settings.</i>
221 </center>
222
223 <p>
224 The final model, the list of all model items, and the Script editor window with
225 <i>Save</i> and <i>Run</i> option are shown in the figures below.
226
227 <center>
228 <a href="g_gui_gmodeler_model_avg.png">
229 <img src="g_gui_gmodeler_model_avg.png" width="600" height="272"></a>
230 <br>
231 <i>Figure: A model to perform average statistics for zipcode zones.</i>
232 </center>
233 <br>
234 <center>
235 <a href="g_gui_gmodeler_items.png">
236 <img src="g_gui_gmodeler_items.png" width="600" height="330"></a>
237 <p>
238 <a href="g_gui_gmodeler_python.png">
239 <img src="g_gui_gmodeler_python.png" width="600" height="330"></a>
240 <br>
241 <i>Figure: Items with Script editor window.</i>
242 </center>
243
244 <p>
245 For convenience, this model for the Graphical Modeler is also available for download
246 <a href="g_gui_gmodeler_zipcodes_avg_elevation.gxm">here</a>.
247
248 <p>
249 The model is run by clicking the <i>Run</i> button
250 <img src="icons/execute.png" alt="run">. When all inputs are set, the results can
251 be displayed as shown in the next Figure:
252
253 <center>
254 <a href="g_gui_gmodeler_avg_run.png"><img src="g_gui_gmodeler_avg_run.png" width="500"></a>
255 <a href="g_gui_gmodeler_avg_map.png"><img src="g_gui_gmodeler_avg_map.png" width="300"></a>
256 <br>
257 <i>Figure: Average elevation for ZIP codes using North Carolina sample dataset as
258 an automatic calculation performed by Graphical Modeler.</i>
259 </center>
260
261 <h3>Managing model properties</h3>
262 When the user wants to run the model again with the same data or the same names, it is
263 necessary to use <code>--overwrite</code> option. It will cause maps with identical
264 names to be overwritten. Instead of setting it for every
265 module separately it is handy to change the Model Property settings globally.
266 This dialog includes also metadata settings, where model name, model description
267 and author(s) of the model can be specified.
268
269 <center>
270 <a href="g_gui_gmodeler_model_properties.png">
271 <img src="g_gui_gmodeler_model_properties.png" width="350"></a>
272 <br>
273 <i>Figure: Model properties.</i>
274 </center>
275
276 <h3>Defining variables</h3>
277
278 Another useful trick is the possibility to set variables. Their content can be used
279 as a substitute for other items. Value of variables can be values such as
280 raster or vector data, integer, float, string value or they may constitute some
281 region, mapset, file or direction data type.
282
283 Then it is not
284 necessary to set any parameters for input data. The dialog with variable settings
285 is automatically displayed after the model is run. So, instead of model parameters
286 (e.g. <code>r.import</code> a <code>v.import</code>, see the Figure
287 <em><a href="g_gui_gmodeler_avg_run.png">Run model dialog</a></em> above)
288 there are <code>Variables</code>.
289
290 <center>
291 <a href="g_gui_gmodeler_variables_run.png">
292 <img src="g_gui_gmodeler_variables_run.png" width="500"></a>
293 <br>
294 <i>Figure: Model with variable inputs.</i>
295 </center>
296
297 <p>
298 The key point is enclosing the substituting variable into <code>%{...}</code> and setting
299 the value in the <code>Variables</code> dialog. For example, in the case of a model
300 variable <code>raster</code> that points to an input file path and which value is
301 required to be used as one of inputs for a particular model, it should be specified in
302 the <code>Variables</code> dialog with its respective name (<code>raster</code>), data
303 type, default value and description. Then it should be set in the module dialog as
304 input called <code>%{raster}</code>.
305
306 <center>
307 <a href="g_gui_gmodeler_variables.png">
308 <img src="g_gui_gmodeler_variables.png" width="600" height="330"></a>
309 <br>
310 <i>Figure: Example of raster file variable settings.</i>
311 </center>
312
313 <br>
314 <center>
315 <a href="g_gui_gmodeler_variables_raster.png">
316 <img src="g_gui_gmodeler_variables_raster.png" width="600" height="257"></a>
317 <br>
318 <i>Figure: Example of raster file variable usage.</i>
319 </center>
320
321 <h3>Saving the model file</h3>
322 Finally, the model settings can be stored as a GRASS Model file with
323 <code>*.gxm</code> extension. The advantage is that it can be shared as a
324 reusable workflow that may be run also by other users with different data.
325
326 <p>
327 <!-- TODO: next line, which model? -->
328 For example, this model can later be used to calculate the average precipitation
329 for every administrative region in Slovakia using the <code>precip</code> raster data from
330 <a href="https://grass.osgeo.org/sampledata/slovakia3d_grass7.tar.gz">
331 Slovakia precipitation dataset</a> and administration boundaries of Slovakia from
332 <a href="https://www.geoportal.sk/sk/zbgis_smd/na-stiahnutie/">Slovak Geoportal</a>
333 (only with a few clicks).
334
335 <h3>Handling intermediate data</h3>
336 There can be some data in a model that did not exist before the process and
337 that it is not worth it to maintain after the process executes. They can
338 be described as being <code>Intermediate</code> by single clicking using the right
339 mouse button, see figure below. All such data should be deleted following
340 model completion. The boundary of intermediate component is dotted line.
341
342 <center>
343 <a href="g_gui_gmodeler_intermediate_data.png">
344 <img src="g_gui_gmodeler_intermediate_data.png" width="400"></a>
345 <br>
346 <i>Figure: Usage and definition of intermediate data in model.</i>
347 </center>
348
349 <h3>Using the Script editor</h3>
350 By using the Script editor in the Graphical Modeler, the user can add Python code and then
351 run it with <i>Run</i> button or just save it as a Python script <code>*.py</code>.
352 The result is shown in the Figure below:
353
354 <center>
355 <a href="g_gui_gmodeler_python_code.png">
356 <img src="g_gui_gmodeler_python_code.png" height="500"></a>
357 <a href="g_gui_gmodeler_python_code_result.png">
358 <img src="g_gui_gmodeler_python_code_result.png" height="500"></a>
359 <br>
360 <i>Figure: Script editor in the wxGUI Graphical Modeler.</i>
361 </center>
362
363 The second option in the <i>Script type</i> combobox exports a PyWPS script
364 instead of a basic Python one. A PyWPS process based on the model will be
365 generated then; for the PyWPS script, the <i>Run</i> button is disabled as
366 users are expected to include this script in their web processing service and
367 not to run it on itself.
368
369 <center>
370 <a href="g_gui_gmodeler_pywps_code.png">
371 <img src="g_gui_gmodeler_pywps_code.png" width="500"></a>
372 <br>
373 <i>Figure: Script editor in the wxGUI Graphical Modeler - set to PyWPS.</i>
374 </center>
375
376 The third option in the <i>Script type</i> combobox exports an actinia process
377 chain (non-parameterized model) or an actinia template (parameterized model).
378 An actinia JSON based on the model will be generated then; as for the PyWPS
379 script, the <i>Run</i> button is disabled as users are expected to include this
380 JSON in their web processing service and not to run it on itself.
381
382 <center>
383 <a href="g_gui_gmodeler_actinia_code.png">
384 <img src="g_gui_gmodeler_actinia_code.png" width="500"></a>
385 <br>
386 <i>Figure: Script editor in the wxGUI Graphical Modeler - set to actinia.</i>
387 </center>
388
389 <p>
390 By default GRASS script package API is used
391 (<code>grass.script.core.run_command()</code>). This can be changed in the
392 settings. Alternatively also PyGRASS API is supported
393 (<code>grass.pygrass.modules.Module</code>).
394
395 <h3>Defining loops</h3>
396 In the example below the <a href="https://e4ftl01.cr.usgs.gov/MOLT/MOD13Q1.006/">MODIS MOD13Q1</a>
397 (NDVI) satellite data products are used in a loop. The original data are
398 stored as coded integer values that need to be multiplied by the
399 value <code>0.0001</code> to represent real <i>ndvi values</i>. Moreover, GRASS
400 provides a predefined color table called <code>ndvi</code> to represent <i>ndvi data</i>.
401 In this case it is not necessary to work with every image separately.
402 <br>
403 The Graphical Modeler is an appropriate tool to
404 process data in an effective way using loop and variables (<code>%{map}</code> for a
405 particular MODIS image in mapset and <code>%{ndvi}</code> for original data name suffix).
406 After the loop component is added to model, it is necessary to define series of maps
407 with required settings of map type, mapset, etc.
408
409 <center>
410 <a href="g_gui_gmodeler_loop_dlg.png">
411 <img src="g_gui_gmodeler_loop_dlg.png" width="300"></a>
412 <br>
413 <i>Figure: MODIS data representation in GRASS after Graphical Modeler usage.</i>
414 </center>
415
416 <p>
417 When the model is supplemented by all of modules, these modules should be
418 ticked in the boxes of loop dialog. The final model and its results are shown below.
419
420 <center>
421 <a href="g_gui_gmodeler_loop_final.png">
422 <img src="g_gui_gmodeler_loop_final.png" width="400"></a>
423 <br>
424 <i>Figure: Model with loop.</i>
425 </center>
426
427 <p>
428 <center>
429 <a href="g_gui_gmodeler_modis_1o.png">
430 <img src="g_gui_gmodeler_modis_1o.png" width="300"></a>
431 <a href="g_gui_gmodeler_modis_1.png">
432 <img src="g_gui_gmodeler_modis_1.png" width="300"></a>
433 <a href="g_gui_gmodeler_modis_2o.png">
434 <img src="g_gui_gmodeler_modis_2o.png" width="300"></a><br>
435 <a href="g_gui_gmodeler_modis_2.png">
436 <img src="g_gui_gmodeler_modis_2.png" width="300"></a>
437 <a href="g_gui_gmodeler_modis_3o.png">
438 <img src="g_gui_gmodeler_modis_3o.png" width="300"></a>
439 <a href="g_gui_gmodeler_modis_3.png">
440 <img src="g_gui_gmodeler_modis_3.png" width="300"></a>
441 <br>
442 <i>Figure: MODIS data representation in GRASS after Graphical Modeler usage.</i>
443 </center>
444
445 <p>
446 The steps to enter in the command console of the Graphical Modeler would be as follows:
447
448 <!-- TODO: WHY does the white space usage differ?? -->
449 <div class="code"><pre>
450 # note that the white space usage differs from the standard command line usage
451
452 # rename original image with preselected suffix
453 g.rename raster = %{map},%{map}.%{ndvi}
454 # convert integer values
455 r.mapcalc expression = %{map} = %{map}.%{ndvi} * 0.0001
456 # set color table appropriate for nvdi data
457 r.colors = map = %{map} color = ndvi
458 </pre></div>
459
460 <h2>SEE ALSO</h2>
461
462 <em>
463 <a href="wxGUI.html">wxGUI</a>,
464 <a href="wxGUI.components.html">wxGUI components</a>
465 </em>
466
467 <p>
468 See also selected user models available from
469 <a href="https://grass.osgeo.org/grass8/manuals/addons/">GRASS Addons repository</a>.
470
471 <p>
472 See also
473 the <a href="https://grasswiki.osgeo.org/wiki/WxGUI_Graphical_Modeler">wiki</a> page
474 (especially various <a href="https://grasswiki.osgeo.org/wiki/WxGUI_Graphical_Modeler#Video_tutorials">video
475 tutorials</a>).
476
477 <h2>AUTHORS</h2>
478
479 Martin Landa, GeoForAll Lab, Czech Technical University in Prague, Czech Republic<br>
480 PyWPS support by Ondrej Pesek, GeoForAll Lab, Czech Technical University in Prague, Czech Republic<br>
481 Various manual improvements by Ludmila Furkevicova, Slovak University of Technology in Bratislava, Slovak Republic