magpie.models

Class BaseModel

java.lang.Object

magpie.models.BaseModel

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Citable, Commandable, Options, Printable, Savable

Direct Known Subclasses:

BaseClassifier, BaseRegression, SplitModel

public abstract class BaseModel
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable, Options, Printable, Commandable, Savable, Citable

Base class for any model, regression or classification.

All models support the ability to filter training data, normalize attributes, and select attributes before model training (in that order).

Implementation Guide

Operations that must be implemented:

• clone() - Fulfills java.lang.Cloneable, ValidationStats and TrainingStats must be new instances. And, you probably want to create a new instance of any submodels
• train_protected(magpie.data.Dataset) - Trains the model on a training set, does not set TrainingStats
• run_protected(magpie.data.Dataset) - Run a model on a Dataset
• printModel_protected() and printModelDescriptionDetails(boolean) - Print detailed and simple descriptions of the model

Implemented Commands:

clone - Create a copy of this model

train $<dataset> - Train model using measured class values
dataset: Dataset used to train this model

output = crossvalidate $<dataset> [<folds>] - Use k-fold cross-validation to assess model performance.
dataset: Dataset to use for cross validation
folds: Number of cross validation folds (default = 10)
output: Dataset, result of used to compute performance statistics
Splits dataset into folds parts. Trains model on folds - 1 parts, validates against remaining part. Repeats using each part as the validation set.

output = crossvalidate $<dataset> <split size>> [<n repeats>] - Cross-validation by splitting dataset into train and test sets. Test is repeated multiple times
dataset: Dataset to use for cross validation
folds: Fraction of entries used in test set
n repeats: Number of times to repeat test
output: Dataset, result of used to compute performance statistics
Same command structure as k-fold cross-validation. Runs if the number of folds is less than 1.

run $<dataset> - Use model to predict class values for each entry
dataset: Dataset to evaluate

validate $<dataset> - Validate model against external dataset
dataset - Dataset to use for validate

set selector $<selector> - Define the BaseAttributeSelector used to screen attributes before training
selector: Attribute selector to use

set selector $<filter> - Define the BaseDatasetFilter used to filter data before attribute normalization, attribute selection, and model training.
filter: Filter to use

normalize [attributes] [class] <method> [<options...>] - Define how to normalize data (data is not normalized by default)
attributes: Whether to normalize attributes
class: Whether to normalize class variable
method: Method used to normalize attributes
options...: Any options for the normalizer

Implemented Print Commands

description - Print out short description of this model.

model - Print out the model

validation [<command>] - Print out statistics generated during validation
command: Command to be passed to internal BaseStatistics object.

training [<command>] - Print out statistics generated during training
command: Command to be passed to internal BaseStatistics object.

selector - Print out attributes used selected by internal BaseAttributeSelector, if defined

Implemented Save Commands

training - Print out performance data for training set

validation - Print out performance data for validation set

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected BaseAttributeSelector	AttributeSelector BaseAttributeSelector used to screen attributes during training
protected boolean	trained Records whether model has been trained
BaseStatistics	TrainingStats Statistics about performance on training set
protected boolean	validated Records whether model has been validated
BaseStatistics	ValidationStats Statistics generated during model validation

Constructor Summary

Constructors

Constructor and Description
BaseModel()

Method Summary

Modifier and Type	Method and Description
java.lang.String	about() Prints a simple status message about this object
BaseModel	clone()
Dataset	crossValidate(double testFraction, int nRepeats, Dataset data, long seed) Run a cross-validation test where the dataset is randomly partitioned into a training and test set.
Dataset	crossValidate(int folds, Dataset cvData) Perform k-fold cross validation
Dataset	crossValidate(int folds, Dataset cvData, long seed) Perform k-fold cross validation
void	done() Run if done with a model, clears any external resources.
void	externallyValidate(Dataset testData) Use external testing data to validate a model (should not contain any data used to train the model)
BaseAttributeSelector	getAttributeSelector() Return the BaseAttributeSelector used by this model
java.util.List<org.apache.commons.lang3.tuple.Pair<java.lang.String,Citation>>	getCitations() Return a list of citations for this object and any underlying objects.
BaseDatasetFilter	getFilter() Get filter used before training
java.util.Date	getTrainTime() Return when this model was trained
java.lang.String	getValidationMethod() Get a description of how this model was validated
void	handleSetCommand(java.util.List<java.lang.Object> Command) Handle setting components of a model via the command interface
boolean	isTrained()
boolean	isValidated()
static BaseModel	loadState(java.lang.String filename) Read the state from file using serialization
java.lang.String	printCommand(java.util.List<java.lang.String> Command) Handles more complicated printing commands.
java.lang.String	printDescription(boolean htmlFormat) Print full name of object, and a simple description of the options.
protected abstract java.lang.String	printModel_protected() Internal method that handles printing the model as a string.
java.lang.String	printModel() If a model is trained, return it formatted as a string.
protected java.util.List<java.lang.String>	printModelDescriptionDetails(boolean htmlFormat) Print details of the model.
void	resetModel() Mark this model as untrained and unvalidated
abstract void	run_protected(Dataset TrainData) Run a model without checking if stuff is trained (use carefully)
void	run(Dataset runData) Run a model on provided data.
java.lang.Object	runCommand(java.util.List<java.lang.Object> command) Process some command described by a list of Objects.
java.lang.String	saveCommand(java.lang.String Basename, java.lang.String Format) Handles complicated saving commands.
void	saveState(java.lang.String filename) Save the state of this object using serialization
void	setAttributeSelector(BaseAttributeSelector AttributeSelector) Define an attribute selector that will force this model to only use a subset of the attributes supplied with a Dataset
void	setComponent(java.lang.String Name, java.lang.Object Object) Set a specific component of a model
void	setFilter(BaseDatasetFilter filter) Set filter used to clean data before training
protected abstract void	train_protected(Dataset TrainData) Train a model without evaluating performance
void	train(Dataset TrainingData) Train a model on a specified training set and then evaluate performance on the training set.
void	train(Dataset data, boolean recordStats) Train a model on a specified training set and then evaluate performance on the training set, if desired

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface magpie.utility.interfaces.Options

