org.mymedialite.ratingprediction
Class MatrixFactorization

java.lang.Object
  extended by org.mymedialite.ratingprediction.RatingPredictor
      extended by org.mymedialite.ratingprediction.IncrementalRatingPredictor
          extended by org.mymedialite.ratingprediction.MatrixFactorization
All Implemented Interfaces:
java.lang.Cloneable, IIterativeModel, IRecommender, IIncrementalRatingPredictor, IRatingPredictor
Direct Known Subclasses:
BiasedMatrixFactorization

public class MatrixFactorization
extends IncrementalRatingPredictor
implements IIterativeModel

Simple matrix factorization class, learning is performed by stochastic gradient descent. Factorizing the observed rating values using a factor matrix for users and one for items. NaN values in the model occur if values become too large or too small to be represented by the type double. If you encounter such problems, there are three ways to fix them: (1) (preferred) Use BiasedMatrixFactorization, which is more stable. (2) Change the range of rating values (1 to 5 works generally well with the default settings). (3) Change the learn_rate (decrease it if your range is larger than 1 to 5). This recommender supports incremental updates.


Field Summary
protected  double globalBias
          The bias (global average).
 double initMean
          Mean of the normal distribution used to initialize the factors.
 double initStDev
          Standard deviation of the normal distribution used to initialize the factors.
protected  Matrix<java.lang.Double> itemFactors
          Matrix containing the latent item factors.
 double learnRate
          Learn rate.
 int numFactors
          Number of latent factors.
 int numIter
          Number of iterations over the training data.
 double regularization
          Regularization parameter.
protected  Matrix<java.lang.Double> userFactors
          Matrix containing the latent user factors.
 
Fields inherited from class org.mymedialite.ratingprediction.IncrementalRatingPredictor
updateItems, updateUsers
 
Fields inherited from class org.mymedialite.ratingprediction.RatingPredictor
maxItemID, maxRating, maxUserID, minRating, ratings
 
Constructor Summary
MatrixFactorization()
          Default constructor.
 
Method Summary
 void addItem(int item_id)
           
 void addRating(int user_id, int item_id, double rating)
          Add a new rating and perform incremental training
 void addUser(int user_id)
           
 double computeLoss()
          Compute the regularized loss.
 int getNumIter()
          Get the number of iterations to run the training
protected  void initModel()
          Initialize the model data structure.
 void iterate()
          Run one iteration (= pass over the training data)
protected  void iterate(java.util.List<java.lang.Integer> rating_indices, boolean update_user, boolean update_item)
          Iterate once over rating data and adjust corresponding factors (stochastic gradient descent).
 void loadModel(java.lang.String filename)
          Get the model parameters from a file
 double predict(int user_id, int item_id)
          Predict the rating of a given user for a given item.
protected  double predict(int user_id, int item_id, boolean bound)
           
 void removeItem(int item_id)
          Remove an item from the recommender model, and delete all ratings of this item It is up to the recommender implementor whether there should be model updates after this action, both options are valid.
 void removeRating(int user_id, int item_id)
          Remove an existing rating and perform "incremental" training
 void removeUser(int user_id)
          Remove a user from the recommender model, and delete all their ratings It is up to the recommender implementor whether there should be model updates after this action, both options are valid.
 void retrainItem(int item_id)
          Updates the latent factors of an item.
 void retrainUser(int user_id)
          Updates the latent factors on a user.
 void saveModel(java.lang.String filename)
          Save the model parameters to a file
 void setNumIter(int num_iter)
          Set the number of iterations to run the training
 java.lang.String toString()
          Return a string representation of the recommender
 void train()
          Learn the model parameters of the recommender from the training data
 void updateRating(int user_id, int item_id, double rating)
          Update an existing rating and perform incremental training
 
Methods inherited from class org.mymedialite.ratingprediction.IncrementalRatingPredictor
getUpdateItems, getUpdateUsers, setUpdateItems, setUpdateUsers
 
Methods inherited from class org.mymedialite.ratingprediction.RatingPredictor
canPredict, clone, getMaxRating, getMinRating, getRatings, setMaxRating, setMinRating, setRatings
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.mymedialite.ratingprediction.IRatingPredictor
getMaxRating, getMinRating, setMaxRating, setMinRating
 
Methods inherited from interface org.mymedialite.IRecommender
canPredict
 

Field Detail

userFactors

protected Matrix<java.lang.Double> userFactors
Matrix containing the latent user factors.


itemFactors

protected Matrix<java.lang.Double> itemFactors
Matrix containing the latent item factors.


globalBias

protected double globalBias
The bias (global average).


initMean

public double initMean
Mean of the normal distribution used to initialize the factors.


initStDev

public double initStDev
Standard deviation of the normal distribution used to initialize the factors.


numFactors

public int numFactors
Number of latent factors.


learnRate

public double learnRate
Learn rate.


regularization

public double regularization
Regularization parameter.


numIter

public int numIter
Number of iterations over the training data.

Constructor Detail

MatrixFactorization

public MatrixFactorization()
Default constructor.

Method Detail

setNumIter

