PredictiveModel (JMSL Numerical Library)

java.lang.Object
- com.imsl.datamining.PredictiveModel

All Implemented Interfaces:

Serializable, Cloneable

Direct Known Subclasses:

DecisionTree
```
public abstract class PredictiveModel
extends Object
implements Serializable, Cloneable
```
Predictive model class. This class defines the members and methods common to predictive models in univariate prediction or classification problems.

See Also:
Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`PredictiveModel.PredictiveModelException` An exception class intended to be the parent of all nested Exception classes where the enclosing class extends `PredictiveModel`.
`static class`	`PredictiveModel.StateChangeException` Exception thrown when an input parameter has changed that might affect the model estimates or predictions.
`static class`	`PredictiveModel.SumOfProbabilitiesNotOneException` Exception thrown when the sum of probabilities is not approximately one.
`static class`	`PredictiveModel.VariableType` An enumeration of data types/characteristics.

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`PredictiveModel(double[][] xy, int responseColumnIndex, PredictiveModel.VariableType[] varType)` Constructs a `PredictiveModel` object for a single response variable and multiple predictor variables.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`fitModel()` Fits the predictive model to the training data (estimates the model using the training data and current configuration settings).
`double[]`	`getClassCounts()` Returns the counts of each class (level) of the categorical response variable.
`double[][]`	`getCostMatrix()` Returns the cost matrix for a categorical response variable.
`int`	`getMaxNumberOfCategories()` Returns the maximum number of categorical variables allowed.
`int`	`getNumberOfClasses()` Returns the number of unique classes found in the categorical response data.
`int`	`getNumberOfColumns()` Returns the number of columns in `xy`.
`int`	`getNumberOfMissing()` Returns the number of missing values of the response variable found in the data `xy`.
`int`	`getNumberOfPredictors()` Returns the number of predictors.
`int`	`getNumberOfRows()` Returns the number of rows in `xy` (observations).
`int[]`	`getNumberOfUniquePredictorValues()` Returns an array containing the number of distinct values of each categorical or ordinal predictor found in the input data.
`int[]`	`getPredictorIndexes()` Returns an array of indices into `xy` where the predictor variables reside.
`PredictiveModel.VariableType[]`	`getPredictorTypes()` Returns an array of `VariableType` objects that correspond to the predictor data types in `xy`.
`int`	`getPrintLevel()` Returns the current print level.
`double[]`	`getPriorProbabilities()` Returns an array containing the prior probabilities.
`int`	`getResponseColumnIndex()` Returns the column index in `xy` containing the response variable.
`double`	`getResponseVariableAverage()` Returns the weighted average value of the response variable.
`int`	`getResponseVariableMostFrequentClass()` Returns the most frequent value of the response variable.
`PredictiveModel.VariableType`	`getResponseVariableType()` Returns the variable type of the response variable.
`double`	`getTotalWeight()` Returns the sum of the active case weights.
`PredictiveModel.VariableType[]`	`getVariableType()` Returns an array containing the variable types in `xy`.
`double[]`	`getWeights()` Returns an array containing the case weights.
`double[][]`	`getXY()` Returns a copy of the `xy` data.
`boolean`	`isMustFitModelFlag()` Returns the current value of the `mustFitModel` flag.
`boolean`	`isUserFixedNClasses()` Returns `true` if the number of classes was fixed by the user.
`abstract double[]`	`predict()` Predicts the response variable using the most recent fit.
`abstract double[]`	`predict(double[][] testData)` Predicts the response values using the most recent fit and the provided test data.
`abstract double[]`	`predict(double[][] testData, double[] testDataWeights)` Predicts the response values using the most recent fit, the provided test data, and the test data case weights.
`void`	`setClassCounts(double[] classCounts)` Sets the counts of each class of the response variable.
`protected abstract void`	`setConfiguration(PredictiveModel pm)` Sets the configuration of `PredictiveModel` to that of the input model.
`void`	`setCostMatrix(double[][] costMatrix)` Specifies the cost matrix for a categorical response variable.
`void`	`setMaxNumberOfCategories(int maxCategories)` Sets the maximum number of categories allowed within categorical predictor variables.
`void`	`setNumberOfClasses(int nClasses)` Sets the number of distinct classes of the response variable.
`void`	`setPredictorIndex(int[] predIdx)` Sets the array of indices into `xy` where the predictor variables reside.
`void`	`setPredictorTypes(PredictiveModel.VariableType[] predVarType)` Sets the `VariableType` objects that correspond to the predictor data types in `xy`.
`void`	`setPrintLevel(int printLevel)` Sets a print level that determines the information printed for a `PredictiveModel`.
`void`	`setPriorProbabilities(double[] priors)` Set the prior probabilities for class membership.
`void`	`setWeights(double[] weights)` Specifies the case weights.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - PredictiveModel
```
protected PredictiveModel(double[][] xy,
               int responseColumnIndex,
               PredictiveModel.VariableType[] varType)
```
    Constructs a PredictiveModel object for a single response variable and multiple predictor variables.
    This constructor should be called by all classes extending PredictiveModel.
    
    Parameters:
    xy - a double matrix that is a number of observations by the number of variables.
    responseColumnIndex - an int specifying the column index of the response variable.
    varType - a PredictiveModel.VariableType array of length equal to xy[0].length containing the type of each variable.