printUsage, setOptions

Field Detail

TrainingStats

public BaseStatistics TrainingStats

Statistics about performance on training set

ValidationStats

public BaseStatistics ValidationStats

Statistics generated during model validation

trained

protected boolean trained

Records whether model has been trained

validated

protected boolean validated

Records whether model has been validated

AttributeSelector

protected BaseAttributeSelector AttributeSelector

BaseAttributeSelector used to screen attributes during training

Constructor Detail

BaseModel

public BaseModel()

Method Detail

loadState

public static BaseModel loadState(java.lang.String filename)
                           throws java.lang.Exception

Read the state from file using serialization

Parameters:

filename - Filename for input

Returns:

Model stored in that file

Throws:

java.lang.Exception - If parsing fails

isTrained

public boolean isTrained()

Returns:

Whether this model has been trained

getTrainTime

public java.util.Date getTrainTime()

Return when this model was trained

Returns:

When starting was started if this model is trained, null otherwise

isValidated

public boolean isValidated()

Returns:

Whether any sort of validation has been run on this model

resetModel

public void resetModel()

Mark this model as untrained and unvalidated

getAttributeSelector

public BaseAttributeSelector getAttributeSelector()

Return the BaseAttributeSelector used by this model

Returns:

Link to the BaseAttributeSelector object

setAttributeSelector

public void setAttributeSelector(BaseAttributeSelector AttributeSelector)

Define an attribute selector that will force this model to only use a subset of the attributes supplied with a Dataset

Parameters:

AttributeSelector - Untrained BaseAttributeSelector

getFilter

public BaseDatasetFilter getFilter()

Get filter used before training

Returns:

Link to internal filter object

setFilter

public void setFilter(BaseDatasetFilter filter)

Set filter used to clean data before training

Parameters:

filter - Desired filter

crossValidate

public Dataset crossValidate(int folds,
                             Dataset cvData)

Perform k-fold cross validation

Parameters:

folds - Number of folds in CV test

cvData - Data to use for CV

Returns:

Clone of input dataset. Class variable is the predicted value of the model used when computing CV statistics

crossValidate

public Dataset crossValidate(int folds,
                             Dataset cvData,
                             long seed)

Perform k-fold cross validation

Parameters:

folds - Number of folds in CV test

cvData - Data to use for CV

seed - Random seed used when splitting dataset

Returns:

Clone of input dataset. Class variable is the predicted value of the model used when computing CV statistics

crossValidate

public Dataset crossValidate(double testFraction,
                             int nRepeats,
                             Dataset data,
                             long seed)

Run a cross-validation test where the dataset is randomly partitioned into a training and test set.

For data with a discrete class, we ensure that the distribution of classes in the train and test set are the same.

Parameters:

testFraction - Fraction entries in the test sets

nRepeats - Number of times test is repeated

data - Dataset used for cross-validation

seed - Random seed

Returns:

Results from the cross-validation tests

externallyValidate

public void externallyValidate(Dataset testData)

Use external testing data to validate a model (should not contain any data used to train the model)

Parameters:

testData - External test dataset

getValidationMethod

public java.lang.String getValidationMethod()

Get a description of how this model was validated

Returns:

Validation technique if model has been validated. "Unvalidated" otherwise.

train

public void train(Dataset TrainingData)

Train a model on a specified training set and then evaluate performance on the training set. Results from running model on training set will be stored as the predicted class for entries in TrainingData.

