BBR (Java Statistical Analysis Tool 0.0.8 API)

java.lang.Object
- jsat.classifiers.linear.BBR

All Implemented Interfaces:

Serializable, Cloneable, Classifier, Parameterized, SimpleWeightVectorModel, SingleWeightVectorModel
```
public class BBR
extends Object
implements Classifier, Parameterized, SingleWeightVectorModel
```
This is an implementation of Bayesian Binary Regression for L₁ and L₂ regularized logistic regression. This model requires additional memory to perform efficient column wise passes on the data set, assuming the data is sparse.

BBR uses a Trust Region Newton algorithm that allows convergence to occur in a small number of iterations, but each iteration may be costly.

See: Genkin, A., Lewis, D. D.,&Madigan, D. (2007). Large-Scale Bayesian Logistic Regression for Text Categorization. Technometrics, 49(3), 291–304. doi:10.1198/004017007000000245

Author:

Edward Raff

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class BBR.Prior
Valid priors that control what type of regularization is applied

Nested Classes
Modifier and Type	Class and Description
`static class`	`BBR.Prior` Valid priors that control what type of regularization is applied

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`BBR(BBR toCopy)` Copy constructor
	`BBR(double regularization, int maxIterations)` Creates a new BBR for L₁ Logistic Regression object that will use the given regularization value.
	`BBR(double regularization, int maxIterations, BBR.Prior prior)` Creates a new BBR Logistic Regression object that will use the given regularization value.
	`BBR(int maxIterations)` Creates a new BBR for L₁ Logistic Regression object that will attempt to automatically determine the regularization value to use.
	`BBR(int maxIterations, BBR.Prior prior)` Creates a new BBR Logistic Regression object that will attempt to automatically determine the regularization value to use.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CategoricalResults`	`classify(DataPoint data)` Performs classification on the given data point.
`BBR`	`clone()`
`double`	`getBias()` Returns the bias term used for the model, or 0 of the model does not support or was not trained with a bias term.
`double`	`getBias(int index)` Returns the bias term used with the weight vector for the given class index.
`int`	`getMaxIterations()` Returns the maximum number of iterations allowed
`Parameter`	`getParameter(String paramName)` Returns the parameter with the given name.
`List<Parameter>`	`getParameters()` Returns the list of parameters that can be altered for this learner.
`BBR.Prior`	`getPrior()` Returns the regularizing prior in use
`Vec`	`getRawWeight()` Returns the only weight vector used for the model
`Vec`	`getRawWeight(int index)` Returns the raw weight vector associated with the given class index.
`double`	`getRegularization()` Returns the regularization penalty used if the auto value is not used
`double`	`getTolerance()` Returns the tolerance parameter that controls convergence
`Vec`	`getWeightVec()` Returns the weight vector used to compute results via a dot product.
`boolean`	`isAutoSetRegularization()` Returns whether or not the algorithm will attempt to select the regularization term automatically
`boolean`	`isUseBias()` Returns `true` if a bias term is in use, `false` otherwise.
`int`	`numWeightsVecs()` Returns the number of weight vectors that can be returned.
`void`	`setAutoSetRegularization(boolean autoSetRegularization)` Sets whether or not the regularization term will be set automatically by the algorithm, which is done as specified in the original paper.
`void`	`setMaxIterations(int maxIterations)` Sets the maximum number of iterations allowed before halting the algorithm early.
`void`	`setPrior(BBR.Prior prior)` Sets the regularizing prior used
`void`	`setRegularization(double regularization)` Sets the regularization penalty to use if the algorithm has not been set to choose one automatically.
`void`	`setTolerance(double tolerance)` Sets the convergence tolerance target.
`void`	`setUseBias(boolean useBias)` Sets whether or not an implicit bias term should be added to the model.
`boolean`	`supportsWeightedData()` Indicates whether the model knows how to train using weighted data points.
`void`	`trainC(ClassificationDataSet dataSet)` Trains the classifier and constructs a model for classification using the given data set.
`void`	`trainC(ClassificationDataSet dataSet, ExecutorService threadPool)` Trains the classifier and constructs a model for classification using the given data set.

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

- Constructor Detail
  - BBR
```
public BBR(double regularization,
           int maxIterations)
```
    Creates a new BBR for L₁ Logistic Regression object that will use the given regularization value.
    
    Parameters:
    
    regularization - the regularization penalty to apply
    
    maxIterations - the maximum number of training iterations to perform
  - BBR
```
public BBR(double regularization,
           int maxIterations,
           BBR.Prior prior)
