org.mymedialite.itemrec
Class BPRMF

java.lang.Object
  extended by org.mymedialite.itemrec.ItemRecommender
      extended by org.mymedialite.itemrec.IncrementalItemRecommender
          extended by org.mymedialite.itemrec.MF
              extended by org.mymedialite.itemrec.BPRMF
All Implemented Interfaces:
java.lang.Cloneable, IIterativeModel, IRecommender, IIncrementalItemRecommender
Direct Known Subclasses:
SoftMarginRankingMF, WeightedBPRMF

public class BPRMF
extends MF

Matrix factorization model for item prediction (ranking) optimized using BPR. BPR reduces ranking to pairwise classification. Literature: Steffen Rendle, Christoph Freudenthaler, Zeno Gantner, Lars Schmidt-Thieme: BPR: Bayesian Personalized Ranking from Implicit Feedback. UAI 2009. http://www.ismll.uni-hildesheim.de/pub/pdfs/Rendle_et_al2009-Bayesian_Personalized_Ranking.pdf Different sampling strategies are configurable by setting the uniformUserSampling and withReplacement accordingly. To get the strategy from the original paper, set uniformUserSampling=false and withReplacement=false. withReplacement=true (default) gives you usually a slightly faster convergence, and uniformUserSampling=true (default) (approximately) optimizes the average AUC over all users. This recommender supports incremental updates.


Field Summary
 double biasReg
          Regularization parameter for the bias term
 boolean boldDriver
          Use bold driver heuristics for learning rate adaption.
protected  boolean fastSampling
          Fast, but memory-intensive sampling
 int fastSamplingMemoryLimit
          Fast sampling memory limit, in MiB TODO find out why fast sampling does not improve performance
protected  double[] itemBias
          Item bias terms
 double learnRate
          Learning rate alpha
protected  Random random
          Random number generator
 double regI
          Regularization parameter for positive item factors
 double regJ
          Regularization parameter for negative item factors
 double regU
          Regularization parameter for user factors
 boolean uniformUserSampling
          Sample uniformly from users
protected  boolean updateJ
          If set (default), update factors for negative sampled items during learning
protected  java.util.ArrayList<int[]> userNegItems
          Support data structure for fast sampling
protected  java.util.ArrayList<int[]> userPosItems
          Support data structure for fast sampling
 boolean withReplacement
          Sample positive observations with (true) or without (false) replacement
 
Fields inherited from class org.mymedialite.itemrec.MF
initMean, initStDev, itemFactors, numFactors, numIter, userFactors
 
Fields inherited from class org.mymedialite.itemrec.ItemRecommender
feedback, maxItemID, maxUserID
 
Constructor Summary
BPRMF()
          Default constructor.
 
Method Summary
 void addFeedback(int user_id, int item_id)
          add a new positive feedback event
 void addItem(int item_id)
          
 void addUser(int user_id)
          
protected  void checkSampling()
           
 double computeFit()
          Compute the fit (AUC on training data)
 double computeLoss()
          Compute approximate loss.
protected  void createFastSamplingData(int u)
           
protected  void initModel()
           
 void iterate()
          Perform one iteration of stochastic gradient ascent over the training data.
 void loadModel(java.io.BufferedReader reader)
          { @inheritDoc }
 void loadModel(java.lang.String filename)
          { @inheritDoc }
 double predict(int user_id, int item_id)
          Predict the weight for a given user-item combination.
 void removeFeedback(int user_id, int item_id)
          remove all positive feedback events with that user-item combination
 void removeItem(int item_id)
          remove all feedback for one item
 void removeUser(int user_id)
          remove all feedback by one user
protected  void retrainItem(int item_id)
          Retrain the latent factors of a given item
protected  void retrainUser(int user_id)
          Retrain the latent factors of a given user
protected  void sampleItemPair(org.mymedialite.itemrec.BPRMF.SampleTriple triple)
          Sample a pair of items, given a user
protected  boolean sampleOtherItem(org.mymedialite.itemrec.BPRMF.SampleTriple triple)
          Sample another item, given the first one and the user
protected  org.mymedialite.itemrec.BPRMF.SampleTriple sampleTriple()
          Sample a triple for BPR learning.
protected  int sampleUser()
          Sample a user that has viewed at least one and not all items.
 void saveModel(java.io.PrintWriter writer)
          { @inheritDoc }
 void saveModel(java.lang.String filename)
          { @inheritDoc }
 java.lang.String toString()
          Return a string representation of the recommender
 void train()
          { @inheritDoc }
protected  void updateFactors(org.mymedialite.itemrec.BPRMF.SampleTriple t, boolean updateU, boolean updateI, boolean updateJ)
          Update features according to the stochastic gradient descent update rule.
 
Methods inherited from class org.mymedialite.itemrec.MF
getItemFactors, getNumIter, getUserFactors, setNumIter
 
Methods inherited from class org.mymedialite.itemrec.ItemRecommender
canPredict, clone, getFeedback, setFeedback
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.mymedialite.IRecommender
canPredict
 

Field Detail

fastSampling

protected boolean fastSampling
Fast, but memory-intensive sampling


itemBias

protected double[] itemBias
Item bias terms


fastSamplingMemoryLimit

public int fastSamplingMemoryLimit
Fast sampling memory limit, in MiB TODO find out why fast sampling does not improve performance


withReplacement

public boolean withReplacement
Sample positive observations with (true) or without (false) replacement


uniformUserSampling

public boolean uniformUserSampling
Sample uniformly from users


biasReg

public double biasReg
Regularization parameter for the bias term


