## NAME

r.binfer - Bayesian expert system development program.
(GRASS Raster Program)

## SYNOPSIS

r.binfer
r.binfer help
r.binfer [-v] input=name [output=name]

## DESCRIPTION

r.binfer 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.binfer, the system bases the probable impacts of a future land use action on the conditional probabilities about the impact of similar past actions.

## OPTIONS

### Flag:

-v
  Run verbosely, displaying messages on debugging output to standard output. Includes a listing of the symbol table used by r.binfer.

### Parameters:

input=name
  Name of an existing file containing analysis instructions.
output=name
  Name to be assigned to the file to contain program output.
  Default: binfer.out

Using appropriate r.binfer 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 texture, 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 containing 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.binfer (or whatever output 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 occurring in each grid cell, given the values of the input raster map layer and contextual attributes.

r.binfer scripts are typed into a file by the user using a system editor like vi, and then input to r.binfer as the input file named on the command line. For a complete description of the input syntax, see the document GRASS Tutorial: r.binfer (forthcoming). For example r.binfer 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.binfer 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 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.binfer 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.binfer 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.binfer 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 output file name.

## EXAMPLES

The two sample scripts shown below illustrate only the use of r.binfer to:

1. estimate the probability that an avalanche will occur, and
2. 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.

1. 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.

2. Category ranges for layer attributes.

   The category ranges are specified using r.reclass 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]).

3. 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.

4. 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.
5. 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.

## AUTHOR

Kurt Buehler, Civil Engineering, Purdue University

Last changed: $Date: 2002/01/25 05:45:34 $