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 sys-
       tem bases the probable impacts of a future land use action
       on the conditional probabilities about the impact of simi-
       lar past actions.

OOPPTTIIOONNSS
   FFllaagg::
       --vv     Run  verbosely,  displaying  messages  on debugging
	      output to standard 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 struc-
       tures an input knowledge/control script with an	appropri-
       ate combination of map layer category values (GRASS raster
       map layers that contain data on soil texture, slope,  den-
       sity,  etc.)  and  attributes  relevant to decision-making
       (e.g., rainfall, temperature,  season,  subjective  judge-
       ment,  etc.).   Options exist for specifying a user inter-
       face and a data	base  containing  prior  and  conditional
       probabilities  necessary  to  infer  the  value	of a goal
       attribute.  The expert also specifies the format for  dis-
       play  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 probability of occur-
       ring  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  editor  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 generate 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 contem-
       plated.	 For  example,	if  the  user  chooses	"rainfall
       amount" as one of the contextual attributes, possible val-
       ues 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 probability and a table of conditional probabilities
       that indicate the probability 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 conditional
       probability  tables,  the  prior probabilities, and Bayes'
       theorem, _r_._b_i_n_f_e_r calculates the output probabilities  for
       each  inferred  value and writes its probability of occur-
       rence 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 bee-
	      tles,

       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  clev-
       erly, 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)