learnRate

public double learnRate
Learning rate alpha


regU

public double regU
Regularization parameter for user factors


regI

public double regI
Regularization parameter for positive item factors


regJ

public double regJ
Regularization parameter for negative item factors


updateJ

protected boolean updateJ
If set (default), update factors for negative sampled items during learning


userPosItems

protected java.util.ArrayList<int[]> userPosItems
Support data structure for fast sampling


userNegItems

protected java.util.ArrayList<int[]> userNegItems
Support data structure for fast sampling


boldDriver

public boolean boldDriver
Use bold driver heuristics for learning rate adaption. See Rainer Gemulla, Peter J. Haas, Erik Nijkamp, Yannis Sismanis: Large-Scale Matrix Factorization with Distributed Stochastic Gradient Descent 2011


random

protected Random random
Random number generator

Constructor Detail

BPRMF

public BPRMF()
Default constructor.

Method Detail

initModel

protected void initModel()
Overrides:
initModel in class MF

train

public void train()
{ @inheritDoc }

Specified by:
train in interface IRecommender
Overrides:
train in class MF

iterate

public void iterate()
Perform one iteration of stochastic gradient ascent over the training data. One iteration is iteration_length * number of entries in the training matrix

Specified by:
iterate in interface IIterativeModel
Specified by:
iterate in class MF

sampleOtherItem

protected boolean sampleOtherItem(org.mymedialite.itemrec.BPRMF.SampleTriple triple)
Sample another item, given the first one and the user

Parameters:
triple - a SampleTriple consisting of a user ID and two item IDs
Returns:
true if the given item was already seen by the user

sampleItemPair

protected void sampleItemPair(org.mymedialite.itemrec.BPRMF.SampleTriple triple)
Sample a pair of items, given a user

Parameters:
triple - a SampleTriple consisting of a user ID and two item IDs

sampleUser

protected int sampleUser()
Sample a user that has viewed at least one and not all items.

Returns:
the user ID

sampleTriple

protected org.mymedialite.itemrec.BPRMF.SampleTriple sampleTriple()
Sample a triple for BPR learning.

Returns:
a SampleTriple consisting of a user ID and two item IDs

updateFactors

protected void updateFactors(org.mymedialite.itemrec.BPRMF.SampleTriple t,
                             boolean updateU,
                             boolean updateI,
                             boolean updateJ)
Update features according to the stochastic gradient descent update rule.

Parameters:
t - a SampleTriple specifying the user ID and the first and second itemIDs
updateU - if true, update the user features
updateI - if true, update the features of the first item
updateJ - if true, update the features of the second item

addFeedback

public void addFeedback(int user_id,
                        int item_id)
add a new positive feedback event

Specified by:
addFeedback in interface IIncrementalItemRecommender
Overrides:
addFeedback in class IncrementalItemRecommender
Parameters:
user_id - the user ID
item_id - the item ID

removeFeedback

public void removeFeedback(int user_id,
                           int item_id)
remove all positive feedback events with that user-item combination

Specified by:
removeFeedback in interface IIncrementalItemRecommender
Overrides:
removeFeedback in class IncrementalItemRecommender
Parameters:
user_id - the user ID
item_id - the item ID

addUser

public void addUser(int user_id)

Overrides:
addUser in class IncrementalItemRecommender

addItem

public void addItem(int item_id)

Overrides:
addItem in class IncrementalItemRecommender

removeUser

public void removeUser(int user_id)
remove all feedback by one user

Specified by:
removeUser in interface IIncrementalItemRecommender
Overrides:
removeUser in class IncrementalItemRecommender
Parameters:
user_id - the user ID

removeItem

public void removeItem(int item_id)
remove all feedback for one item

Specified by:
removeItem in interface IIncrementalItemRecommender
Overrides:
removeItem in class IncrementalItemRecommender
Parameters:
item_id - the item ID

retrainUser

protected void retrainUser(int user_id)
Retrain the latent factors of a given user

Parameters:
user_id - the user ID

retrainItem

protected void retrainItem(int item_id)
Retrain the latent factors of a given item

Parameters:
item_id - the item ID

computeLoss

public double computeLoss()
Compute approximate loss.

Specified by:
computeLoss in interface IIterativeModel
Specified by:
computeLoss in class MF
Returns:
the approximate loss

computeFit

public double computeFit()
Compute the fit (AUC on training data)

Returns:
the fit

createFastSamplingData

protected void createFastSamplingData(int u)

checkSampling

protected void checkSampling()

predict

public double predict(int user_id,
                      int item_id)
Description copied from class: MF
Predict the weight for a given user-item combination. If the user or the item are not known to the recommender, zero is returned. To avoid this behavior for unknown entities, use CanPredict() to check before.

Specified by:
predict in interface IRecommender
Overrides:
predict in class MF
Parameters:
user_id - the user ID
item_id - the item ID
Returns:
the predicted weight

saveModel

public void saveModel(java.lang.String filename)
               throws java.io.IOException
Description copied from class: MF
{ @inheritDoc }

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

saveModel

public void saveModel(java.io.PrintWriter writer)
Description copied from class: MF
{ @inheritDoc }

Overrides:
saveModel in class MF

loadModel

public void loadModel(java.lang.String filename)
               throws java.io.IOException
{ @inheritDoc }

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

loadModel

public void loadModel(java.io.BufferedReader reader)
               throws java.io.IOException
{ @inheritDoc }

Overrides:
loadModel in class MF
Throws:
java.io.IOException

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 ItemRecommender
Returns:
the class name and all hyperparameters, separated by space characters.