.TH r.infer .nh .SH NAME \fIr.infer\fR \- Outputs a raster map layer whose category values represent the application of user-specified criteria (rules statements) to other raster map layers' category values. .br .I (GRASS Raster Program) .SH SYNOPSIS \fBr.infer\fR .br \fBr.infer help\fR .br \fBr.infer \fR[\fB-vt\fR] \fBrulesfile\*=\fIname\fR .SH DESCRIPTION .I 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 \fIinfer\fR is created as output, whose category values reflect the ability of each cell in the named input layers to satisfy the named conditions. \fIr.infer\fR commands (conditions and consequences) are typed into a file by the user using a system editor like \fIvi\fR, and then input to \fIr.infer\fR as the \fIrulesfile\fR named on the command line. The results are used to generate a new raster map layer named \fIinfer\fR in the user's current mapset. This program performs analyses similar to .I r.combine, but uses a (possibly) more pleasing syntax and approach. .SH 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: .RS \fBr.infer \fR[\fB-vt\fR] \fBrulesfile\*=\fIname\fR .RE where \fIname\fR is the name of an ASCII file containing valid input rules to \fIr.infer\fR, and the (optional) flags \fI-v\fR and \fI-t\fR have the meanings described in the OPTIONS section, below. Alternately, the user can simply type \fBr.infer\fR 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 described in the manual entry for \fIparser\fR. .LP \fBFlags:\fR .IP \fB-t\fR Allows the user to run \fIr.infer\fR in \fItest\fR mode. The user is questioned about the truth of each condition named in the file. \fIr.infer\fR then outputs the value that would be placed in the new layer \fIinfer\fR 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 \fIr.infer\fR in test mode prior to actually creating map layers. .IP \fB-v\fR Makes \fIr.infer\fR run \fIverbosely\fR, giving information about each cell as it is analyzed according to the statement conditions. .LP \fBParameter:\fR .IP \fBrulesfile\*=\fIname\fR Allows the user to input rules to \fIr.infer\fR 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. .SH COMMANDS AND STATEMENTS The following commands are available in .I r.infer: .sp .5 .TS c|c|c|c l|l|l|l. 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 .TE 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 \fBconditions\fR followed by one or more \fBhypotheses\fR and/or \fBconclusions\fR. 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. .ti -.25i IFMAP .ti -.25i .B Map condition. .ti -.25i Map conditions are questions to each cell about the presence of specified map layer category values. \fIr.infer\fR questions each cell in the named map layer (here, \fIgeology\fR) about its contents (i.e., category value). Cells which satisfy the named condition(s) stated by IFMAP (i.e., here, those cells which contain \fIgeology\fR map layer category values 4 or 5) will be assigned the subsequently-stated map conclusion or hypothesis (category), in the new map layer \fIinfer\fR. Cells which fail to satisfy named map condition(s) will continue to move down through the user's \fIrulesfile\fR (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 \fIinfer\fR (if no additional conclusions/hypotheses are possible in this \fIrulesfile\fR). example: \fB IFMAP geology 4 5\fR .ti -.25i IFNOTMAP .ti -.25i .B Map condition. .ti -.25i Like IFMAP, but instead questions each cell about the \fIabsence\fR 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 \fIinfer\fR. example: \fBIFNOTMAP owner 2\fR .ti -.25i THENMAPHYP .ti -.25i .B Map conclusion. .ti -.25i Assigns each cell a specified category value in the new map layer \fIinfer\fR based on the cell's ability or failure to meet conditions named above this THENMAPHYP statement in the \fIrulesfile\fR. The user should note that although the user can specify a uniquely-named \fIrulesfile\fR, \fIr.infer\fR always directs its output to a file named \fIinfer\fR 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 \fIr.infer\fR (e.g., using the GRASS command \fIg.rename\fR). It is important to realize that \fIr.infer\fR runs through the conditions stated in the named \fIrulesfile\fR 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 \fIr.infer\fR satisfies a set of conditions, it is assigned a category value in the new map layer \fIinfer\fR. \fIr.infer\fR 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. .IP example: 10 \fB IFMAP density 1 .br THENMAPHYP 1 no trees\fR .PP In the above example, all cells having a category value of \fI1\fR (non-forest) in the map layer \fIdensity\fR, are assigned a category value of \fI1\fR in the resultant map layer \fIinfer\fR. The trailing text "no trees" is entered into the category support file for category 1 in the new map layer \fIinfer\fR. .ti -.25i THEN .ti -.25i .B Statement hypothesis. .ti -.25i 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. .ti -.25i IF .ti -.25i .B Statement condition. .ti -.25i 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. .IP example: 10 \fBIFMAP elevation.255 170-255 .br ANDIFMAP density 3 4 .br THEN high elevation with trees .br ! .br IF high elevation with trees .br ANDIFMAP owner 2 .br THENMAPHYP 1 this is the place\fR .PP The above example queries each cell for the presence of \fIboth\fR elevations greater than 1580 meters (i.e., for \fIelevation.255\fR 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 .I 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 \fIboth\fR has "high elevations with trees" and \fIowner\fR 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 \fIinfer\fR. The trailing text "this is the place" is automatically entered into the category support file for the new map \fIinfer\fR. Cells failing to meet all of the conditions stated in this input file will be assigned category 0 in the new map layer \fIinfer\fR. .SH SEE ALSO \fIGRASS Tutorial: r.infer\fR .br .I g.rename, .I r.combine, .I r.mapcalc, .I r.weight, and .I parser .SH "AUTHOR" James Westervelt, U.S. Army Construction Engineering Research Laboratory .LP Special recognition goes to: .br .nf 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 .fi .sp 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 \fIr.infer\fR.