- Method Detail
  - fitModel
```
public void fitModel()
              throws PredictiveModel.PredictiveModelException
```
    Fits the predictive model to the training data (estimates the model using the training data and current configuration settings).
    Each PredictiveModel subclass must override and call this method.
    
    Throws:
    
    PredictiveModel.PredictiveModelException - an exception has occurred in the common PredictiveModel methods. Implementing or overriding methods from this class may require that exceptions be thrown. Exceptions thrown from these methods will necessarily extend the PredictiveModelException.
  - getClassCounts
```
public double[] getClassCounts()
```
    Returns the counts of each class (level) of the categorical response variable.
    If the response variable is not PredictiveModel.VariableType.CATEGORICAL nor PredictiveModel.VariableType.ORDERED_DISCRETE, null is returned.
    
    Returns:
    a double array containing the summation of the case weights for each occurrence of a particular class found in the categorical response data.
  - getCostMatrix
```
public double[][] getCostMatrix()
```
    Returns the cost matrix for a categorical response variable.
    The cost matrix has elements C(i, j) = cost of misclassifying a response in class j as in class i. The diagonal elements of the cost matrix must be 0. In the case that nClasses has not been determined (usually because fitModel() has not been called), an array of length zero is returned.
    
    Returns:
    a square double matrix of dimension nClasses by nClasses containing the cost matrix for a categorical response variable, where nClasses is the number of classes the response variable may assume.
  - getMaxNumberOfCategories
```
public int getMaxNumberOfCategories()
```
    Returns the maximum number of categorical variables allowed.
    
    Returns:
    an int indicating the maximum number of categorical variables allowed.
  - getNumberOfClasses
```
public int getNumberOfClasses()
```
    Returns the number of unique classes found in the categorical response data.
    
    Returns:
    an int indicating the number of unique classes found in the categorical response data.
  - getNumberOfColumns
```
public int getNumberOfColumns()
```
    Returns the number of columns in xy.
    
    Returns:
    an int that indicates the number of columns.
  - getNumberOfMissing
```
public int getNumberOfMissing()
```
    Returns the number of missing values of the response variable found in the data xy.
    
    Returns:
    an int indicating the number of missing values.
  - getNumberOfPredictors
```
public int getNumberOfPredictors()
```
    Returns the number of predictors.
    
    Returns:
    an int equal to the number of predictors.
  - getNumberOfRows
```
public int getNumberOfRows()
```
    Returns the number of rows in xy (observations).
    
    Returns:
    an int equal to the number of rows in xy (observations).
  - getNumberOfUniquePredictorValues
```
public int[] getNumberOfUniquePredictorValues()
```
    Returns an array containing the number of distinct values of each categorical or ordinal predictor found in the input data.
    For predictors with PredictiveModel.VariableType.QUANTITATIVE_CONTINUOUS, the value is set to 0 but is not meaningful.
    
    Returns:
    an int array containing the number of distinct values.
  - getPredictorIndexes
```
public int[] getPredictorIndexes()
```
    Returns an array of indices into xy where the predictor variables reside.
    
    Returns:
    an int array containing indices into xy where the predictor variables reside.
  - getPredictorTypes
```
public PredictiveModel.VariableType[] getPredictorTypes()
```
    Returns an array of VariableType objects that correspond to the predictor data types in xy.
    
    Returns:
    a VariableType array that corresponds to the predictor data types in xy.
  - getPrintLevel
```
public int getPrintLevel()
```
    Returns the current print level.
    
    Returns:
    an int indicating the current print level.
    
    printLevel Action
    
    0 No printing.
    
    1 Prints final results only.
    
    2 Prints intermediate and final results.
    
    Default: printLevel = 0.
  - getPriorProbabilities
```
public double[] getPriorProbabilities()
```
    Returns an array containing the prior probabilities.
    
    Returns:
    a double array containing the prior probabilities.
  - getResponseColumnIndex
```
public int getResponseColumnIndex()
```
    Returns the column index in xy containing the response variable.
    
    Returns:
    an int specifying the column index for the response variable.
  - getResponseVariableAverage
