mapper(1)

NAME
mapper - Common flags used in all LNKnet/LNKmap mappers.

SYNOPSIS
This manual page describes flags and functions common to all input/output mappers in the LNKmap package. Because many flags used by LNKmap programs are identical to flags used by LNKnet classification programs, some flags are described more fully on the classifier(1) manual page.

LNKmap and the LNKmap input/output mapping programs are experimental and are not fully supported.

mapper [ -train ] [ -create ] [ -pathexp directory ]
[ -ferror file ] [ -fparam file ]
[ -pathdata directory ] -finput file -fdescribe file
[ -labels string[,string]... ] [ -nraw n ]
[ -noutputs n ] [ -npatterns n ] [ -ninputs n ]
[ -features n[,n]... ] [ -normalize -fnorm file ]
[ -random ] [ -seed n ] [ -debug n ] [ -verbose n ]
[ -verror n ]

DESCRIPTION

In LNKnet, there is a set of programs for input/output function mapping. This set is called LNKmap. The LNKmap mapper user interfaces are very similar to the LNKnet classifier interfaces. The differences are described here.

There is no cross validation mode for the mapping programs.
    Only training and testing modes are available. They are similar to the training and testing modes for the classifiers.

    TRAINING EXAMPLE
        This command trains a multi-layer perceptron mapper using data in the file gauss_map.train and produces a parameter file X1mlpm.param mlpm -epochs 10 -train -create -nodes 1,3,1 \
        -nraw 1 -pathdata $LNKHOME/data/map \
        -finput gauss_map.train \
        -fdescribe gauss_map.train.defaults \
        -npatterns 200 -fparam X1mlpm.param

    TESTING EXAMPLE
        This command tests a previously trained multi-layer perceptron mapper using data in the file gauss_map.test and parameters from the file X1mlpm.param. mlpm -pathdata $LNKHOME/data/map \
        -finput gauss_map.test \
        -fdescribe gauss_map.test.defaults -nraw 1 \
        -finput X1mlpm.param

Data is presented to a mapper as it is to a classifier.  There are two
    functions which are performed before data is presented to a classifier for training or testing. First, data is read from a file, normalized and stored internally. Second, patterns are selected for presentation to the mapper.

    The process of reading a mapping patterns is the same as that of
        reading a classification pattern. The process has three parts. The first is parsing a line in the input file. In the second, data is normalized using parameters taken from a normalization file which was generated using the training file of the data base. Finally, if the user has requested that only certain features of the input pattern be used, those features are selected.

    There are two methods for selecting patterns for presentation to a
        LNKmap input/output mapper, using the data in its input file order, and randomizing the order once per training epoch data before presenting it. LNKnet classifiers can also perform automatic cross validation experiments and patterns can be selected to achieve some desired a priori class probability. These two features are unavailable in LNKmap.

Many files are used by the LNKmap mappers.

    These are the files of patterns used for training or testing a
        mapper. Usually, for any particular data base there are three files, a training file, an evaluation file, and a test file. The training file is usually the largest, and holds the data to be used for training mappers. The evaluation file is used to test a mapper while tuning algorithm parameters for this data base. After having used the evaluation file to tune algorithm parameters, another test file is needed for reporting the error rate of this mapper on new data. This testing file is to be used infrequently, ideally only once. The default names of the input files are based on the name of the data base. The training file is <data_base>.train, so the training file for the gauss_map data base is gauss_map.train. The evaluation file is <data_base>.eval and the testing file is <data_base>.test. The evaluation and testing files for the gauss_map data base are gauss_map.eval and gauss_map.test.

        The format of all of the data files is the same. Each file is an ASCII file of input and output patterns, one pair of patterns per line. The input values are first, followed by the output values for that input pattern.

        An example input file (sample.train):
         0.2    0.3    0.5     -0.1
        -0.4    0.5    0.1     -0.9
         0.0    0.3    0.3     -0.3
        The function being mapped is y1 = x1+x2, y2 = x1-x2

    A description file holds default values for the flags
        nraw, noutputs, npatterns, and labels. There should be a description file for every input file. The default name is <input_file>.defaults, so the description file for the gauss_map training file is gauss_map.train.defaults.

        The description file for the data file above (sample.train.defaults):
        describe -ninputs 2 -noutputs 2 -npatterns 3 -labels y1,y2 -map

    Normalization files for mapping data are created using the program
        norm_map. They are used in the same way as the normalization files for classification data. The normalization file type lda is not available for mapping data.

    Mapping parameter files are the same as classifier parameter files.

    During testing and during incremental training, pattern by pattern
        mapping results are written to an error file. The contents of this error file are controlled by the value of verror. The following settings for verror are recognized by the mappers.

        0   Do not produce an error file.

        1   Produce a "short" error file. There is a line in the error file for each pattern tested by the mapper. There are 2 fields in each line. The fields are:
            line number, and the RMS error of the mapper outputs

        2   Produce an "outputs" error file. There is a line in the error file for each pattern tested by the mapper. There are 2 + 2*noutputs fields in each line. The first 2 fields are as in the "short" file. The next 2*noutputs fields are the desired outputs for the pattern and the outputs produced by the mapper.

        3   Produce an "outputs+inputs" error file. There is a line in the error file for each pattern tested. There are 2 + 2*noutputs + ninputs fields in each line. The first 2 + 2*noutputs + 2 fields are as in the "outputs" file. The next ninputs fields are the inputs given to the mapper for this pattern.

    The LNKmap programs print information about a mapping run to
        the standard output and to the standard error output. When running LNKmap programs from the LNKmap graphical interface, this information is also written to a log file. The quantity of information printed depends on the setting of verbose. At its highest setting, the following is printed:

        A line to mark the start of the program.

        The command used to call this program.  This is an expanded version of
            the command, with the default values of those flags which were not set shown. The start time for execution is also shown.

        If this is an incremental training run, some indication of the
            mapper's status for each epoch.

        An error summary by output number for any testing done during this run.

        An overall error rate for testing during this run.

        A line to mark the end of the program.

