Albero Mapper: maps rules as Idrisi images

    Updated version (28th September 1998). Compact rule format, arithmetic rule support, faster processing, better error handling
    Version 0.300, Michael Bedward,


    Albero Mapper is a utility to generate maps from decision rules and a series of input maps. It was written for use with the Albero decision tree modelling system but can be used to map any set of rules that can be expressed as C style if statements. It works with Idrisi format map images and runs on PCs under Windows 3.1 or above.

    This version is the second release with a bold move from version number 0.0001 to 0.300 !  If you used the previous version you might want to look at the list of changes.  The program is still just a beginning and could be improved a lot so please email me your comments, complaints and suggestions.

    What you can do with it?
    The Albero Mapper is useful where you have a set of rules that describe the relationship between an attribute that you wish to map (the response) and a set of other attributes that you already have maps for (the predictors).For example, here is a rule that describe where a vegetation type is found in relation to some landscape variables...

          if ( geology == granite  &&
               elevation <= 200  &&
               rain > 1200 )
            veg = 10 ;

    This rule is formatted as an if statement for the C programming language (the only format that Albero Mapper presently understands). It means:
          IF geology is granite
          AND elevation is up to 200m
          AND annual rainfall is greater than 1200mm
          THEN vegetation is Type 10

    If you have Idrisi images for geology, elevation and annual rainfall in the study area you can use Albero Mapper to generate a new image that shows where vegetation type 10 occurs. You could do this with Idrisi but it would be time consuming and would involve generating a series of intermediate images. Albero Mapper lets you do it in one step. And rather than mapping one rule at a time it works with sets of many rules. So, your rule set could describe the distribution of a whole series of vegetation types which will all be mapped in one run.

