sequence(1)

NAME
sequence - Common flags used in all LNKsequence sequence classifiers and clusterers.

SYNOPSIS
This manual page describes flags and functions common to all sequence classifiers and clusterers in the LNKsequence package. Because many flags used by LNKsequence programs are identical to flags used by LNKnet classification programs, some flags are described more fully on the classifier(1) manual page.

sequence [ -train ] [ -create ] [ -pathexp directory ]
[ -ferror file ] [ -fparam file ]
[ -pathdata directory ] -flist file -fdescribe file
[ -nsequences n ] [ -ninputs n ] [ -features n[,n]... ]
[ -window_width n [ -window_frames n[,n]... ] ]
[ -normalize -fnorm file ] [ -cross_valid n | [
-cross_valid_from_file -fcross_valid file ]
[ -random_cv ] ] [ -random ] [ -seed n ] [ -debug n ]
[ -verbose n ] [ -verror n ]

DESCRIPTION

In LNKnet, there is a set of programs for sequence classification called LNKsequence. The LNKsequence classifier user interfaces are very similar to the LNKnet classifier interfaces. The differences are described here.

The modes of operation for LNKsequence classifiers are the same as
    those for LNKnet classifiers, training, testing, and cross validation testing. For cross validation testing the data is assigned to folds by sequences, not by individual frames.

    TRAINING EXAMPLE
        This command trains a Gaussian sequence classifier using data in the file gender.train and produces a parameter file gauss_seq.param. gauss_seq -train -create \
        -pathdata $LNKHOME/data/seq \
        -flist gender.train -fdescribe gender.defaults \
        -fparam gauss_seq.param

    TESTING EXAMPLE
        This command tests a previously trained Gaussian sequence classifier using data in the file gender.test and parameters from the file gauss_seq.param. gauss_seq -pathdata $LNKHOME/data/seq \
        -flist gender.test -fdescribe gender.defaults \
        -fparam gauss_seq.param

    CROSS VALID EXAMPLE
        This command trains and tests 5 Gaussian sequence classifiers. The sequences in the training file are assigned to five testing folds. For each cross validation fold, a classifier is trained on four folds of sequences. The classifier is then tested on the fifth fold. gauss_seq -cross_valid 5 \
        -pathdata $LNKHOME/data/seq -flist gender.test \
        -fdescribe gender.defaults

Four functions occur before data is presented to a sequence
    classifier for training or testing. First, the sequence list file is read and frame files are identified. These frame files are opened and the frames belonging to each sequence are read. Then, these frames are individually normalized using normalization parameters which were calculated using the norm_seq program on the frames specified in the training list file. Next, input features are selected from these frames and they are stored. When a frame is presented to the classifier, its neighbors are abutted to create a multi-frame window. Frames selected from this window are presented to the sequence classifier as a pattern.

The sequences in a list file can be presented in order or the order
    can be changed. For most incrementally trained sequence classifiers, classification results are improved when the order of sequences is randomized every epoch. When performing N-fold cross validation, the sequences are assigned to training and test sets for each fold. The training sequences for each fold are selected from the fold's training set. The frames in a sequence are always presented in the order they appear in the frame file.

Many files are used by the LNKmap sequence classifiers.

    A description file holds values for the data base type, the number of
        frame input features, the labels for the input featuers, the number of output classes, and the labels for the output classes. Every data base must have a description file. The default name for a description file is <data_base>.defaults. The description file for the gender data base is gender.defaults.

        The description file gender (gender.defaults)
        describe -seq -ninputs 8 -noutputs 2 -labels female,male
        -input_labels C0,C1,C2,C3,C4,C5,C6,C7

    These are the lists of sequences of frames used for training or
        testing a sequence classifier. Each data base usually has three list files, a training file, an evaluation file, and a testing file. The training list file is usually the largest. The evaluation file is used when testing a sequence classifier while tuning classifier parameters such as size or how many epochs to train. After having used the evaluation file to tune classifier parameters, another test file is needed for reporting the error rate of this sequence classifier on new data. This testing list file is to be used infrequently, ideally only once. The default names of the list files are based on the name of the data base. The training file is <data_base>.train. The evaluation file is <data_base.eval and the testing file is <data_base>.test. Thus the list files in the gender data base are gender.train, gender.eval, and gender.test. The format of all these files is the same. Each list file is an ASCII file with one sequence per line. The first field on each line is the class of the sequence. This class can be an integer class number, as in LNKnet data files, or a class label. If the class is an integer, it must be from 0 to noutputs-1, where noutputs is the number of output classes specified in the data base description file. If the class is a label, the label must match one of the class labels in the description file. The second field is the frame file name. If the frame file consists of more than one sequence, a third and fourth field are added to the list file line. The third field is the frame number of the first frame in the sequence. The number of the first frame in a frame file is 0. The fourth field is the duration in frames of a sequence.

        An example list file (gender.train)
        male sw2163_a.dat
        female sw2163_b.dat
        male sw1037.dat 0 20548
        female sw1037.dat 20568 19642

    The sequences in a LNKsequence data base can be found in many frame
        files. Frame files are ASCII files with one line per frame. Each line has the floating point values for the input features for each frame of data. Unlike LNKnet data files, there is no class information in frame files. The list files are used to identify the class of the frames in each sequence. There are no limitations on the names given to frame data files, provided they match the names used in list files.

        Five frames from sw1037.dat
         -2.873 0.6599 0.9521 -0.4902  1.143   1.67 -0.8673  1.498
         -2.113 -0.06797 0.06473 -1.207  1.272   2.29 -0.5885 0.7758
         -3.567 0.6243 -0.4729 -2.035 0.1802  1.555 -0.6339  1.516
         -0.8087 0.07863  0.365 -2.151  1.007   1.94 -0.7745 0.3789
         0.1152 0.8266 0.5006 -1.406  0.798  2.055 -0.9471 0.2887

    Normalization files for sequence data are created using the program
        norm_seq. They are used in the same way as the files for classification data.

    Sequence classification parameter files are the same as static pattern
        classification parameter files with one exception. Sequence classification parameter files include information about the windowing parameters used when combining frames to create multi-frame input patterns.

    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 sequence classifiers.

        0   Do not produce an error file.

        1   Produce a "results" error file. There is a line in the error file for each pattern tested by the sequence classifier. There are five fields in each line. The fields are:
            sequence number, correct class, class returned by the sequence classifier, whether the returned class was in error, and the total RMS error for the outputs for each frame in the sequence.

        2   Produce a "results+outputs" error file. There is a line in the error file for each pattern tested. There are There is a line in the error file for each pattern tested by the sequence classifier. There are 5 + noutputs fields on each line. The first 5 fields are as in the "results" file. The next noutputs fields are the total outputs for each class for each frame in the sequence.

    The LNKsequence programs print information about a sequence
        classification run to the standard output and to the standard error output. When running LNKsequence programs from the LNKsequence 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
            sequence classifier'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 sequence classifier flags and their arguments without running the program.

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

