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



NNAAMMEE
       rr..iinnffeerr	 - Outputs a raster map layer whose category val-
       ues 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  com-
       mand  line.  The results are used to generate 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
       (possibly) 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]  rruulleess--
       ffiillee==_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  com-
       mand  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 questioned about the truth of  each  condi-
	      tion  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	satisfied  (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 sand-
       stone
		  |	      | condition	    |
       -----------+-----------+---------------------+----------------------
       IF	   |  AND	 | predefined	       | No sand-
       stone
	       | 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  layers used in the examples are in the Spearfish
       sample data base.



       IIFFMMAAPP Map condition


       Map conditions are questions to each cell about the  pres-
       ence  of  specified  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
       values 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 condi-
       tion(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  specified  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  command
       _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 cur-
       rently being examined by _r_._i_n_f_e_r satisfies a set of condi-
       tions, 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 conditions 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 con-
       ditions named further 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-forest) 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 sup-
       port 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 statement 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 previous 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	statement),  and is used here for
       readability.


       The IF statement then references cells having "high eleva-
       tion 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 state-
       ment to category 1 in the new map layer _i_n_f_e_r.  The trail-
       ing 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)