Getting the software and getting started

    The Mapper distribution consists of three files:
    File  Description   Download site Executable file for MS Windows Sydney (Australia)
      Salzburg (Austria) Notes, example rules and data files Sydney (Australia)
      Salzburg (Austria) C++ source code   Sydney (Australia)
      Salzburg (Austria)

    If you are a Windows 3.1x user you will also need to install Win32s if you don't already have it.

        Conditions of use
    Albero Mapper is freeware. You can use and distribute the program and the associated source code as you wish but you are not to sell the program or any part of it without the express permission of the author. Albero Mapper comes with ABSOLUTELY NO WARRANTY and could contain errors. The author will accept NO LIABILITY for whatever terrible havoc you may wreak with this program. You are on your own.

    The file contains mapper.exe (a 32 bit Windows executable file) and mapper.txt (these notes). To install on your PC, unzip with pkunzip or InfoZip unzip and put mapper.exe in a convenient directory on your hard disk.  To run Mapper under Windows 3.1 you need to have Win32s installed.  If you don't you can download it from the Microsoft ftp site.

    Basic concepts
    Albero Mapper reads rules from a text file, applies them to a set of Idrisi images and generates a map as a new Idrisi image.
    Here is an example of a single rule to map a vegetation type:
         if ( altitude < 150  &&
              geology == 3
           vegetation = 1 ;
    In this example, altitude and geology are the predictor variables and vegetation is the response variable. Every decision rule describes the relationship between one or more predictors and the response. The rule is formatted as an if statement for the C programming language where && means AND.
    When Albero Mapper processes this rule it will read values of altitude and geology from Idrisi-format images, the predictor images, test the rule for each pixel in turn, and generate a response image for vegetation.

    Here is an example for tiny images:

           altitude                  geology                vegetation

     160 | 155 | 149 | 145     5  |  5  |  3  |  3      0  |  0  |  1  |  1
     ---------------------    ---------------------    ---------------------
     161 | 157 | 150 | 146     5  |  3  |  5  |  3      0  |  0  |  0  |  1
     ---------------------    ---------------------    ---------------------
     159 | 154 | 148 | 140     5  |  5  |  3  |  3      0  |  0  |  1  |  1
     ---------------------    ---------------------    ---------------------
     155 | 151 | 142 | 137     5  |  3  |  3  |  3      0  |  0  |  1  |  1

    A rule can contain many conditions and you can use legend names instead of numeric values. Here is another example:

         if ( ( geology == sandstone  ||  geology == metaseds )  &&
              altitude >= 200  && altitude < 500  &&
              rainfall >= 1000  &&
              topo_roughness >= -20 )
              vegetation = magic_forest ;

    "==" is the comparison operator while "||" means OR. So this rule is read as:

         IF geology is sandstone OR metaseds AND
            altitude is at least 200 but less than 500 AND
            rainfall is at least 1000 AND
            topo_roughness is at least -20
            vegetation is magic_forest

        Rule syntax

    This version of Albero Mapper understands a resonable complete subset of C/C++ if statement terms.

    The form of each rule is:
         if ( condition1  op  condition2   op .... )
           {response = value ;}
     where "op" is either "&&" (logical AND) or "||" (logical OR)
    Each condition can be simple, e.g. altitude < 200 or compound, e.g. ( geology == granite || geology == basalt )
    These comparison operators are supported:

     ==  ( is equal to )
     !=  ( not equal to )
     >   ( greater than )
     >=  ( greater than or equal to )
     <   ( less than )
     <=  ( less than or equal to )

    A condition can also be just a variable name in which case it will be true if the value of the variable is non-zero. For example, if you have a map of a study area where a pixel value of 0 means outside and 1 means inside, then this rule will pick occurrences of basalt inside the study area.

     if ( studyArea && geology == basalt )
         newMap = basalt ;

    The response term must be of the form "response_name = value ;" and must be enclosed within curly brackets as in the above examples. The semicolon is required.

        Types of predictor variables

    Predictor variables can be either image or coordinate type. An image variable refers to values in an Idrisi image such as in the examples above. A coordinate variable refers to X or Y coordinates. To use coordinate variables you need to make sure that the document files for your Idrisi images all contain valid values for min and max X and Y coordinates. The following rule uses coordinate variables to map steep areas in a rectangular zone:

         if ( easting >= 720000  &&  easting <= 750000  &&
              northing >= 5900000  &&  northing <= 5920000  &&
              slope > 20 )
           steep_area = 1 ;

        Arithmetic terms in rules
    Mapper optionally supports arithmetic rules like this one...

        if ( maxTemperature - minTemperature > 20 )
        tempRange = Big ;

    ...and here's another example...

        if ( inStudyArea )
            localExtinctionProb = ( numberBotanists * 20 ) / numberPlants ;

    Interpreting arithmetic terms slows Mapper down substantially so the default mode is no arithmetic support.  Click the arithmetic support check box to turn this feature on.

        How Albero Mapper processes multiple rules

    Normally you will run Albero Mapper with a rule file that contains tens or perhaps hundreds of rules. Multiple rules are arranged to form a block of nested if / else if / else statements that looks like this...

     if ( ... )
       if ( ... )
         response = r1 ;
       else if ( ... )
         response = r2 ;
     else if ( ... )
       response = r3 ;
       response = r4 ;

    This format differs from that used by Albero Mapper 0.0001 (see changes). As soon as a rule is found that tests positive for a given location, the program writes the response value specified by that rule to the output map and then moves on to the next location.

        Using legends
    You can used legend category names in your rules for both predictor and response variables. Albero Mapper does not read legend information from Idrisi document files. Instead, it expects the legends to be in separate text files where each record is:

         numeric_value  category_name

         1 sandstone
         2 granite
         3 basalt

    The values and names are separated by spaces or tabs.

        Output image
    Albero Mapper produces a binary integer format Idrisi image with a default background value of 0. Any pixels that do not test positive to any of the rules in your rule set will be given this background value.  Mapper also creates an Idrisi document file that contains the parameters for the output image.

    Files for Albero Mapper
    To get started, you will need the following data files:

       * a variable description file
       * a rule file
       * an Idrisi image for each predictor variable used in the rules
       * optional legend files

    A variable description file is a text file that tells Albero Mapper about the predictor and response variables and the associated image and legend files. Here is an example:

         vegetation      response        veg.leg
         geology         8class.img      8class.leg
         easting         xcoord
         northing        ycoord
         altitude        alt.img
         aspect          sinaspct.img
         slope           slope.img
         photo_class     photo.img       photo.leg

    Column 1 is the variable name. Variable names must be exactly the same as they appear in the rules file. Albero Mapper is case sensitive so "Altitude" is seen as different to "altitude".

    Column 2 is the variable source. For the response variable this is just the word "response". For normal predictors the source is the name of the Idrisi image file, including the extension. For coordinate variables it is "xcoord" or "ycoord".
    Column 3 is the legend file name. For those variables that don't use a legend you just leave this blank.

        Rule file
    This is a text file that contains the set of rules that you want to process. The maximum number of rules is limited only by available memory for processing.

    Idrisi images
These must be either binary byte or binary integer type and be accompanied by document files. All of the images must have the same number of rows and columns and the same coordinate limits.

        Legend files

    For each variable that uses a legend you need to provide a text file with the legend information in the form:

        pixel_value  category_name
        pixel_value  category_name
        pixel_value  category_name

        Running the program
    Start the program from within Windows by clicking on it's icon (if you have chosen to use one) or selecting the program from the File Manager (Win 3.1) or Explorer (Win 95/NT). Enter the path and file names for the variable
description file, the rule file and the name of the output image file that you want generated. Then click the "Run" button.

        Known bugs

    See changes for a list of bugs fixed since the last version.  Please email me if you find bugs or just have any problems with the current version.

        Source code

    Albero Mapper is written in C++ and uses the fabulous public domain wxWindows class library version 1.68.  It does not yet compile with wxWindows version 2.  It has been compiled with Borland C++ version 4.52 for Windows and with Gnu gcc 2.7.2 for Sun/Solaris.

             Michael Bedward - Last modified 28 September 1998