```
    Creates a new BBR Logistic Regression object that will use the given regularization value.
    
    Parameters:
    
    regularization - the regularization penalty to apply
    
    maxIterations - the maximum number of training iterations to perform
    
    prior - the prior to apply for regularization
  - BBR
```
public BBR(int maxIterations)
```
    Creates a new BBR for L₁ Logistic Regression object that will attempt to automatically determine the regularization value to use.
    
    Parameters:
    
    maxIterations - the maximum number of training iterations to perform
  - BBR
```
public BBR(int maxIterations,
           BBR.Prior prior)
```
    Creates a new BBR Logistic Regression object that will attempt to automatically determine the regularization value to use.
    
    Parameters:
    
    maxIterations - the maximum number of training iterations to perform
    
    prior - the prior to apply for regularization
  - BBR
```
protected BBR(BBR toCopy)
```
    Copy constructor
    
    Parameters:
    
    toCopy - the object to copy
- Method Detail
  - setRegularization
```
public void setRegularization(double regularization)
```
    Sets the regularization penalty to use if the algorithm has not been set to choose one automatically.
    
    Parameters:
    
    regularization - sets the positive regularization penalty to use
  - getRegularization
```
public double getRegularization()
```
    Returns the regularization penalty used if the auto value is not used
    
    Returns:
    
    the regularization penalty used if the auto value is not used
  - setAutoSetRegularization
```
public void setAutoSetRegularization(boolean autoSetRegularization)
```
    Sets whether or not the regularization term will be set automatically by the algorithm, which is done as specified in the original paper. This may choose a very large (and bad) value of the regularization term, and should not be used with smaller data sets. This value is chosen deterministically.
    
    This value takes precedence over anything set with setRegularization(double)
    
    Parameters:
    
    autoSetRegularization - true to choose the regularization term automatically, false to use whatever value was set before.
  - isAutoSetRegularization
```
public boolean isAutoSetRegularization()
```
    Returns whether or not the algorithm will attempt to select the regularization term automatically
    
    Returns:
    
    true if the regularization term is chosen automatically, false otherwise.
  - setMaxIterations
```
public void setMaxIterations(int maxIterations)
```
    Sets the maximum number of iterations allowed before halting the algorithm early.
    
    Parameters:
    
    maxIterations - the maximum number of training iterations
  - getMaxIterations
```
public int getMaxIterations()
```
    Returns the maximum number of iterations allowed
    
    Returns:
    
    the maximum number of iterations allowed
  - setTolerance
```
public void setTolerance(double tolerance)
```
    Sets the convergence tolerance target. Relative changes that are smaller than the given tolerance will determine convergence.
    
    The default value used is that suggested in the original paper of 0.0005
    
    Parameters:
    
    tolerance - the positive convergence tolerance goal
  - getTolerance
```
public double getTolerance()
```
    Returns the tolerance parameter that controls convergence
    
    Returns:
    
    the tolerance parameter that controls convergence
  - setUseBias
```
public void setUseBias(boolean useBias)
```
    Sets whether or not an implicit bias term should be added to the model.
    
    Parameters:
    
    useBias - true to add a bias term, false to exclude the bias term.
  - isUseBias
```
public boolean isUseBias()
```
    Returns true if a bias term is in use, false otherwise.
    
    Returns:
    
    true if a bias term is in use, false otherwise.
  - setPrior
```
public void setPrior(BBR.Prior prior)
```
    Sets the regularizing prior used
    
    Parameters:
    
    prior - the prior to use
  - getPrior
```
public BBR.Prior getPrior()
```
    Returns the regularizing prior in use
    
    Returns:
    
    the regularizing prior in use
  - getWeightVec
```
public Vec getWeightVec()
```
    Returns the weight vector used to compute results via a dot product.
    Do not modify this value, or you will alter the results returned.
    
    Returns:
    
    the learned weight vector for prediction
  - getRawWeight
```
public Vec getRawWeight()
```
    Description copied from interface: SingleWeightVectorModel
    
    Returns the only weight vector used for the model
    
    Specified by:
    
    getRawWeight in interface SingleWeightVectorModel
    
    Returns:
    
    the only weight vector used for the model
  - getBias
```
public double getBias()
```
    Description copied from interface: SingleWeightVectorModel
    
    Returns the bias term used for the model, or 0 of the model does not support or was not trained with a bias term.
    
    Specified by:
    
    getBias in interface SingleWeightVectorModel
    
    Returns:
    
    the bias term for the model
  - getRawWeight
```
public Vec getRawWeight(int index)
```
    Description copied from interface: SimpleWeightVectorModel
    
    Returns the raw weight vector associated with the given class index. If the given class is an implicit zero vector, a ConstantVector object may be returned.
    Do not alter the returned weight vector, as it will change the model's values.
    
    If a regression problem, only index = 0 should be used
    
    Specified by:
    
    getRawWeight in interface SimpleWeightVectorModel
    
    Parameters:
    
    index - the class index to get the weight vector for
    
    Returns:
    
    the weight vector used for the specified class
  - getBias
```
public double getBias(int index)
```
    Description copied from interface: SimpleWeightVectorModel
    
    Returns the bias term used with the weight vector for the given class index. If the model does not support or was not trained with bias weights, 0 will be returned.
    
    If a regression problem, only index = 0 should be used
    
    Specified by:
    
    getBias in interface SimpleWeightVectorModel
    
    Parameters:
    
    index - the class index to get the weight vector for
    
    Returns:
    
    the bias term for the specified class
  - numWeightsVecs
```
public int numWeightsVecs()
```
    Description copied from interface: SimpleWeightVectorModel
    
    Returns the number of weight vectors that can be returned. For binary classification problems the value may be 1 if only a single weight vector's sign is used to determine the class. For multi-class problems, the weight vector count includes the implicit zero vector (if one is being used).
    
    Specified by:
    
    numWeightsVecs in interface SimpleWeightVectorModel
    
    Returns:
    
    the number of weight vectors for which SimpleWeightVectorModel.getRawWeight(int) can be called.
  - classify
```
public CategoricalResults classify(DataPoint data)
```
    Description copied from interface: Classifier
    
    Performs classification on the given data point.
    
    Specified by:
    
    classify in interface Classifier
    
    Parameters:
    
    data - the data point to classify
    
    Returns:
    
    the results of the classification.
  - trainC
```
public void trainC(ClassificationDataSet dataSet,
                   ExecutorService threadPool)