```
public double getResponseVariableAverage()
```
    Returns the weighted average value of the response variable.
    
    Returns:
    a double equal to the weighted average value.
  - getResponseVariableMostFrequentClass
```
public int getResponseVariableMostFrequentClass()
```
    Returns the most frequent value of the response variable. Only meaningful for VariableType.CATEGORICAL or VariableType.ORDERED_DISCRETE.
    
    Returns:
    an int equal to the average value.
  - getResponseVariableType
```
public PredictiveModel.VariableType getResponseVariableType()
```
    Returns the variable type of the response variable.
    
    Returns:
    the VariableType of the response variable.
  - getTotalWeight
```
public double getTotalWeight()
```
    Returns the sum of the active case weights.
    
    Returns:
    a double indicating the sum of the active case weights.
  - getVariableType
```
public PredictiveModel.VariableType[] getVariableType()
```
    Returns an array containing the variable types in xy.
    
    Returns:
    a VariableType array containing the variable types in xy.
  - getWeights
```
public double[] getWeights()
```
    Returns an array containing the case weights.
    
    Returns:
    a double array containing the case weights.
  - getXY
```
public double[][] getXY()
```
    Returns a copy of the xy data.
    
    Returns:
    a double matrix containing the training data.
  - isMustFitModelFlag
```
public boolean isMustFitModelFlag()
```
    Returns the current value of the mustFitModel flag.
    When true, the fitModel() method should be called before doing any predictions or other analysis.
    
    Returns:
    a boolean value indicating the state of the flag.
  - isUserFixedNClasses
```
public boolean isUserFixedNClasses()
```
    Returns true if the number of classes was fixed by the user.
    
    Returns:
    a boolean value indicating whether or not the number of classes has been fixed by the user.
  - predict
```
public abstract double[] predict()
                          throws PredictiveModel.PredictiveModelException
```
    Predicts the response variable using the most recent fit.
    Each PredictiveModel subclass must override this method.
    
    Returns:
    a double array containing the predicted values.
    
    Throws:
    
    PredictiveModel.PredictiveModelException - an exception has occurred in the common PredictiveModel methods. Implementing or overriding methods from this class may require that exceptions be thrown. Exceptions thrown from these methods will necessarily extend the PredictiveModelException.
  - predict
```
public abstract double[] predict(double[][] testData)
                          throws PredictiveModel.PredictiveModelException
```
    Predicts the response values using the most recent fit and the provided test data.
    Each PredictiveModel subclass must override this method.
    
    Parameters:
    testData - a double matrix containing data to be predicted. testData must have the same number of columns and in the same arrangement as xy (the observations).
    
    Returns:
    a double array containing the predicted values.
    
    Throws:
    
    PredictiveModel.PredictiveModelException - an exception has occurred in the common PredictiveModel methods. Implementing or overriding methods from this class may require that exceptions be thrown. Exceptions thrown from these methods will necessarily extend the PredictiveModelException.
  - predict
```
public abstract double[] predict(double[][] testData,
               double[] testDataWeights)
                          throws PredictiveModel.PredictiveModelException
```
    Predicts the response values using the most recent fit, the provided test data, and the test data case weights.
    Each PredictiveModel subclass must override this method.
    
    Parameters:
    testData - double matrix containing data to be predicted. testData must have the same number of columns and in the same arrangement as xy (the observations).
    testDataWeights - a double array containing weights for each row of testData.
    
    Returns:
    a double array containing the predicted values.
    
    Throws:
    
    PredictiveModel.PredictiveModelException - an exception has occurred in the common PredictiveModel methods. Implementing or overriding methods from this class may require that exceptions be thrown. Exceptions thrown from these methods will necessarily extend the PredictiveModelException.
  - setClassCounts
```
public void setClassCounts(double[] classCounts)
```
    Sets the counts of each class of the response variable.
    Use this method to set the class counts, when one or more classes do not occur in the training data due to sampling, but are otherwise valid, or when the data is distributed and the global counts are available. Only applies when the response variable is of type PredictiveModel.VariableType.CATEGORICAL or PredictiveModel.VariableType.ORDERED_DISCRETE.
    
    Parameters:
    classCounts - a double array containing the class counts of the response variable.
    The default is to use the class counts discovered in the input matrix, xy, weighted by the values in weights.
  - setConfiguration
