gov.sandia.cognition.learning.algorithm.factor.machine

Class AbstractFactorizationMachineLearner

java.lang.Object

gov.sandia.cognition.util.AbstractCloneableSerializable

gov.sandia.cognition.algorithm.AbstractIterativeAlgorithm

gov.sandia.cognition.algorithm.AbstractAnytimeAlgorithm<ResultType>

gov.sandia.cognition.learning.algorithm.AbstractAnytimeBatchLearner<java.util.Collection<? extends InputOutputPair<? extends InputType,OutputType>>,ResultType>

gov.sandia.cognition.learning.algorithm.AbstractAnytimeSupervisedBatchLearner<Vector,java.lang.Double,FactorizationMachine>

gov.sandia.cognition.learning.algorithm.factor.machine.AbstractFactorizationMachineLearner

All Implemented Interfaces:

AnytimeAlgorithm<FactorizationMachine>, IterativeAlgorithm, MeasurablePerformanceAlgorithm, StoppableAlgorithm, AnytimeBatchLearner<java.util.Collection<? extends InputOutputPair<? extends Vector,java.lang.Double>>,FactorizationMachine>, BatchLearner<java.util.Collection<? extends InputOutputPair<? extends Vector,java.lang.Double>>,FactorizationMachine>, SupervisedBatchLearner<Vector,java.lang.Double,FactorizationMachine>, CloneableSerializable, Randomized, java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

FactorizationMachineAlternatingLeastSquares, FactorizationMachineStochasticGradient

public abstract class AbstractFactorizationMachineLearner
extends AbstractAnytimeSupervisedBatchLearner<Vector,java.lang.Double,FactorizationMachine>
implements Randomized, MeasurablePerformanceAlgorithm

An abstract class for learning FactorizationMachines. It defines the common parameters for learning algorithms and how to initialize the factorization machine for learning.

Since:

3.4.0

Author:

Justin Basilico

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	biasEnabled True if the bias term is enabled.
protected double	biasRegularization The regularization term for the bias.
static boolean	DEFAULT_BIAS_ENABLED The default for bias enabled is true.
static double	DEFAULT_BIAS_REGULARIZATION The default bias regularization parameter is 0.0.
static int	DEFAULT_FACTOR_COUNT The default number of factors is 10.
static double	DEFAULT_FACTOR_REGULARIZATION The default factor regularization parameter is 0.01.
static int	DEFAULT_MAX_ITERATIONS The default maximum number of iterations is 100.
static double	DEFAULT_SEED_SCALE The default seed initialization scale is 0.01.
static double	DEFAULT_WEIGHT_REGULARIZATION The default weight regularization parameter is 0.001.
static boolean	DEFAULT_WEIGHTS_ENABLED The default for weights enabled is true.
protected int	dimensionality The dimensionality of the input to the factorization machine.
protected int	factorCount The number of factors to use.
protected double	factorRegularization The regularization term for the factor matrix.
protected java.util.Random	random The random number generator to use.
protected FactorizationMachine	result The current factorization machine output learned by the algorithm.
protected double	seedScale The standard deviation for initializing the factors.
protected double	weightRegularization The regularization term for the linear weights.
protected boolean	weightsEnabled True if the linear weight term is enabled.

Fields inherited from class gov.sandia.cognition.learning.algorithm.AbstractAnytimeBatchLearner

data, keepGoing

Fields inherited from class gov.sandia.cognition.algorithm.AbstractAnytimeAlgorithm

maxIterations

Fields inherited from class gov.sandia.cognition.algorithm.AbstractIterativeAlgorithm

DEFAULT_ITERATION, iteration

Constructor Summary

Constructors

Constructor and Description
AbstractFactorizationMachineLearner() Creates a new AbstractFactorizationMachineLearner.
AbstractFactorizationMachineLearner(int factorCount, double biasRegularization, double weightRegularization, double factorRegularization, double seedScale, int maxIterations, java.util.Random random) Creates a new AbstractFactorizationMachineLearner.

Method Summary

Modifier and Type	Method and Description
double	getBiasRegularization() Gets the value for the parameter controlling the bias regularization.
int	getFactorCount() Gets the number of factors.
double	getFactorRegularization() Gets the value for the parameter controlling the factor matrix regularization.
java.util.Random	getRandom() Gets the random number generator used by this object.
FactorizationMachine	getResult() Gets the current result of the algorithm.
double	getSeedScale() Gets the seed initialization scale.
double	getWeightRegularization() Gets the value for the parameter controlling the linear weight regularization.
protected boolean	initializeAlgorithm() Called to initialize the learning algorithm's state based on the data that is stored in the data field.
boolean	isBiasEnabled() Gets whether or not the bias term is enabled.
boolean	isFactorsEnabled() Gets whether or not the factors are enabled.
boolean	isWeightsEnabled() Gets whether or not the linear weight term is enabled.
void	setBiasEnabled(boolean biasEnabled) Sets whether or not the bias term is enabled.
void	setBiasRegularization(double biasRegularization) Sets the value for the parameter controlling the bias regularization.
void	setFactorCount(int factorCount) Sets the number of factors.
void	setFactorRegularization(double factorRegularization) Sets the value for the parameter controlling the factor matrix regularization.
void	setRandom(java.util.Random random) Sets the random number generator used by this object.
void	setSeedScale(double seedScale) Sets the seed initialization scale.
void	setWeightRegularization(double weightRegularization) Sets the value for the parameter controlling the linear weight regularization.
void	setWeightsEnabled(boolean weightsEnabled) Sets whether or not the linear weight term is enabled.