Parameters:

TrainingData - Dataset used for training

train

public void train(Dataset data,
                  boolean recordStats)

Train a model on a specified training set and then evaluate performance on the training set, if desired

Parameters:

data - Dataset to use for training

recordStats - Whether to record training statistics

run

public void run(Dataset runData)

Run a model on provided data. Results will be stored as the predicted class variable.

Parameters:

runData - Dataset to evaluate.

saveState

public void saveState(java.lang.String filename)
               throws java.lang.Exception

Save the state of this object using serialization

Parameters:

filename - Filename for output

Throws:

java.lang.Exception

clone

public BaseModel clone()

Overrides:

clone in class java.lang.Object

train_protected

protected abstract void train_protected(Dataset TrainData)

Train a model without evaluating performance

Parameters:

TrainData - Training data

run_protected

public abstract void run_protected(Dataset TrainData)

Run a model without checking if stuff is trained (use carefully)

Parameters:

TrainData - Training data

about

public java.lang.String about()

Description copied from interface: Printable

Prints a simple status message about this object

Specified by:

about in interface Printable

Returns:

Short status message

printModel

public java.lang.String printModel()

If a model is trained, return it formatted as a string.

Returns:

Model formatted as string

printModel_protected

protected abstract java.lang.String printModel_protected()

Internal method that handles printing the model as a string. Should end with a "\n"

Returns:

String representation of model

printDescription

public java.lang.String printDescription(boolean htmlFormat)

Description copied from interface: Printable

Print full name of object, and a simple description of the options. This description should print enough information to reproduce how this object was created, but not necessarily enough to run it (e.g., coefficients for the model).

Example: For a model training a separate WekaRegression for intermetallics

magpie.models.regression.SplitRegression

Splitter: AllMetalsSplitter
All Metals: magpie.models.regression.WekaRegression trees.REPTree
Contains Nonmetal: magpie.regression.LASSORegreession -maxterms 2

Specified by:

printDescription in interface Printable

Parameters:

htmlFormat - Whether format for output to an HTML page (e.g., <div> to create indentation) or for printing to screen.

Returns:

String describing the model

See Also:

#printModel()

printModelDescriptionDetails

protected java.util.List<java.lang.String> printModelDescriptionDetails(boolean htmlFormat)

Print details of the model. Used by printDescription(boolean).

Implementation note: No not add indentation for details. That is handled by printDescription(boolean). You should also call the super operation to get the Normalizer and Attribute selector settings

Parameters:

htmlFormat - Whether to use HTML format

Returns:

List describing model details. Each entry is a different line of the description (i.e., in place of newline characters).

printCommand

public java.lang.String printCommand(java.util.List<java.lang.String> Command)
                              throws java.lang.Exception

Description copied from interface: Printable

Handles more complicated printing commands.

Specified by:

printCommand in interface Printable

Parameters:

Command - Command specifying what to print

Returns:

String formatted as requested

Throws:

java.lang.Exception - If command not understood

runCommand

public java.lang.Object runCommand(java.util.List<java.lang.Object> command)
                            throws java.lang.Exception

Description copied from interface: Commandable

Process some command described by a list of Objects.

Specified by:

runCommand in interface Commandable

Parameters:

command - Command as a list of objects

Returns:

Any output (null if no output generated by command)

Throws:

java.lang.Exception - If something goes wrong

handleSetCommand

public void handleSetCommand(java.util.List<java.lang.Object> Command)
                      throws java.lang.Exception

Handle setting components of a model via the command interface

Parameters:

Command - Command to be executed.

Throws:

java.lang.Exception

setComponent

public void setComponent(java.lang.String Name,
                         java.lang.Object Object)
                  throws java.lang.Exception

Set a specific component of a model

Parameters:

Name - Name of component

Object - Instance of component (will be cloned)

Throws:

java.lang.Exception

saveCommand

public java.lang.String saveCommand(java.lang.String Basename,
                                    java.lang.String Format)
                             throws java.lang.Exception

Description copied from interface: Savable

Handles complicated saving commands.

Dev Note: Make sure to add save format to Javadoc. See Dataset as an example. Required format:

<save><p><b>format<b> - Description
<br>Optional room to talk more about format </save>

Specified by:

saveCommand in interface Savable

Parameters:

Basename - Name of file without extension

Format - Command specifying format in which to print

Returns:

Filename Path to output file

Throws:

java.lang.Exception - If command not understood

getCitations

public java.util.List<org.apache.commons.lang3.tuple.Pair<java.lang.String,Citation>> getCitations()

Description copied from interface: Citable

Return a list of citations for this object and any underlying objects.

Specified by:

getCitations in interface Citable

Returns:

List of pairs: [Reason for Citation], [Citation]

done

public void done()

Run if done with a model, clears any external resources. For example, closes the external server for ExternalModel.