```
protected abstract void setConfiguration(PredictiveModel pm)
                                  throws PredictiveModel.PredictiveModelException
```
    Sets the configuration of PredictiveModel to that of the input model.
    The implementation should include model-specific input methods (subclass methods) that must necessarily be set. An example would be problem-specific constraints such as tree depth for a DecisionTree in an ensemble prediction algorithm (see BootstrapAggregation). Here DecisionTree.setMaxDepth(int) is called within this overridden method to constrain the permuted trees to the same maximum dimensions.
    
    Each PredictiveModel subclass must override this method.
    
    Parameters:
    pm - a PredictiveModel object.
    
    Throws:
    
    PredictiveModel.PredictiveModelException - an exception class intended to be the parent of all nested Exception classes where the enclosing class extends PredictiveModel.
  - setCostMatrix
```
public void setCostMatrix(double[][] costMatrix)
```
    Specifies the cost matrix for a categorical response variable.
    
    Parameters:
    costMatrix - a square double matrix of dimension nClasses by nClasses containing elements C(i, j), the cost of misclassifying a response in class j as in class i. The diagonal elements of the cost matrix must be 0.
    Both dimensions of costMatrix should agree with the number of classes found in the data. Otherwise an exception will be thrown.
    
    Default: costMatrix[i][j]=1.0 where and costMatrix[i][i]=0.0.
  - setMaxNumberOfCategories
```
public void setMaxNumberOfCategories(int maxCategories)
```
    Sets the maximum number of categories allowed within categorical predictor variables.
    
    Parameters:
    maxCategories - an int specifying the maximum number of categories a predictor variable can have.
    Default: maxCategories=10
  - setNumberOfClasses
```
public void setNumberOfClasses(int nClasses)
```
    Sets the number of distinct classes of the response variable. Only applies when the response variable is of type PredictiveModel.VariableType.CATEGORICAL or PredictiveModel.VariableType.ORDERED_DISCRETE.
    
    Parameters:
    nClasses - an int representing the number of distinct classes or categories of the response variable.
    An error is generated if more than nClasses categories are discovered in the data.
    
    Default: nClasses is 0.
  - setPredictorIndex
```
public void setPredictorIndex(int[] predIdx)
```
    Sets the array of indices into xy where the predictor variables reside.
    This may be used to subset the full set of predictor variables (getPredictorTypes()).
    
    Parameters:
    predIdx - an int array containing the column index for each predictor variable. Default: All columns other than the column containing the response variable are indicated.
  - setPredictorTypes
```
public void setPredictorTypes(PredictiveModel.VariableType[] predVarType)
```
    Sets the VariableType objects that correspond to the predictor data types in xy.
    
    Parameters:
    predVarType - a VariableType array of length equal to the number of predictors specifying the data type of each predictor.
  - setPrintLevel
```
public void setPrintLevel(int printLevel)
```
    Sets a print level that determines the information printed for a PredictiveModel.
    
    Parameters:
    printLevel - An int specifying the level of printing to perform.
    
    printLevel Action
    
    0 No printing.
    
    1 Prints final results only.
    
    2 Prints intermediate and final results.
    
    Default: printLevel = 0.
  - setPriorProbabilities
```
public void setPriorProbabilities(double[] priors)
                           throws PredictiveModel.SumOfProbabilitiesNotOneException
```
    Set the prior probabilities for class membership.
    
    Parameters:
    priors - a double array specifying the prior probabilities of class membership for each class.
    The prior probabilities must range between 0.0 and 1.0 inclusive, and sum to 1.0. The length of priors should agree with the number of classes found in the data. Otherwise an exception is thrown. Calling this method overwrites any existing values.
    
    Default: Determined from the data.
    
    Throws:
    
    PredictiveModel.SumOfProbabilitiesNotOneException - prior probabilities must sum to 1.0.
  - setWeights
```
public void setWeights(double[] weights)
```
    Specifies the case weights.
    
    Parameters:
    weights - a double array specifying case weights.
    Default: weights[i] = 1.0 for all i.

printLevel	Action
0	No printing.
1	Prints final results only.
2	Prints intermediate and final results.

Class PredictiveModel

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

PredictiveModel

Method Detail

fitModel

getClassCounts

getCostMatrix

getMaxNumberOfCategories

getNumberOfClasses

getNumberOfColumns

getNumberOfMissing

getNumberOfPredictors

getNumberOfRows

getNumberOfUniquePredictorValues

getPredictorIndexes

getPredictorTypes

getPrintLevel

getPriorProbabilities

getResponseColumnIndex

getResponseVariableAverage

getResponseVariableMostFrequentClass

getResponseVariableType

getTotalWeight

getVariableType

getWeights

getXY

isMustFitModelFlag

isUserFixedNClasses

predict

predict

predict

setClassCounts

setConfiguration

setCostMatrix

setMaxNumberOfCategories

setNumberOfClasses

setPredictorIndex

setPredictorTypes

setPrintLevel

setPriorProbabilities

setWeights