OPTIONS
The following options are recognized with spaces separating an option and any following items:

--  A double dash on the command line prints a list of all mapper flags and their arguments without running the program.

-train
    Perform training. If -create is set, the mapper is trained from scratch. Otherwise, an existing parameter file is read and training is continued on that mapper.

-create
    Creates a new error file. Otherwise, pattern by pattern errors are appended to an existing error file. If the -train flag is on, a new mapper model is created.

-pathexp directory
    The base directory used for writing the files ferror and fparam A slash "/" is automatically added to the end of the base directory if it doesn't end with a slash. Example: -pathexp ./

-ferror file
    Name of the file in pathexp for storing mapping results in testing or training. Example: -ferror X1mlp.err.train

-fparam file
    Name of the file in pathexp for storing mapper parameters. Example: -fparam X1mlp.param

-pathdata directory
    The base directory used for finding the data files finput, fdescribe and fnorm. A slash "/" is automatically added to the end of the base directory if it doesn't end with a slash. Example: -pathdata lnknet/data/map

-finput file
    This flag is required. The ASCII file in pathdata with the data to be used for either training or testing a mapper or clusterer. The format and naming conventions for input files are described above. Example: -finput gauss_map.train

-fdescribe file
    This file is required. The file in pathdata which contains the values for the data base type, number of input features, input feature labels, number of outputs, and the output labels. The data base type should be -map. Description files are described in more detail above. Example: -fdescribe gauss_map.train.defaults

-labels str[,str]...
    The comma delimited list of strings used to label the noutputs outputs in finput. Example: -labels A1,A2,S1,S2

-nraw n
    n is the number of input features of each pattern in finput.

-noutputs n
    n is the number of output features of each pattern in finput. The total number of fields in each line of finput should be nraw + noutputs.

-npatterns n
    n is the number of patterns to read from finput. If this number is less than the number of lines in finput, only the first npatterns patterns will be used by the mapper.

-ninputs n
    n is the number of dimensions of each normalized pattern to be used by the mapper. If this flag is not set, all available data dimensions will be used. If this flag is set to a number less than the number of inputs given in the data base description file, only the first ninputs dimensions will be used. If a list of dimensions to be used is specified by features, ninputs should be the length of the features list. If testing a mapping model or continuing the training of an existing model, this flag has no effect.

-features n[n,]...
    An integer list of the dimensions of the normalized data to be used by the mapper in training. These dimensions are counted starting at 0, meaning that in the case of a three dimensional data base, the entries in the features list can be 0, 1, or 2. If testing a mapping model or continuing the training of an existing model, this flag has no effect.
    Example: -features 3,0,2
    The fourth, first, and third dimensions of the data will be used in this mapper in the order given.

-normalize
    When reading in the data, normalize it using the parameters present in fnorm. If testing a mapping model or continuing the training of an existing model, this flag has no effect.

-fnorm file
    The file in pathdata which has the normalization parameters to be used when normalizing the data in the input file. Normalization files are described above. Example -fnorm gauss_map.norm.simple

-random
    Randomize the order of the data before each epoch of training. This flag has no effect when testing.

-seed n
    Initialize the random number generator using n as the seed.

-debug n
    The value of n determines the quantity of debugging messages printed out during runs of a mapper.

-verbose n
    The value of n determines the quantity of mapper status messages and error summary information printed out during runs of a mapper. What is printed at which verbosity levels is described above.

-verror n
    The value of n determines the amount of data put in the error file ferror. The possible values for n are described above.

The following classifier options are unavailable for mapping programs:

    -cross_valid, -cross_valid_from_file, -fcross_valid
        Cross validation testing is not done by the mapping programs.

    -adjust_train_priors, -priors_npatterns, -train_uniform_priors, -train_priors_list,
        -adjust_test_priors, -test_uniform_priors,
        -test_priors_list
        Priors adjustment cannot be done by mappers, as there are no classes.

    -log_outputs
        The outputs are always printed in the linear domain.

SEE ALSO
classifier(1), mlpm(1), rbfm(1), irbfm(1), kmeansm(1), norm_map(1)

HISTORY
First written 5 July 1993 by Linda Kukolich
Modified 21 June 1994, added flag lists

BUGS
Send bug reports to Linda Kukolich (kukolich@sst.ll.mit.edu)