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



NNAAMMEE
       rr..bbiinnffeerr  - Bayesian expert system development program.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..bbiinnffeerr
       rr..bbiinnffeerr hheellpp
       rr..bbiinnffeerr [--vv] iinnppuutt==_n_a_m_e [oouuttppuutt==_n_a_m_e]

DDEESSCCRRIIPPTTIIOONN
       _r_._b_i_n_f_e_r is an expert system shell containing an inference engine based
       on  Bayesian  statistics  (reasoning  from  past  experience).	It  is
       designed to assist human experts in a field develop computerized expert
       systems for land use planning and management. These expert systems  are
       designed to aid non-experts make decisions about land use.


       In  Bayesian expert system programs like _r_._b_i_n_f_e_r, the system bases the
       probable impacts of a future land use action on the conditional	proba-
       bilities about the impact of similar past actions.

OOPPTTIIOONNSS
   FFllaagg::
       --vv     Run  verbosely, displaying messages on debugging output to stan-
	      dard output.  Includes a listing of the  symbol  table  used  by
	      _r_._b_i_n_f_e_r.




   PPaarraammeetteerrss::
       iinnppuutt==_n_a_m_e
	      Name of an existing file containing analysis instructions.

       oouuttppuutt==_n_a_m_e
	      Name to be assigned to the file to contain program output.
	      Default: _b_i_n_f_e_r_._o_u_t



       Using appropriate _r_._b_i_n_f_e_r syntax, the human expert structures an input
       knowledge/control script with an appropriate combination of  map  layer
       category values (GRASS raster map layers that contain data on soil tex-
       ture, slope, density, etc.) and attributes relevant to  decision-making
       (e.g.,  rainfall,  temperature,	season,  subjective  judgement, etc.).
       Options exist for specifying a user interface and a data base  contain-
       ing prior and conditional probabilities necessary to infer the value of
       a goal attribute.  The expert also specifies the format for display  of
       end  results  (raster  map layers) in the input script.	New raster map
       layers -- one for each possible inferred attribute value -- are created
       that  contain the probability of the inferred attribute value occurring
       in each grid cell.


       Alternately, a single new map layer called _r_._b_i_n_f_e_r (or whatever _o_u_t_p_u_t
       name  is  specified  by	the user) is also output.  This map shows, for
       each grid cell, the inferred attribute value that has the highest prob-
       ability	of  occurring in each grid cell, given the values of the _i_n_p_u_t
       raster map layer and contextual attributes.


       _r_._b_i_n_f_e_r scripts are typed into a file by the user using a system  edi-
       tor  like _v_i, and then input to _r_._b_i_n_f_e_r as the _i_n_p_u_t file named on the
       command line.  For a complete description of the _i_n_p_u_t syntax, see  the
       document  GRASS Tutorial: r.binfer (forthcoming).  For example _r_._b_i_n_f_e_r
       scripts see the EXAMPLES section below.	The results are used to gener-
       ate the new raster map layers in the user's current mapset.


       As  stated above, _r_._b_i_n_f_e_r scripts contain descriptions of two types of
       input attributes. The map layer type attributes are actual GRASS raster
       map  layers,  with  the	values	defined to be ranges of the categories
       within that raster map layer.  For example, if the user	chooses  slope
       as  one	of  the  layer	attributes,  the possible values for the slope
       attribute might be the following:

       flat	    (slopes between 0 and 5 degrees)
       low	    (slopes between 6 and 10 degrees)
       medium	    (slopes between 11 and 30 degrees)
       steep	    (slopes greater than 31 degrees)

       The contextual attributes are those that do not	represent  raster  map
       layers,	but rather, information that reflects criteria relevant to the
       specific decision being contemplated.  For example, if the user chooses
       "rainfall  amount" as one of the contextual attributes, possible values
       assigned to the "rainfall amount" attribute might be the following:

       low	    (rainfall amounts less than an inch)
       medium	    (rainfall amounts between one and three inches)
       high	    (rainfall amounts grater than three inches)

       The inferred attribute values are specified along with a  prior	proba-
       bility and a table of conditional probabilities that indicate the prob-
       ability of that inferred attribute value occurring given that an  input
       attribute value has occurred.


       _r_._b_i_n_f_e_r will determine the value of contextual attributes by prompting
       the user for input. It will then open each of  the  raster  map	layers
       corresponding to each map layer attribute. _r_._b_i_n_f_e_r then determines the
       values for all map layer attributes in each grid cell.  Using the  con-
       ditional  probability tables, the prior probabilities, and Bayes' theo-
       rem, _r_._b_i_n_f_e_r calculates the output  probabilities  for	each  inferred
       value  and  writes  its	probability of occurrence as a percentage.  It
       also determines which value is most likely to occur in  that  cell  and
       writes that to the _o_u_t_p_u_t file name.