```
    Description copied from interface: Classifier
    
    Trains the classifier and constructs a model for classification using the given data set. If the training method knows how, it will used the threadPool to conduct training in parallel. This method will block until the training has completed.
    
    Specified by:
    
    trainC in interface Classifier
    
    Parameters:
    
    dataSet - the data set to train on
    
    threadPool - the source of threads to use.
  - trainC
```
public void trainC(ClassificationDataSet dataSet)
```
    Description copied from interface: Classifier
    
    Trains the classifier and constructs a model for classification using the given data set.
    
    Specified by:
    
    trainC in interface Classifier
    
    Parameters:
    
    dataSet - the data set to train on
  - supportsWeightedData
```
public boolean supportsWeightedData()
```
    Description copied from interface: Classifier
    
    Indicates whether the model knows how to train using weighted data points. If it does, the model will train assuming the weights. The values returned by this method may change depending on the parameters set for the model.
    
    Specified by:
    
    supportsWeightedData in interface Classifier
    
    Returns:
    
    true if the model supports weighted data, false otherwise
  - clone
```
public BBR clone()
```
    Specified by:
    
    clone in interface Classifier
    
    Overrides:
    
    clone in class Object
  - getParameters
```
public List<Parameter> getParameters()
```
    Description copied from interface: Parameterized
    
    Returns the list of parameters that can be altered for this learner.
    
    Specified by:
    
    getParameters in interface Parameterized
    
    Returns:
    
    the list of parameters that can be altered for this learner.
  - getParameter
```
public Parameter getParameter(String paramName)
```
    Description copied from interface: Parameterized
    
    Returns the parameter with the given name. Two different strings may map to a single Parameter object. An ASCII only string, and a Unicode style string.
    
    Specified by:
    
    getParameter in interface Parameterized
    
    Parameters:
    
    paramName - the name of the parameter to obtain
    
    Returns:
    
    the Parameter in question, or null if no such named Parameter exists.

Class BBR

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

BBR

BBR

BBR

BBR

BBR

Method Detail

setRegularization

getRegularization

setAutoSetRegularization

isAutoSetRegularization

setMaxIterations

getMaxIterations

setTolerance

getTolerance

setUseBias

isUseBias

setPrior

getPrior

getWeightVec

getRawWeight

getBias

getRawWeight

getBias

numWeightsVecs

classify

trainC

trainC

supportsWeightedData

clone

getParameters

getParameter