The first part of this appendix describes the MIndUtil program and its options. The second part lists and describes the general options for MIndUtil. The final part describes induction modes. The MIndUtil program comes with the server side of the MineSet images and is invoked automatically on the server when working through Tool Manager.
MIndUtil provides the MineSet inducers and mining utilities, such as discretization (binning). It also provides features for file conversions. In the following description, all examples assume the UNIX shell is csh or tcsh. Users of sh and ksh can transform setenv ENV val into env=val; export env.
The syntax for invoking MIndUtil is:
MIndUtil [-s] [-o <optionfile>] [-O <option>=<value>] |
where the -s option suppresses environment options (described below). The -o option allows reading options from an ASCII option specification file containing one <option>=<value> per line. By convention, MineSet uses the suffix .classify-opt for such option files. The -O option (uppercase) allows setting a specific option by following it with the option name, an equal sign, and the value. The -o and -O can be repeated multiple times. If an option is set more than once, the last time it is set determines its value. For example, if it is set through an option file and then set again through using the -O flag, the latter one determines its value.
Each option has a unique name; all option names are written in uppercase letters. If you want to set up the .datamove file to keep data and classifier option files on the server, the following lines must be in the .datamove file:
keep_data_files=yes keep_classifier_options_files=yes |
This ensures that the option specification files ending with the .classify-opt extension (consisting of the options passed to MIndUtil via the Tool Manager) are not erased from the server after you invoke inducers through Tool Manager.
A typical file (iris.classify-opt) might contain the following lines:
MODE=train-and-test LABEL=iris_type INDUCER=decision-tree DT_MAX_LEVEL=0 DT_SPLIT_BY=normalized-mutual-info DT_PRUNING_FACTOR=0.85 DT_LBOUND_MIN_SPLIT=5 CLASSIFIER_NAME=iris-dt.class VIZ_NAME=iris-dt.treeviz TRAIN_FRACTION=0.666667 ACC_EST_SEED=7258789 |
Given a schema file (iris.schema, which references iris.data), you can run MIndUtil from the command line to induce a decision tree by using the options file as follows:
MIndUtil -o iris.classify-opt -O SCHEMA=iris.schema |
This is exactly the way MIndUtil is invoked by DataMover.
Options in MIndUtil can be set through a hierarchy of levels. An option set at a higher level (see below) overrides any setting from a lower level. The levels are:
Hard-coded default—Many options have a hard-coded default value. If the value is not overridden in any of the higher levels, the hard-coded default is used.
Environment option—An environment variable can contain the option's value. You can set the environment variable with the same name as the option itself. For example,
setenv SCHEMA iris.schema |
sets the SCHEMA option to iris.schema.
An environment variable takes precedence over hard-coded defaults. The command-line option -s suppresses environment variables.
Command-line options—You can set specific options with -O <option>=<value>
For example, to generate a decision tree from iris.classify-opt, set the pruning factor to 0, and set the minimum records in a split to 1, use:
MIndUtil -o iris.classify-opt -O SCHEMA=iris.schema \ -O DT_PRUNING_FACTOR=0 -O DT_LBOUND_MIN_SPLIT=1 |
This induces a larger tree for the iris dataset. Command-line options take precedence over environment variables and hard-coded defaults.
The order of command line arguments is important: Options to the right override earlier options to their left. Thus, the -O options override the values set in the iris.classify-opt file.
User input—If an option is required but the option was not set using any of the above levels in the hierarchy, you are prompted for the option, and you can type a value.
If you type ?, a help string appears to explain the meaning of the option. User input has the highest precedence and given values override command line options, environment variables, and hard-coded defaults.
A special environment variable, called PROMPTLEVEL, determines when to prompt the user for an option. The variable has three possible values:
Required-only prompts you for required options only. There are no prompts for options with a hard-coded default value. This is the lowest level prompting mode and the default.
Basic prompts you for basic options (each option is hard-coded as basic or not), whether or not they have a default value. Some options are defined as “nuisance” (non-basic) options and are not prompted for by this mode. The purpose of this mode is to prompt for the most commonly used options.
If the option has a default, you can change it to be a nuisance option by setting the option value to an exclamation mark (“!”). A nuisance option can be changed to a non-nuisance option by setting its value to be a question mark (“?”). For example, you can type:
setenv PROMPTLEVEL basic MIndUtil -o iris.classify-opt -O DT_MAX_LEVEL="?" |
You now are prompted for most options (non-nuisance) with defaults taken from iris.classify-opt. To accept the default, press Enter. Since SCHEMA is not defined in iris.classify-opt and is a required option, you are prompted for SCHEMA without a default. DT_MAX_LEVEL is a nuisance option, but setting it to a question mark specifies to prompt for it.
All prompts you for all options, regardless of their nuisance setting.
When MIndUtil is executed from Tool Manager, all options except the schema filename are passed from the client through an options file <file>.classify-opt. On the server, the DataMover invokes MIndUtil with the options file and the appropriate schema file.
Tool Manager prepends any options it finds in .mineset-classopt on the client workstation. The file is searched first in the current directory, then in the home directory. The first one found is used.
When an option requires one of a given set of values (for instance, an enumerated option), a prefix of the desired option value can be used, and comparison is case-insensitive. If there are multiple values with the given prefix, the first one in the list is chosen. For example, the first option in MIndUtil is MODE, which takes on one of the following values: induce, train-and-test, estimate-accuracy, discretize, auto-select, compute-importance, mineset-to-mlc, mlc-to-mineset, or visualize. Setting the option to “i” selects induce. In scripts, use the full option name for future compatibility.
To facilitate repeat runs of a program under the same options, these can be put in a file. The file must be in a format that can be sourced by csh or tcsh. The name of the file can be set through the environment variable OPTION_DUMP. For example, if your .login contains the statement
setenv OPTION_DUMP ~/.mindoptions |
the options from the last run are stored in ~/.mindoptions.
To repeat a previous run, simply source the dump file; for example,
source ~/.mindoptions
Note that the file is generated as you input options. This means you can source the file from csh or tcsh to get the options you have already filled in manually, even if you aborted the run.
MIndUtil is written using MLC++, the machine learning library in C++ (see http://www.sgi.com/Technology/mlc). More options can be used for those familiar with MLC++. Here are the important ones shared by many modes.
All filename specifications require the file suffix, except where detailed below.
MODE is an enumerated option containing one of the following: induce, train-and-test, estimate-accuracy, discretize, auto-select, compute-importance, mineset-to-mlc, mlc-to-mineset, or visualize.
Induce builds a classifier using all the data.
Train-and-test splits the data into a training set and a test set; a classifier is built from the training set and evaluated on the test set.
Estimate-accuracy performs cross-validation to estimate the accuracy of a classifier built using the induce option.
Discretize allows discretizing continuous attributes.
Auto-select allows finding a set of important attributes together with prespecified attributes.
Compute-importance computes the importance of each attribute as if it were used individually with a prespecified set of attributes.
MineSet-to-MLC and MLC-to-MineSet allow converting files from MLC++ format to MineSet format and vice versa.
Visualize allows converting a classifier to a visualization.
The modes are detailed in the next section.
SCHEMA is a string defining the MineSet schema file to use. The file specification must be complete (that is, with the .schema extension). (See “Using MineSet With Existing Data Files” in Chapter 2 for a description of schema files.)
LABEL is the name of the column or attribute that is to be used as the label whenever it is needed. The label name must be one of the columns in the schema file.
DISC_TYPE is an enumerated option taking on the value binning or entropy. This determines the discretization mode. binning invokes uniform binning, while entropy invokes “automatic” binning that is nonuniform (see “The Bin Column Button” in Chapter 3). The default is entropy.
MIN_SPLIT is an integer specifying the minimum number of instances that must be in each bucket when discretization is being done.
LOGLEVEL is an integer >= 0 defining the amount of logging information to print during the run. The default is zero. This option is hidden; you are not prompted for it.
DRIBBLE is a Boolean operation defining whether to dribble output during processing in order to show progress. The default is TRUE. This option is hidden; you are not prompted for it.
LINE_WIDTH is an integer > 1 defining the line width for the output. Automatic wrapping occurs to break words before this width. Wrapped lines begin with the WRAP_PREFIX string. The default line width is 79. This option is hidden; you are not prompted for it.
This section describes the options for induction modes, induce and train-and-test. The induce mode induces a classifier using the whole dataset. The train-and-test mode induces a classifier on a portion of the dataset and tests it on a holdout set. The modes require specifying an INDUCER option, which is either decision-tree or evidence. Options shared by both inducers in train-and-test mode are:
VIZ_NAME is a string defining the visualization name whenever appropriate. For the decision tree inducer, this fully specified filename is the name of the configuration file (recommended suffix is .treeviz) and a suffix of .data is automatically added to the data file needed. For the evidence inducer, only one filename is needed (recommended suffix is .eviviz).
CLASSIFIER_NAME is a string defining the classifier name whenever appropriate.
DISP_CONFUSION_MAT is a Boolean defining whether to display a confusion matrix, showing the distribution of mistakes for one class against another. This is a rudimentary ASCII display.
TRAIN_FRACTION is a floating point number between 0 and 1. It determines what ratio of the records to use as a training set. The rest are used as a test set. The default is two-thirds.
The option shared by both inducers under both induce and train-and-test modes is:
ACC_EST_SEED is an integer serving as the seed for the random-number generator used to split the records into training and test sets.
The following options are available for decision trees (INDUCER = decision-tree):
DT_MAX_LEVEL, an integer >=0, limits the number of levels to grow the decision tree. The default of zero implies no limit.
DT_PRUNING_FACTOR, a floating point number >=0, determines the pruning factor. The default of zero implies no pruning (Tool Manager defaults to a pruning factor of 0.85).
DT_LBOUND_MIN_SPLIT, an integer, provides a lower bound on the number of records required to trickle down to at least two branches in a given node. No split will be made otherwise. The default is 1 (Tool Manager defaults to 5).
DT_MIN_SPLIT_WEIGHT, a floating point number >=0, is the minimum ratio of training records divided by the number of classes that are required to trickle down to at least two branches in a given node. The default is 0 (Tool Manager defaults to 0.1).
DT_SPLIT_BY is an enumerated option taking one of the following values: mutual-info, normalized-mutual-info, gain-ratio. It specifies the evaluation criterion for choosing the attribute to split on at every node (see Chapter 9 for details). The default is normalized-mutual-info.
DT_ADJUST_THRESHOLDS is a Boolean operator determining whether splits on continuous attributes have thresholds that are midpoints between two data points or whether the thresholds should be actual data values. The default is FALSE (that is, not to adjust the thresholds to data values).
This option is useful when you want to avoid splits on fractional values if attributes take on only integer values.
The following options are available for the evidence inducer (INDUCER = evidence):
EVI_LAPLACE_CORRECTION, a Boolean determining whether to apply the Laplace correction (see Chapter 10). The default is false.
EVI_FSS, a Boolean determining whether to apply feature subset selection (see Chapter 10). The default is false.
If the MODE is estimate-accuracy, cross-validation will be performed. The following options are available:
All other options are the same as for the induction modes.
If MODE is discretize, discretization of attributes is performed and thresholds are determined. The following options are available:
OUTPUT_NAME is the name of the file to contain the results.
ATTR_X, where X starts at 0 and increases. This defines the names of the attributes that you would like discretized.
BINS_X, where X starts at 0 and increases. This specifies the number of bins to discretize ATTR_X into. Note that this is an upper bound and entropy binning may choose a lower number of bins. If the number of bins is zero, automatic heuristics are used.
Example: A discretization of two attributes, petal width and petal length, according to label iris_type, such that the number of bins is automatically determined can be done using the following options:
MODE=discretize LABEL=iris_type ATTR_0=petal_length BINS_0=0 ATTR_1=petal_width BINS_1=0 DISC_TYPE=entropy MIN_SPLIT=5 OUTPUT_NAME=iris.disc |
If MODE is auto-select or compute-importance, corresponding to the Find Importance and Compute Importance modes in the Tool Manager's Column Importance, the following options are available:
OUTPUT_NAME is the name of the file to contain the results.
ATTR_X, where X starts at 0 and increases. This defines the names of preselected attributes. All other attributes are candidates for auto-selection or are ranked if column importance is chosen.
SELECT_N, an integer that determines the number of attributes to automatically select in auto-select mode, which corresponds to the non-Advanced mode and the advanced “find...” mode in column importance in the Tool Manager.
Example: To choose three attributes that can be used together with petal_width to classify iris_type, the following options can be used:
MODE=auto-select LABEL=iris_type SELECT_N=3 ATTR_0=petal_length DISC_TYPE=entropy MIN_SPLIT=5 OUTPUT_NAME=feature.fss |
In this example and the one in the “Discretization” section, the discretization mode was entropy and the minimum number of instances in a bin was set to 5.
These modes provide facilities to convert from MLC++ format to MineSet format and vice versa. They can be used to convert UC Irvine (http://www.ics.uci.edu/~mlearn/MLRepository.html) formatted files or C4.5 formatted files, which are common in the machine learning community.
MineSet-to-MLC provides the following options:
SPLIT_TRAIN_TEST, whether to split the data into two files: a training set and a test set.
MLCFILE, the filename to export to. Suffixes of .names, .data, and .test are appended to this stem if SPLIT_TRAIN_TEST is true; otherwise, the suffixes are .names and .all. You can then run MLC++ inducers on these files, independent of MineSet.
MLC-to-MineSet provides the following options:
DATAFILE, the file to import. If no suffix is given, it is assumed to be .data. It is recommended that you concatenate the training and test sets into a .all file and use that for importing.
NAMESFILE, the names file describing the DATAFILE. A reasonable default is automatically suggested based on the DATAFILE option.
OUTPUT_DATA, a MineSet output file. This should have a .data suffix.
OUTPUT_SCHEMA, a MineSet schema file. This should have a .schema suffix.
OUTPUT_LABEL, a string indicating what name to use for the label attribute.
REMOVE_UNKNOWN_INST, a Boolean option indicating whether to remove records that have attributes with unknown values. The default is FALSE.
This mode lets you generate visualization files from classifiers. The following options are available:
CLASSIFIER_NAME is the name of the classifier, including the file suffix.
VIZ_NAME is a string defining the visualization name. For the decision tree inducer, this fully specified file name will be the name of the configuration file (recommended suffix is .treeviz) and a suffix of .data will be automatically added to the data file needed. For the evidence inducer, only one file name is needed (recommended suffix is .eviviz).