Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
g.gui.gmodeler(1)	    GRASS GIS User's Manual	     g.gui.gmodeler(1)

       g.gui.gmodeler  - Graphical Modeler.
       Allows interactively creating, editing and managing models.

       general,	GUI, graphical modeler,	workflow

       g.gui.gmodeler --help
       g.gui.gmodeler	 [file=name.gxm]    [--help]   [--verbose]   [--quiet]

	   Print usage summary

	   Verbose module output

	   Quiet module	output

	   Force launching GUI dialog

	   Name	of model file to be loaded

       The Graphical Modeler is	a wxGUI	component which	 allows	 the  user  to
       create, edit, and manage	simple and complex models using	an easy-to-use
       interface.  When	performing analytical operations in GRASS GIS, the op-
       erations	are not	isolated, but part of a	chain of operations. Using the
       Graphical Modeler, a chain of processes (i.e. GRASS GIS modules)	can be
       wrapped into one	process	(i.e. model). Subsequently it is easier	to ex-
       ecute the model later on	even with slightly different inputs or parame-
       Models  represent a programming technique used in GRASS GIS to concate-
       nate single steps together to accomplish	a  task.  It  is  advantageous
       when  the user see boxes	and ovals that are connected by	lines and rep-
       resent some tasks rather	than seeing lines of coded text. The Graphical
       Modeler	can be used as a custom	tool that automates a process. Created
       models can simplify or shorten a	task which can be run many  times  and
       it  can	also  be  easily shared	with others. Important to note is that
       models cannot perform specified tasks that  one	cannot	also  manually
       perform	with  GRASS  GIS.  It  is  recommended to first	to develop the
       process manually, note down the steps (e.g. by using the	Copy button in
       module dialogs) and later replicate them	in model.

       The Graphical Modeler allows you	to:

	   o   define data items (raster, vector, 3D raster maps)

	   o   define actions (GRASS commands)

	   o   define relations	between	data and action	items

	   o   define  loops  (e.g. map	series)	and conditions (if-else	state-

	   o   define model variables

	   o   parameterize GRASS commands

	   o   define intermediate data

	   o   validate	and run	model

	   o   save model properties to	a file (GRASS Model File|*.gxm)

	   o   export model to Python script

	   o   export model to image file

   Main	dialog
       The Graphical Modeler can be launched from the Layer Manager menu  File
       ->  Graphical modeler or	from the main toolbar .	It's also available as
       stand-alone module g.gui.gmodeler.

       The main	Graphical Modeler menu contains	options	which enable the  user
       to  fully  control the model. Directly under the	main menu one can find
       toolbar with buttons (see figure	below).	There  are  options  including
       (1)  Create new model, (2) Load model from file,	(3) Save current model
       to file,	(4) Export model to image, (5) Export model to Python  script,
       (6) Add command (GRASS modul) to	model, (7) Add data to model, (8) Man-
       ually define relation between data and commands,	(9) Add	loop/series to
       model,  (10) Add	comment	to model, (11) Redraw model canvas, (12) Vali-
       date model, (13)	Run model, (14)	Manage	model  variables,  (15)	 Model
       settings, (16) Show manual, (17)	Quit Graphical Modeler.

       Figure: Components of Graphical Modeler menu toolbar.

       There  is  also	a lower	menu bar in the	Graphical modeler dialog where
       one can manage model items, visualize commands,	add  or	 manage	 model
       variables,  define  default  values and descriptions. The Python	editor
       dialog window allows seeing  workflows  written	in  Python  code.  The
       rightmost  tab  of  the bottom menu is automatically triggered when the
       model is	activated and shows all	the steps  of  running	GRASS  modeler
       modules.	In case	of errors in the calculation process, it is written at
       that place.
       Figure: Lower Graphical Modeler menu toolbar.

   Components of models
       The workflow is usually established from	four types of diagrams.	 Input
       and derived model data are usually represented with oval	diagrams. This
       type of model elements stores path to specific data on the user's disk.
       It  is  possible	 to  insert vector data, raster	data, database tables,
       etc.  The type of data is clearly distinguishable in the	model  by  its
       color.  Different model elements	are shown in the figures below.

	   o   (A) raster data:

	   o   (B) relation:

	   o   (C) GRASS module:

	   o   (D) loop:

	   o   (E) database table:

	   o   (F) 3D raster data:

	   o   (G) vector data:

	   o   (H) disabled GRASS module:

	   o   (I) comment:
       Figure:	A  model  to  perform  unsupervised  classification  using MLC
       (i.maxlik) and SMAP (i.smap).

       Another example:
       Figure: A model to perform  estimation  of  average  annual  soil  loss
       caused  by  sheet  and rill erosion using The Universal Soil Loss Equa-

       Example as part of landslide prediction process:
       Figure: A model to perform creation of parametric maps used  by	geolo-
       gists to	predict	landslides in the area of interest.

       In  this	 example the zipcodes_wake vector data and the elev_state_500m
       raster data from	the North Carolina sample dataset (original raster and
       vector  data)  are  used	to calculate average elevation for every zone.
       The important part of the process is the	Graphical Modeler, namely  its
       possibilities of	process	automation.

   The workflow	shown as a series of commands
       In the command console the procedure looks as follows:
       # input data import
       r.import	input=elev_state_500m.tif output=elevation
       v.import	input=zipcodes_wake.shp	output=zipcodes_wake
       # computation region settings
       g.region	vector=zipcodes_wake
       # raster	statistics (average values), upload to vector map table	calculation
       v.rast.stats -c map=zipcodes_wake raster=elevation column_prefix=rst method=average
       # univariate statistics on selected table column	for zipcode map	calculation
       v.db.univar map=zipcodes_wake column=rst_average
       # conversion from vector	to raster layer	(due to	result presentation) input=zipcodes_wake output=zipcodes_avg use=attr attribute_column=rst_average
       # display settings
       r.colors	-e map=zipcodes_avg color=bgyr
       d.mon start=wx0 bgcolor=white
       d.barscale style=arrow_ends color=black bgcolor=white fontsize=10
       d.rast map=zipcodes_avg bgcolor=white
       d.vect map=zipcodes_wake	type=boundary color=black
       d.northarrow style=1a at=85.0,15.0 color=black fill_color=black width=0 fontsize=10
       d.legend	raster=zipcodes_avg lines=50 thin=5 labelnum=5 color=black fontsize=10

   Defining the	workflow in the	Graphical Modeler
       To start	performing above steps as an automatic process with the	Graph-
       ical Modeler press the  icon or type g.gui.gmodeler. The	 simplest  way
       of  inserting  elements	is by adding the complete GRASS	command	to the
       Command field in	the GRASS command dialog  (see	figure	below).	  With
       full  text search one can do faster module hunting. Next, the label and
       the command can be added. In case that only a module name is  inserted,
       after  pressing the Enter button, the module dialog window is displayed
       and it is possible to set all of	the usual module  options  (parameters
       and flags).

       Figure: Dialog for adding GRASS commands	to model.

   Managing model parameters
       All used	modules	can be parameterized in	the model. That	causes launch-
       ing the dialog with input options for model after the model is run.  In
       this    example,	  input	  layers   (zipcodes_wake   vector   map   and
       elev_state_500m raster map) are parameterized.  Parameterized  elements
       show  their  diagram border slightly thicker than those of unparameter-
       ized elements.
       Figure: Model parameter settings.

       The final model,	the list of all	model items, and the Python code  win-
       dow with	Save and Run option are	shown in the figures below.
       Figure: A model to perform average statistics for zipcode zones.

       Figure: Items with Python editor	window.

       For convenience,	this model for the Graphical Modeler is	also available
       for download here.

       The model is run	by clicking the	Run button . When all inputs are  set,
       the results can be displayed as shown in	the next Figure:
       Figure:	Average	 elevation  for	 ZIP codes using North Carolina	sample
       dataset as an automatic calculation performed by	Graphical Modeler.

   Managing model properties
       When one	wants to run model again with the same data or the same	names,
       it  is  necessary  to  use  --overwrite option. It will cause maps with
       identical names to be overwritten. Instead of setting it	for every mod-
       ule  separately it is handy to change the Model Property	settings glob-
       ally.  This dialog includes also	metadata settings, where  model	 name,
       model description and author(s) of the model can	be specified.
       Figure: Model properties.

   Defining variables
       Another useful trick is the possibility to set variables. Their content
       can be used as a	substitute for other items. Value of variables can  be
       values  such  as	raster or vector data, integer,	float, string value or
       they may	constitute some	region,	mapset,	file or	direction  data	 type.
       Then it is not necessary	to set any parameters for input	data. The dia-
       log with	variable settings is automatically displayed  after  model  is
       run. So,	instead	of model parameters (e.g. r.import a v.import, see the
       Figure Run model	dialog above) there are	Variables.
       Figure: Model with variable inputs.

       The key point is	the usage of % before the  substituting	 variable  and
       settings	 in Variables dialog. For example, in case of a	model variable
       raster that points to an	input file path	and which value	is required to
       be used as one of inputs	for a particular model,	it should be specified
       in the Variables	dialog with its	respective name	(raster),  data	 type,
       default value and description. Then it should be	set in the module dia-
       log as input called %raster.
       Figure: Example of raster file variable settings.
       Figure: Example of raster file variable usage.

   Saving the model file
       Finally,	the model settings can be stored as a  GRASS  GIS  Model  file
       with *.gxm extension. The advantage is that it can be shared as a reus-
       able workflow that may be run also by other users with different	data.

       For example, this model can later be used to calculate the average pre-
       cipitation for every administrative region in Slovakia using the	precip
       raster data from	 Slovakia  precipitation  dataset  and	administration
       boundaries of Slovakia from Slovak Geoportal (only with a few clicks).

   Handling intermediate data
       There can be some data in a model that did not exist before the process
       and that	it is not worth	it to maintain	after  the  process  executes.
       They  can  be  described	as being Intermediate by single	clicking using
       the right mouse button, see figure  below.  All	such  data  should  be
       deleted following model completion. The boundary	of intermediate	compo-
       nent is dotted line.
       Figure: Usage and definition of intermediate data in model.

   Using the Python editor
       By using	the Python editor in the Graphical Modeler one can add	Python
       code and	then run it with Run button or just save it as a Python	script
       *.py.  The result is shown in the Figure	below:
       Figure: Python editor in	the wxGUI Graphical Modeler.

   Defining loops
       In the example below the	MODIS MOD13Q1 (NDVI) satellite	data  products
       are  used in a loop. The	original data are stored as coded integer val-
       ues that	need to	be multiplied by the value 0.0001  to  represent  real
       ndvi  values.  Moreover,	 GRASS	GIS  provides a	predefined color table
       called ndvi to represent	ndvi data.  In this case it is	not  necessary
       to work with every image	separately.
       The  Graphical Modeler is an appropriate	tool to	process	data in	an ef-
       fective way using loop and variables (%map for a	particular MODIS image
       in  mapset  and	%ndvi  for original data name suffix).	After the loop
       component is added to model, it is necessary to define series  of  maps
       with required settings of map type, mapset, etc.
       Figure:	MODIS data representation in GRASS GIS after Graphical Modeler

       When the	model is supplemented by all of	modules, these modules	should
       be  ticked in the boxes of loop dialog. The final model and its results
       are shown below.
       Figure: Model with loop.

       Figure: MODIS data representation in GRASS GIS after Graphical  Modeler

       The  steps  to  enter  in  the command console of the Graphical Modeler
       would be	as follows:
       # note that the white space usage differs from the standard command line	usage
       # rename	original image with preselected	suffix
       g.rename	raster = %map,%map.%ndvi
       # convert integer values
       r.mapcalc expression = %map = %map.%ndvi	* 0.0001
       # set color table appropriate for nvdi data
       r.colors	= map =	%map color = ndvi

       wxGUI components

       See also	selected user models available from this git repository.

       See also	the wiki page (especially various video	tutorials).

       Martin Landa, OSGeoREL, Czech Technical University in Prague, Czech Re-
       Various	manual	improvements by	Ludmila	Furkevicova, Slovak University
       of Technology in	Bratislava, Slovak Republic

       Available at: wxGUI Graphical Modeler source code (history)

       Main index | GUI	index |	Topics index | Keywords	index |	Graphical  in-
       dex | Full index

       A(C) 2003-2020 GRASS Development	Team, GRASS GIS	7.8.4 Reference	Manual

GRASS 7.8.4						     g.gui.gmodeler(1)


Want to link to this manual page? Use this URL:

home | help