-create
    Creates a new error file. Otherwise, sequence by sequence errors are appended to an existing error file. If the -train flag is on, a new sequence classification 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 sequence classification results in testing or training. Example: -ferror X1mlp_seq.err.train

-fparam file
    Name of the file in pathexp for storing sequence classifier parameters. Example: -fparam X1mlp_seq.param

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

-flist file
    This flag is required. The ASCII file in pathdata where the sequence to be used for either training or testing a sequence classifier or clusterer are defined. The format and naming conventions for input files are described above. Example: -flist gender.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 output classes, and the class labels. Description files are described in more detail above. Example: -fdescribe gender.defaults

-nsequences n
    n is the number of sequences to read from flist. If this number is less than the number of lines in flist, only the first nsequences sequences will be used by the sequence classifier.

-ninputs n
    n is the number of dimensions of each normalized frame to be used by the sequence classifier. 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 sequence classification 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 sequence classifier 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 sequence classification 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 sequence classifier in the order given.

-window_width n
    n neighboring frames are abutted to create a multi-frame pattern which is then presented to a classifier. The first pattern from a sequence consists of the first n frames of data in the sequence. The second pattern from a sequence consists of the n frames starting from the second frame in the sequence. The last pattern from a sequence consists of the last n frames in the sequence.

-window_frames n[,n]...
    If window_width has been set to a number greater than one, a subset of the frames in a window can be selected for inclusion in a multi-frame pattern. In this example, each pattern will consist of two frames which are separated by three frames: -window_width 5 -window_frames 0,4

-normalize
    When reading in the data, normalize it using the parameters present in fnorm. If testing a sequence classification 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 gender.norm.simple

-cross_valid n
    If the train flag is not set, do n fold cross validation on the data. This means that the sequences will be split into n parts and n classification models or sets of clusters will be trained and tested on the sequences in flist. The sequences are automatically assigned to folds as described above. If the flag cross_valid_from_file is set, this flag is ignored.

-cross_valid_from_file
    If the train flag is not set, do cross validation on the data using the flags in cross_valid_file to determine which sequences in flist are in each training and testing fold.

-fcross_valid file
    The file in pathdata which contains flags which specify the splits and folds used in cross validation when cross_valid_from_file is set. An example of a cross validation file is given on the classifier(1) manual page. The one difference is that for the static pattern classifiers described on the classifier(1) page fcross_valid specifies assignment of patterns to folds. Sequence cross validation files specify these assignments for sequences. Example: -fcross_valid gender.train.cv

-random
    Randomize the order of the sequences 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 sequence classifier.

-verbose n
    The value of n determines the quantity of sequence classification status messages and error summary information printed out during runs of a sequence classifier. 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 options differ from the static pattern classifier options with the same name.

-fdescribe
    The flag -seq should always be set in the description file for a sequence classification data base.

The following LNKnet static pattern classification options are unavailable for sequence classification programs:

    -adjust_train_priors, -priors_npatterns,
        -train_uniform_priors, -train_priors_list -adjust_test_priors, -test_uniform_priors, -test_priors_list Priors adjustment is not done by sequence classifiers.

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

SEE ALSO
classifier(1), mlp_seq(1), gauss_seq(1), gmix_seq(1), rbf_seq(1), irbf_seq(1), kmeans_seq(1), norm_seq(1)

HISTORY
First written 21 June 1994 by Linda Kukolich

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