EEXXAAMMPPLLEESS
       The  two sample scripts shown below illustrate only the use of _r_._b_i_n_f_e_r
       to:

	      estimate the probability that an avalanche will occur, and

	      infer the probability of finding pine mountain beetles,

       at each cell across a landscape, given the input map  layer  attributes
       shown below.  The author makes no claims as to the correctness of using
       these criteria to infer either event.


       Some Notes on Script Construction.

	       No Data ( or what to do with category zero).


       If category zero is excluded from the ranges  of  any  layer  attribute
       value,  it  is  treated	as "no data" and the resulting probability and
       combined maps will reflect this.


       Otherwise, category zero is treated just like any other cell value.

	       Category ranges for layer attributes.


       The category ranges are specified using _r_._r_e_c_l_a_s_s rules.  For  example,
       a value list for slope might look like this:

       (flat [0 1 thru 3], gentle [4 thru 8],
       moderate [9 thru 15], other [16 thru 89]).


	       Question Attachments.


       Question  attachments  can  be  supplied  for  and context attribute or
       attribute value. If names are chosen cleverly, the default menu	should
       be sufficient.

	       Determinant  List.  At this time the determinant list serves no
	      real purpose.  Planned extensions to binfer  will  make  use  of
	      this list, so just don't use it for now.

	       Probabilities.	The  conditional  probability  table  is  very
	      important, try to be sure of its accuracy.




       #
       # Filename: avalanche.binfer
       #
       # This is a r.binfer script that infers the probability
       # of an avalanche occurring, given the values of the
       # input attributes.
       #
       # NOTE: Execute r.binfer as follows:
       # r.binfer avalanche.binfer [output=name]
       # If the user does not specify an output file name,
       # the combined map will be named binfer.
       #
       # Script file output keywords:
       #
       # CombinedMap (Colortable) - assigns the combined map
       # the given colortable.
       # NoCombinedMap - only generates probability maps
       # (one for each inferred attribute value).
       # NoProbabilityMaps - only generates combined map.
       # (Colortable) can be any of the following keywords:
       # Aspect - aspect colors,
       # Grey,Gray - grey scale,
       # Histo - histogram stretched grey scale,
       # Rainbow - rainbow colors,
       # Ramp - color ramp (default),
       # Random - random colors,
       # RYG - red yellow green,
       # Wave - color wave.
       #
       #
       # Start layer attribute section.
       #
       layer:
       #
       # Layer attribute #1 is aspect
       #
       aspect:
       #
       # all southern exposures = 1.
       # all eastern exposures = 2.
       # all western exposures = 3.
       # all northern exposures = 4.
       # all others = 0.
       #
       (south[16 thru 22],east[22 23 1 thru 4],west[11 thru 15],
       north[5 thru 10]).
       #
       # Layer attribute #2 is slope
       #
       slope:
       #
       # low - 0 to 9 degrees
       # moderate - 10 - 19 degrees
       # steep - 20 - 29 degrees
       # severe - 30 - 88 degrees
       #
       (low[1 thru 10],moderate[11 thru 19],steep[20 thru 30],
       severe[31 thru 89]).
       %
       # End of layer section

       #
       # Start context section
       #
       context:
       #
       # Contextual attribute #1 is temperature
       # NOTE: A menu will be constructed using the attribute
       # name and the names of the attribute values.
       # The user will be prompted to enter his choice.
       #
       temperature:
       (freezing,cold,warm,hot).
       #
       # Contextual attribute #2 is snowfall_amt
       # NOTE: A menu will be constructed using the
       # question attachments supplied here.
       # The user will be prompted to enter his choice.
       #
       snowfall_amt:
       (a {question "Less than one foot."},
       b {question "Between a foot and four feet."},
       c {question "More than four feet."})
       {question "How much snow has accumulated ?"}.
       %
       # End of context section.

       #
       # Start inferred section
       #
       inferred:
       #
       # Inferred attribute is avalanche.
       #
       avalanche:
       #
       # Inferred attribute value "high".
       # A colortable of Ramp will be assigned (default).
       # NOTE: Prior probability, and conditional probabilities
       # are given in this section.
       #
       (high <0.20>
       [0.10,0.50,0.20,0.20;
       0.05,0.15,0.20,0.60;
       0.80,0.15,0.00,0.05;
       0.05,0.35,0.60;] ,
       #
       # Inferred attribute value "moderate".
       # A colortable of Grey will be assigned.
       #
       moderate Grey <0.30>
       [0.15,0.35,0.25,0.25;
       0.10,0.20,0.20,0.50;
       0.75,0.20,0.00,0.05;
       0.05,0.35,0.60;] ,
       #
       # Inferred attribute value "low".
       # A colortable of Rainbow will be assigned.
       #
       low Rainbow <0.50>
       [0.25,0.25,0.25,0.25;
       0.25,0.25,0.25,0.25;
       0.50,0.30,0.10,0.10;
       0.10,0.40,0.50;] ).
       %
       # End of inferred section.
       # End of avalanche.binfer script.





       #
       # Filename: bugs.binfer
       #
       # This is a r.binfer script that infers the probability of
       # finding pine mountain beetles, given the input layer
       # attributes below.  NOTE: Execute r.binfer as follows:
       # binfer bugs.binfer [output=name] if the user does not
       # specify an output name, the combined map will be named
       # binfer.
       #
       # Script file output keywords:
       #
       # CombinedMap (Colortable) - assigns the combined map
       # the given colortable.
       # NoCombinedMap - only generates probability maps
       # (one for each inferred attribute value).
       # NoProbabilityMaps - only generates combined map.
       # (Colortable) can be any of the following keywords:
       # Aspect - aspect colors,
       # Grey,Gray - grey scale,
       # Histo - histogram stretched grey scale,
       # Rainbow - rainbow colors,
       # Ramp - color ramp (default),
       # Random - random colors,
       # RYG - red yellow green,
       # Wave - color wave.
       #
       # Choose the combined map colortable to be a color wave
       CombinedMap Wave
       #
       # Start layer attribute section.
       #
       layer:
       #
       # Layer attribute #1 is slope
       #
       slope:
       #
       #
       (low[1 thru 10],moderate[11 12 13 14 thru 20],
       steep[21 thru 30],severe[31 thru 89]).
       #
       # Layer attribute #2 is aspect
       #
       aspect:
       #
       #
       (south[16 thru 22],east[22 23 1 thru 4],west[11 thru 15],
       north[5 thru 10]).
       #
       # Layer attribute #3 is vegcover
       #
       vegcover:
       (other[1 thru 2],coniferous[3],deciduous[4],mixed[5],
       disturbed[6]).
       #
       # Layer attribute #4 is (forest) density
       #
       density:
       (nonforest[1],sparse[2],moderate[3],dense[4]).
       %
       # End of layer section.

       #
       # Start inferred section
       #
       inferred:
       #
       # Inferred attribute is bugs
       #
       bugs:
       #
       # Inferred attribute value "bugs".
       # A colortable of Ramp will be assigned (default).
       # NOTE: Prior probability, and conditional probabilities
       # are given in this section.
       #
       (bugs <0.20>
       [0.124,0.416,0.371,0.090; # slope conditionals
       0.180,0.292,0.292,0.239; # myaspect,
       0.011,0.798,0.022,0.169,0.0; # vegcover,
       0.202,0.326,0.213,0.258;], # and density (one per value).

       #
       # Inferred attribute value "nobugs".
       # A colortable of Rainbow will be assigned.
       #
       nobugs Rainbow <0.80>
       [0.404,0.416,0.157,0.011;
       0.225,0.281,0.281,0.225;
       0.281,0.427,0.135,0.056,0.0;
       0.584,0.112,0.202,0.112;]).
       %
       # End of inferred section.
       # End of bugs.binfer script.


AAUUTTHHOORR
       Kurt Buehler, Civil Engineering, Purdue University

       _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.binfer(1)