Methods inherited from class gov.sandia.cognition.learning.algorithm.AbstractAnytimeBatchLearner

cleanupAlgorithm, clone, getData, getKeepGoing, learn, setData, setKeepGoing, step, stop

Methods inherited from class gov.sandia.cognition.algorithm.AbstractAnytimeAlgorithm

getMaxIterations, isResultValid, setMaxIterations

Methods inherited from class gov.sandia.cognition.algorithm.AbstractIterativeAlgorithm

addIterativeAlgorithmListener, fireAlgorithmEnded, fireAlgorithmStarted, fireStepEnded, fireStepStarted, getIteration, getListeners, removeIterativeAlgorithmListener, setIteration, setListeners

Methods inherited from class java.lang.Object

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

Methods inherited from interface gov.sandia.cognition.algorithm.MeasurablePerformanceAlgorithm

getPerformance

Methods inherited from interface gov.sandia.cognition.learning.algorithm.BatchLearner

learn

Methods inherited from interface gov.sandia.cognition.util.CloneableSerializable

clone

Methods inherited from interface gov.sandia.cognition.algorithm.AnytimeAlgorithm

getMaxIterations, setMaxIterations

Methods inherited from interface gov.sandia.cognition.algorithm.IterativeAlgorithm

addIterativeAlgorithmListener, getIteration, removeIterativeAlgorithmListener

Methods inherited from interface gov.sandia.cognition.algorithm.StoppableAlgorithm

isResultValid

Field Detail

DEFAULT_FACTOR_COUNT

public static final int DEFAULT_FACTOR_COUNT

The default number of factors is 10.

See Also:

Constant Field Values

DEFAULT_BIAS_ENABLED

public static final boolean DEFAULT_BIAS_ENABLED

The default for bias enabled is true.

See Also:

Constant Field Values

DEFAULT_WEIGHTS_ENABLED

public static final boolean DEFAULT_WEIGHTS_ENABLED

The default for weights enabled is true.

See Also:

Constant Field Values

DEFAULT_BIAS_REGULARIZATION

public static final double DEFAULT_BIAS_REGULARIZATION

The default bias regularization parameter is 0.0.

See Also:

Constant Field Values

DEFAULT_WEIGHT_REGULARIZATION

public static final double DEFAULT_WEIGHT_REGULARIZATION

The default weight regularization parameter is 0.001.

See Also:

Constant Field Values

DEFAULT_FACTOR_REGULARIZATION

public static final double DEFAULT_FACTOR_REGULARIZATION

The default factor regularization parameter is 0.01.

See Also:

Constant Field Values

DEFAULT_SEED_SCALE

public static final double DEFAULT_SEED_SCALE

The default seed initialization scale is 0.01.

See Also:

Constant Field Values

DEFAULT_MAX_ITERATIONS

public static final int DEFAULT_MAX_ITERATIONS

The default maximum number of iterations is 100.

See Also:

Constant Field Values

biasEnabled

protected boolean biasEnabled

True if the bias term is enabled.

weightsEnabled

protected boolean weightsEnabled

True if the linear weight term is enabled.

factorCount

protected int factorCount

The number of factors to use. Zero means no factors.

biasRegularization

protected double biasRegularization

The regularization term for the bias. Cannot be negative.

weightRegularization

protected double weightRegularization

The regularization term for the linear weights. Cannot be negative.

factorRegularization

protected double factorRegularization

The regularization term for the factor matrix. Cannot be negative.

seedScale

protected double seedScale

The standard deviation for initializing the factors. Cannot be negative.

random

protected java.util.Random random

The random number generator to use.

result

protected transient FactorizationMachine result

The current factorization machine output learned by the algorithm.

dimensionality

protected transient int dimensionality

The dimensionality of the input to the factorization machine.

Constructor Detail

AbstractFactorizationMachineLearner

public AbstractFactorizationMachineLearner()

Creates a new AbstractFactorizationMachineLearner.

AbstractFactorizationMachineLearner

public AbstractFactorizationMachineLearner(int factorCount,
                                           double biasRegularization,
                                           double weightRegularization,
                                           double factorRegularization,
                                           double seedScale,
                                           int maxIterations,
                                           java.util.Random random)

Creates a new AbstractFactorizationMachineLearner.

