r.infer(1)		      Grass User's Manual		    r.infer(1)



NNAAMMEE
       rr..iinnffeerr	 -  Outputs a raster map layer whose category values represent
       the application of user-specified criteria (rules statements) to  other
       raster map layers' category values.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..iinnffeerr
       rr..iinnffeerr hheellpp
       rr..iinnffeerr [--vvtt] rruulleessffiillee==_n_a_m_e

DDEESSCCRRIIPPTTIIOONN
       _r_._i_n_f_e_r	is  an	inference engine which applies a set of user-specified
       rules to named raster map layers.  A new raster map layer  named  _i_n_f_e_r
       is created as output, whose category values reflect the ability of each
       cell in the named input layers to satisfy the named conditions.


       _r_._i_n_f_e_r commands (conditions and consequences) are typed into a file by
       the  user  using  a system editor like _v_i, and then input to _r_._i_n_f_e_r as
       the _r_u_l_e_s_f_i_l_e named on the command line.  The results are used to  gen-
       erate  a new raster map layer named _i_n_f_e_r in the user's current mapset.
       This program performs analyses similar to _r_._c_o_m_b_i_n_e, but uses a (possi-
       bly) more pleasing syntax and approach.

OOPPTTIIOONNSS
       The  program  will  be  run non-interactively if the user specifies the
       name of a rules file and any desired flags on the command  line,  using
       the form: rr..iinnffeerr [--vvtt] rruulleessffiillee==_n_a_m_e

       where _n_a_m_e is the name of an ASCII file containing valid input rules to
       _r_._i_n_f_e_r, and the (optional) flags _-_v and _-_t have the meanings described
       in the OPTIONS section, below.


       Alternately,  the  user	can  simply  type rr..iinnffeerr on the command line,
       without program arguments.  In this case, the user will be prompted for
       the  needed  parameter value and flag settings using the standard GRASS
       parser interface.

   FFllaaggss::
       --tt     Allows the user to run _r_._i_n_f_e_r in _t_e_s_t mode.  The user is  ques-
	      tioned  about  the  truth  of  each condition named in the file.
	      _r_._i_n_f_e_r then outputs the value that would be placed in  the  new
	      layer _i_n_f_e_r for a cell meeting conditions specified by the user.
	      When no sets of conditions stated in the input file  are	satis-
	      fied  (based  upon  the user's answers), cell values of zero are
	      output.  Test mode is used to test the accuracy  of  the	user's
	      logic.   Users  are encouraged to run _r_._i_n_f_e_r in test mode prior
	      to actually creating map layers.

       --vv     Makes _r_._i_n_f_e_r run _v_e_r_b_o_s_e_l_y, giving information about each  cell
	      as it is analyzed according to the statement conditions.


   PPaarraammeetteerrss::
       rruulleessffiillee==_n_a_m_e
	      Allows  the  user  to input rules to _r_._i_n_f_e_r from an ASCII file,
	      rather than from standard input.	This rulesfile must  exist  in
	      the  user's  current  working  directory or be given by its full
	      pathname.  File rules statements take the  same  form  as  those
	      given  on  the command line.  Examples of valid rules statements
	      are given in the sections below.


CCOOMMMMAANNDDSS AANNDD SSTTAATTEEMMEENNTTSS
       The following commands are available in _r_._i_n_f_e_r_:

       COMMANDS AND STATEMENTS
       The following commands are available in r.infer:
	Command   |  Aliases  |   Followed By	    |	    Such As
       -----------+-----------+---------------------+----------------------
       IFMAP	  | ANDIFMAP  | cellmap cat#	    | geology 2
		  | ANDMAP    | 		    |
       -----------+-----------+---------------------+----------------------
       IFNOTMAP   | ANDNOTMAP | cellmap cat#	    | geology 2
       -----------+-----------+---------------------+----------------------
       THENMAPHYP |	      | cat# [statement]    | 3 nice vacation spot
       -----------+-----------+---------------------+----------------------
       THEN	  |	      | statement	    | No sandstone
		  |	      | condition	    |
       -----------+-----------+---------------------+----------------------
       IF	  | AND       | predefined	    | No sandstone
	       | ANDIF	   | statement condition |


       These five commands may be used to formulate statements with  functions
       ranging	from a simple reclassification to a more complex expert system
       type application.  Statements are composed of one  or  more  ccoonnddiittiioonnss
       followed  by  one  or  more  hhyyppootthheesseess and/or ccoonncclluussiioonnss.  The use of
       aliases is provided to allow for the use of  a  command	which  has  an
       English meaning consistent with the logic at that point.


       Following  is a description of each of the five commands.  The map lay-
       ers used in the examples are in the Spearfish sample data base.



       IIFFMMAAPP Map condition


       Map conditions are questions to each cell about the presence of	speci-
       fied  map  layer  category  values.  _r_._i_n_f_e_r questions each cell in the
       named map layer (here, _g_e_o_l_o_g_y)	about  its  contents  (i.e.,  category
       value).	 Cells	which  satisfy	the named condition(s) stated by IFMAP
       (i.e., here, those cells which contain _g_e_o_l_o_g_y map layer category  val-
       ues  4 or 5) will be assigned the subsequently-stated map conclusion or
       hypothesis (category), in the new map layer _i_n_f_e_r.  Cells which fail to
       satisfy	named  map condition(s) will continue to move down through the
       user's _r_u_l_e_s_f_i_l_e (searching for conditions it is able  to  satisfy)  if
       any  additional	conclusions/hypotheses are stated in the file, or will
       be assigned category zero in the new map layer _i_n_f_e_r (if no  additional
       conclusions/hypotheses are possible in this _r_u_l_e_s_f_i_l_e).


       example:  IIFFMMAAPP ggeeoollooggyy 44 55



       IIFFNNOOTTMMAAPP Map condition


       Like IFMAP, but instead questions each cell about the _a_b_s_e_n_c_e of speci-
       fied map layer categories.  Cells which meet  the  IFNOTMAP  conditions
       (i.e., below, those cells which do NOT include owner map layer category
       value 2) will be assigned the named conclusionothesis, in the  new  map
       layer _i_n_f_e_r.


       example: IIFFNNOOTTMMAAPP oowwnneerr 22


       TTHHEENNMMAAPPHHYYPP Map conclusion


       Assigns each cell a specified category value in the new map layer _i_n_f_e_r
       based on the cell's ability or failure to meet conditions  named  above
       this  THENMAPHYP statement in the _r_u_l_e_s_f_i_l_e.  The user should note that
       although the user  can  specify	a  uniquely-named  _r_u_l_e_s_f_i_l_e,  _r_._i_n_f_e_r
       always  directs	its output to a file named _i_n_f_e_r in the current mapset
       (overwriting whatever is currently in this file).   Therefore,  if  the
       user  wishes  to  save  this  file  for future use, this file should be
       renamed before the user next runs _r_._i_n_f_e_r (e.g., using the  GRASS  com-
       mand _g_._r_e_n_a_m_e).


       It  is  important  to  realize that _r_._i_n_f_e_r runs through the conditions
       stated in the named _r_u_l_e_s_f_i_l_e one cell at a time, moving from  the  top
       of  the	raster	input file to the bottom of the raster input file.  As
       soon as the cell currently being examined by _r_._i_n_f_e_r satisfies a set of
       conditions, it is assigned a category value in the new map layer _i_n_f_e_r.
       _r_._i_n_f_e_r does NOT check to see if that same cell satisfies other	condi-
       tions  named further down in the input file, too.  Instead, it moves on
       to the next cell, and begins anew with the conditions named at the  top
       of  the	input  file.   Essentially,  this  means that conclusions made
       higher-up in the input file have precedence over conditions named  fur-
       ther down in the input file.


       example:

	IIFFMMAAPP ddeennssiittyy 11
       TTHHEENNMMAAPPHHYYPP 11 nnoo ttrreeeess


       In  the above example, all cells having a category value of _1 (non-for-
       est) in the map layer _d_e_n_s_i_t_y, are assigned a category value  of  _1  in
       the resultant map layer _i_n_f_e_r.  The trailing text "no trees" is entered
       into the category support file for category 1  in  the  new  map  layer
       _i_n_f_e_r.



       TTHHEENN Statement hypothesis


       At  the	conclusion  of one or several condition statements, instead of
       making a map conclusion as with THENMAPHYP, the conditions are used  to
       create  a  hypothesis.  This may then be referenced in later statements
       using the IF command.  The trailing text at the end of the THEN	state-
       ment  is  used as the means with which to reference the hypothesis.  An
       example follows the description of IF below.



       IIFF Statement condition.


       States a condition based on an hypothesis that was created by a	previ-
       ous  THEN  statement.   IF may be used only after a THEN has set up the
       group of statements that are to be referenced later.


       example:


       IIFFMMAAPP eelleevvaattiioonn..225555 117700--225555
       AANNDDIIFFMMAAPP ddeennssiittyy 33 44
       TTHHEENN hhiigghh eelleevvaattiioonn wwiitthh ttrreeeess
       !!
       IIFF hhiigghh eelleevvaattiioonn wwiitthh ttrreeeess
       AANNDDIIFFMMAAPP oowwnneerr 22
       TTHHEENNMMAAPPHHYYPP 11 tthhiiss iiss tthhee ppllaaccee


       The above example queries each cell for the presence of _b_o_t_h elevations
       greater	than  1580  meters  (i.e.,  for  _e_l_e_v_a_t_i_o_n_._2_5_5 category values
       170-255) and a medium to high density of trees (i.e., density  category
       values  3  4).  All areas (i.e., cells) that satisfy these criteria are
       assigned to the hypothesis "high elevation with trees." The "!"	simply
       tells _r_._i_n_f_e_r to ignore whatever appears on that line (a comment state-
       ment), and is used here for readability.


       The IF statement then references  cells	having	"high  elevation  with
       trees"  (i.e.,  those cells that satisfied both of the above conditions
       named by the IFMAP and ANDIFMAP statements).  If a cell _b_o_t_h has  "high
       elevations  with  trees" and _o_w_n_e_r map layer category 2 (areas owned by
       the Forest Service), it is assigned by the THENMAPHYP statement to cat-
       egory  1  in  the  new map layer _i_n_f_e_r.	The trailing text "this is the
       place" is automatically entered into the category support file for  the
       new  map  _i_n_f_e_r.  Cells failing to meet all of the conditions stated in
       this input file will be assigned category 0 in the new map layer _i_n_f_e_r.

SSEEEE AALLSSOO
       _g_._r_e_n_a_m_e, _r_._c_o_m_b_i_n_e, _r_._m_a_p_c_a_l_c, _r_._w_e_i_g_h_t, and _p_a_r_s_e_r

AAUUTTHHOORR
       James Westervelt, U.S.Army Construction Engineering Research Laboratory


       Special recognition goes to:


       George W. Hageman

       SOFTMAN Enterprises

       P.O. Box 11234

       Boulder, Colorado  80301


       Daniel S. Cox

       In Touch

       796 West Peachtree St. NE

       Atlanta, GA 30308


       Mr. Hageman, in the spring of 1986, submitted an  inference  engine  to
       the  UNIX network.  Mr. Cox reworked the code submitting an new version
       shortly thereafter.  It is this code that forms the guts of _r_._i_n_f_e_r.

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0							    r.infer(1)