public void setNumIter(int num_iter)
Description copied from interface: IIterativeModel
Set the number of iterations to run the training

Specified by:
setNumIter in interface IIterativeModel

getNumIter

public int getNumIter()
Description copied from interface: IIterativeModel
Get the number of iterations to run the training

Specified by:
getNumIter in interface IIterativeModel

initModel

protected void initModel()
Initialize the model data structure.


train

public void train()
Description copied from interface: IRecommender
Learn the model parameters of the recommender from the training data

Specified by:
train in interface IRecommender
Specified by:
train in class RatingPredictor

iterate

public void iterate()
Description copied from interface: IIterativeModel
Run one iteration (= pass over the training data)

Specified by:
iterate in interface IIterativeModel

retrainUser

public void retrainUser(int user_id)
Updates the latent factors on a user.

Parameters:
user_id - the user ID

retrainItem

public void retrainItem(int item_id)
Updates the latent factors of an item.

Parameters:
item_id - the item ID

iterate

protected void iterate(java.util.List<java.lang.Integer> rating_indices,
                       boolean update_user,
                       boolean update_item)
Iterate once over rating data and adjust corresponding factors (stochastic gradient descent).

Parameters:
rating_indices - a list of indices pointing to the ratings to iterate over
update_user - true if user factors to be updated
update_item - true if item factors to be updated

predict

protected double predict(int user_id,
                         int item_id,
                         boolean bound)

predict

public double predict(int user_id,
                      int item_id)
Predict the rating of a given user for a given item. If the user or the item are not known to the recommender, the global average is returned. To avoid this behavior for unknown entities, use CanPredict() to check before.

Specified by:
predict in interface IRecommender
Specified by:
predict in class RatingPredictor
Parameters:
user_id - the user ID
item_id - the item ID
Returns:
the predicted rating

addRating

public void addRating(int user_id,
                      int item_id,
                      double rating)
Description copied from interface: IIncrementalRatingPredictor
Add a new rating and perform incremental training

Specified by:
addRating in interface IIncrementalRatingPredictor
Overrides:
addRating in class IncrementalRatingPredictor
Parameters:
user_id - the ID of the user who performed the rating
item_id - the ID of the rated item
rating - the rating value

updateRating

public void updateRating(int user_id,
                         int item_id,
                         double rating)
Description copied from interface: IIncrementalRatingPredictor
Update an existing rating and perform incremental training

Specified by:
updateRating in interface IIncrementalRatingPredictor
Overrides:
updateRating in class IncrementalRatingPredictor
Parameters:
user_id - the ID of the user who performed the rating
item_id - the ID of the rated item
rating - the rating value

removeRating

public void removeRating(int user_id,
                         int item_id)
Description copied from interface: IIncrementalRatingPredictor
Remove an existing rating and perform "incremental" training

Specified by:
removeRating in interface IIncrementalRatingPredictor
Overrides:
removeRating in class IncrementalRatingPredictor
Parameters:
user_id - the ID of the user who performed the rating
item_id - the ID of the rated item

addUser

public void addUser(int user_id)
Overrides:
addUser in class IncrementalRatingPredictor

addItem

public void addItem(int item_id)
Overrides:
addItem in class IncrementalRatingPredictor

removeUser

public void removeUser(int user_id)
Description copied from interface: IIncrementalRatingPredictor
Remove a user from the recommender model, and delete all their ratings It is up to the recommender implementor whether there should be model updates after this action, both options are valid.

Specified by:
removeUser in interface IIncrementalRatingPredictor
Overrides:
removeUser in class IncrementalRatingPredictor
Parameters:
user_id - the ID of the user to be removed

removeItem

public void removeItem(int item_id)
Description copied from interface: IIncrementalRatingPredictor
Remove an item from the recommender model, and delete all ratings of this item It is up to the recommender implementor whether there should be model updates after this action, both options are valid.

Specified by:
removeItem in interface IIncrementalRatingPredictor
Overrides:
removeItem in class IncrementalRatingPredictor
Parameters:
item_id - the ID of the user to be removed

saveModel

public void saveModel(java.lang.String filename)
               throws java.io.IOException
Description copied from interface: IRecommender
Save the model parameters to a file

Specified by:
saveModel in interface IRecommender
Specified by:
saveModel in class RatingPredictor
Parameters:
filename - the file to write to
Throws:
java.io.IOException

loadModel

public void loadModel(java.lang.String filename)
               throws java.io.IOException
Description copied from interface: IRecommender
Get the model parameters from a file

Specified by:
loadModel in interface IRecommender
Specified by:
loadModel in class RatingPredictor
Parameters:
filename - the file to read from
Throws:
java.io.IOException

computeLoss

public double computeLoss()
Compute the regularized loss.

Specified by:
computeLoss in interface IIterativeModel
Returns:
the regularized loss

toString

public java.lang.String toString()
Description copied from interface: IRecommender
Return a string representation of the recommender

Specified by:
toString in interface IRecommender
Overrides:
toString in class RatingPredictor
Returns:
the class name and all hyperparameters, separated by space characters.