Parameters:

factorCount - The number of factors to use. Zero means no factors. Cannot be negative.

biasRegularization - The regularization term for the bias. Cannot be negative.

weightRegularization - The regularization term for the linear weights. Cannot be negative.

factorRegularization - The regularization term for the factor matrix. Cannot be negative.

seedScale - The random initialization scale for the factors. Multiplied by a random Gaussian to initialize each factor value. Cannot be negative.

maxIterations - The maximum number of iterations for the algorithm to run. Cannot be negative.

random - The random number generator.

Method Detail

initializeAlgorithm

protected boolean initializeAlgorithm()

Description copied from class: AbstractAnytimeBatchLearner

Called to initialize the learning algorithm's state based on the data that is stored in the data field. The return value indicates if the algorithm can be run or not based on the initialization.

Specified by:

initializeAlgorithm in class AbstractAnytimeBatchLearner<java.util.Collection<? extends InputOutputPair<? extends Vector,java.lang.Double>>,FactorizationMachine>

Returns:

True if the learning algorithm can be run and false if it cannot.

getResult

public FactorizationMachine getResult()

Description copied from interface: AnytimeAlgorithm

Gets the current result of the algorithm.

Specified by:

getResult in interface AnytimeAlgorithm<FactorizationMachine>

Returns:

Current result of the algorithm.

getFactorCount

public int getFactorCount()

Gets the number of factors. The factors are used to represent the pairwise interaction between dimensions in the input vector.

Returns:

The number of factors to use. Zero means no factors. Cannot be negative.

setFactorCount

public void setFactorCount(int factorCount)

Sets the number of factors. The factors are used to represent the pairwise interaction between dimensions in the input vector.

Parameters:

factorCount - The number of factors to use. Zero means no factors. Cannot be negative.

isBiasEnabled

public boolean isBiasEnabled()

Gets whether or not the bias term is enabled. If it is not enabled, it will default to zero and not be updated.

Returns:

True if the bias term is enabled, otherwise false.

setBiasEnabled

public void setBiasEnabled(boolean biasEnabled)

Sets whether or not the bias term is enabled. If it is not enabled, it will default to zero and not be updated.

Parameters:

biasEnabled - True if the bias term is enabled, otherwise false.

isWeightsEnabled

public boolean isWeightsEnabled()

Gets whether or not the linear weight term is enabled. If it is not enabled, it will default to a zero vector and not be updated.

Returns:

True if the linear term is enabled, otherwise false.

setWeightsEnabled

public void setWeightsEnabled(boolean weightsEnabled)

Sets whether or not the linear weight term is enabled. If it is not enabled, it will default to a zero vector and not be updated.

Parameters:

weightsEnabled - True if the linear term is enabled, otherwise false.

isFactorsEnabled

public boolean isFactorsEnabled()

Gets whether or not the factors are enabled. This is true when the number of factors is greater than zero.

Returns:

True if the number of factors is greater than zero, otherwise false.

getBiasRegularization

public double getBiasRegularization()

Gets the value for the parameter controlling the bias regularization.

Returns:

The regularization term for the bias. Cannot be negative.

setBiasRegularization

public void setBiasRegularization(double biasRegularization)

Sets the value for the parameter controlling the bias regularization.

Parameters:

biasRegularization - The regularization term for the bias. Cannot be negative.

getWeightRegularization

public double getWeightRegularization()

Gets the value for the parameter controlling the linear weight regularization.

Returns:

The regularization term for the weights. Cannot be negative.

setWeightRegularization

public void setWeightRegularization(double weightRegularization)

Sets the value for the parameter controlling the linear weight regularization.

Parameters:

weightRegularization - The regularization term for the weights. Cannot be negative.

getFactorRegularization

public double getFactorRegularization()

Gets the value for the parameter controlling the factor matrix regularization.

Returns:

The regularization term for the factors. Cannot be negative.

setFactorRegularization

public void setFactorRegularization(double factorRegularization)

Sets the value for the parameter controlling the factor matrix regularization.

Parameters:

factorRegularization - The regularization term for the factors. Cannot be negative.

getSeedScale

public double getSeedScale()

Gets the seed initialization scale. It is multiplied by a random Gaussian to initialize each factor value.

Returns:

The random initialization scale for the factors. Cannot be negative.

setSeedScale

public void setSeedScale(double seedScale)

Sets the seed initialization scale. It is multiplied by a random Gaussian to initialize each factor value.

Parameters:

seedScale - The random initialization scale for the factors. Cannot be negative.

getRandom

public java.util.Random getRandom()

Description copied from interface: Randomized

Gets the random number generator used by this object.

Specified by:

getRandom in interface Randomized

Returns:

The random number generator used by this object.

setRandom

public void setRandom(java.util.Random random)

Description copied from interface: Randomized

Sets the random number generator used by this object.

Specified by:

setRandom in interface Randomized

Parameters:

random - The random number generator for this object to use.