r.infer

NAME

r.infer - Outputs a raster map layer whose category values represent the application of user-specified criteria (rules statements) to other raster map layers' category values.
(GRASS Raster Program)

SYNOPSIS

r.infer
r.infer help
r.infer [-vt] rulesfile=name

DESCRIPTION

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

r.infer commands (conditions and consequences) are typed into a file by the user using a system editor like vi, and then input to r.infer as the rulesfile named on the command line. The results are used to generate a new raster map layer named infer in the user's current mapset. This program performs analyses similar to r.combine, but uses a (possibly) more pleasing syntax and approach.

OPTIONS

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:

r.infer [-vt] rulesfile=name

where name is the name of an ASCII file containing valid input rules to r.infer, and the (optional) flags -v and -t have the meanings described in the OPTIONS section, below.

Alternately, the user can simply type r.infer 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.

Flags:

-t: Allows the user to run r.infer in test mode. The user is questioned about the truth of each condition named in the file. r.infer then outputs the value that would be placed in the new layer infer 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.infer in test mode prior to actually creating map layers.
-v: Makes r.infer run verbosely, giving information about each cell as it is analyzed according to the statement conditions.

Parameters:

rulesfile=name: Allows the user to input rules to r.infer 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.

COMMANDS AND STATEMENTS

The following commands are available in r.infer:

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 conditions followed by one or more hypotheses and/or conclusions. 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.

IFMAP Map condition

Map conditions are questions to each cell about the presence of specified map layer category values. r.infer questions each cell in the named map layer (here, geology) about its contents (i.e., category value). Cells which satisfy the named condition(s) stated by IFMAP (i.e., here, those cells which contain geology map layer category values 4 or 5) will be assigned the subsequently-stated map conclusion or hypothesis (category), in the new map layer infer. Cells which fail to satisfy named map condition(s) will continue to move down through the user's rulesfile (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 infer (if no additional conclusions/hypotheses are possible in this rulesfile).

example: IFMAP geology 4 5

IFNOTMAP Map condition

Like IFMAP, but instead questions each cell about the absence 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 conclusion\hypothesis, in the new map layer infer.

example: IFNOTMAP owner 2

THENMAPHYP Map conclusion

Assigns each cell a specified category value in the new map layer infer based on the cell's ability or failure to meet conditions named above this THENMAPHYP statement in the rulesfile. The user should note that although the user can specify a uniquely-named rulesfile, r.infer always directs its output to a file named infer 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.infer (e.g., using the GRASS command g.rename).

It is important to realize that r.infer runs through the conditions stated in the named rulesfile 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.infer satisfies a set of conditions, it is assigned a category value in the new map layer infer. r.infer 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 conditions named further down in the input file.

example:
IFMAP density 1
THENMAPHYP 1 no trees

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

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

IF 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:

IFMAP elevation.255 170-255
ANDIFMAP density 3 4
THEN high elevation with trees
!
IF high elevation with trees
ANDIFMAP owner 2
THENMAPHYP 1 this is the place

The above example queries each cell for the presence of both elevations greater than 1580 meters (i.e., for elevation.255 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.infer to ignore whatever appears on that line (a comment statement), 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 both has "high elevations with trees" and owner map layer category 2 (areas owned by the Forest Service), it is assigned by the THENMAPHYP statement to category 1 in the new map layer infer. The trailing text "this is the place" is automatically entered into the category support file for the new map infer. Cells failing to meet all of the conditions stated in this input file will be assigned category 0 in the new map layer infer.

AUTHOR

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