net.myrrix.common
Interface MyrrixRecommender

All Superinterfaces:

org.apache.mahout.cf.taste.recommender.ItemBasedRecommender, org.apache.mahout.cf.taste.recommender.Recommender, org.apache.mahout.cf.taste.common.Refreshable

public interface MyrrixRecommender
extends org.apache.mahout.cf.taste.recommender.ItemBasedRecommender

Defines additional methods supported beyond what is in ItemBasedRecommender, including a method to recommend to "anonymous" users recommendToAnonymous(long[], int) and a means to bulk-load data ingest(Reader).

Note that the API methods setPreference(long, long) and removePreference(long, long), retained from Apache Mahout, have a somewhat different meaning than in Mahout. They add to an association strength, rather than replace it. See the javadoc.

Author:

Sean Owen

Method Summary

float[]	estimatePreferences(long userID, long... itemIDs) A bulk version of Recommender.estimatePreference(long, long), suitable for computing many estimates at once.
void	ingest(File file) "Uploads" a series of new associations to the recommender; this is like a bulk version of setPreference(long, long, float).
void	ingest(Reader reader) Like ingest(File), but reads from a Reader.
boolean	isReady()
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	recommend(long userID, int howMany, boolean considerKnownItems, org.apache.mahout.cf.taste.recommender.IDRescorer rescorer)
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	recommendToAnonymous(long[] itemIDs, int howMany) Computes recommendations for a user that is not known to the model yet; instead, the user's associated items are supplied to the method and it proceeds as if a user with these associated items were in the model.
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	recommendToMany(long[] userIDs, int howMany, boolean considerKnownItems, org.apache.mahout.cf.taste.recommender.IDRescorer rescorer) Recommends to a group of users all at once.
void	removePreference(long userID, long itemID) This method will remove an item from the user's set of known items, making it eligible for recommendation again.
void	setPreference(long userID, long itemID) Defaults to value 1.0.
void	setPreference(long userID, long itemID, float value) Adds to a user-item preference, or association.

Methods inherited from interface org.apache.mahout.cf.taste.recommender.ItemBasedRecommender

mostSimilarItems, mostSimilarItems, mostSimilarItems, mostSimilarItems, mostSimilarItems, mostSimilarItems, recommendedBecause

Methods inherited from interface org.apache.mahout.cf.taste.recommender.Recommender

estimatePreference, getDataModel, recommend, recommend

Methods inherited from interface org.apache.mahout.cf.taste.common.Refreshable

refresh

Method Detail

recommend

List<org.apache.mahout.cf.taste.recommender.RecommendedItem> recommend(long userID,
                                                                       int howMany,
                                                                       boolean considerKnownItems,
                                                                       org.apache.mahout.cf.taste.recommender.IDRescorer rescorer)
                                                                       throws org.apache.mahout.cf.taste.common.TasteException

Parameters:

userID - user for which recommendations are to be computed

howMany - desired number of recommendations

considerKnownItems - if true, items that the user is already associated to are candidates for recommendation. Normally this is false.

rescorer - rescoring function used to modify association strengths before ranking results

Returns:

List of recommended RecommendedItems, ordered from most strongly recommend to least

Throws:

NotReadyException - if the recommender has no model available yet

org.apache.mahout.cf.taste.common.TasteException - if another error occurs

recommendToMany

List<org.apache.mahout.cf.taste.recommender.RecommendedItem> recommendToMany(long[] userIDs,
                                                                             int howMany,
                                                                             boolean considerKnownItems,
                                                                             org.apache.mahout.cf.taste.recommender.IDRescorer rescorer)
                                                                             throws org.apache.mahout.cf.taste.common.TasteException

Recommends to a group of users all at once. It takes into account their tastes equally and produces one set of recommendations that is deemed most suitable to them as a group. It is otherwise identical to recommend(long, int, boolean, IDRescorer).

Throws:

org.apache.mahout.cf.taste.common.TasteException

recommendToAnonymous

List<org.apache.mahout.cf.taste.recommender.RecommendedItem> recommendToAnonymous(long[] itemIDs,
                                                                                  int howMany)
                                                                                  throws org.apache.mahout.cf.taste.common.TasteException

Computes recommendations for a user that is not known to the model yet; instead, the user's associated items are supplied to the method and it proceeds as if a user with these associated items were in the model.

Throws:

NotReadyException - if the implementation has no usable model yet

org.apache.mahout.cf.taste.common.TasteException

See Also:

Recommender.recommend(long, int)

estimatePreferences

float[] estimatePreferences(long userID,
                            long... itemIDs)
                            throws org.apache.mahout.cf.taste.common.TasteException

A bulk version of Recommender.estimatePreference(long, long), suitable for computing many estimates at once. The return values correspond, in order, to the item IDs provided, in order.

Throws:

org.apache.mahout.cf.taste.common.TasteException

See Also:

Recommender.estimatePreference(long, long)

ingest

void ingest(Reader reader)
            throws org.apache.mahout.cf.taste.common.TasteException

Like ingest(File), but reads from a Reader.

Parameters:

reader - source of CSV data to ingest

Throws:

NotReadyException - if the implementation has no usable model yet

org.apache.mahout.cf.taste.common.TasteException

ingest

void ingest(File file)
            throws org.apache.mahout.cf.taste.common.TasteException

"Uploads" a series of new associations to the recommender; this is like a bulk version of setPreference(long, long, float). The input file should be in CSV format, where each line is of the form userID,itemID,value. Note that the file may be compressed. If it is make sure that its name reflects its compression -- gzip ending in ".gz", zip ending in ".zip".

Parameters:

file - CSV file to ingest, possibly compressed.

Throws:

NotReadyException - if the implementation has no usable model yet

org.apache.mahout.cf.taste.common.TasteException

setPreference

void setPreference(long userID,
                   long itemID)
                   throws org.apache.mahout.cf.taste.common.TasteException

Defaults to value 1.0.

Throws:

org.apache.mahout.cf.taste.common.TasteException - if the preference cannot be updated, due to a server error

NotReadyException - if the implementation has no usable model yet

See Also:

setPreference(long, long, float)

setPreference

void setPreference(long userID,
                   long itemID,
                   float value)
                   throws org.apache.mahout.cf.taste.common.TasteException

Adds to a user-item preference, or association. This is called in response to some action that indicates the user has a stronger association to an item, like a click or purchase. It is intended to be called many times for a user and item, as more actions are observed that associate the two. That is, this calls adds to rather than sets the association.

To "undo" associations, call this method with negative values, or see removePreference(long, long).

Value is not a rating, but a strength indicator. It may be negative. Its magnitude should correspond to the degree to which an observed event suggests an association between a user and item. A value twice as big should correspond to an event that suggests twice as strong an association.

For example, a click on a video might result in a call with value 1.0. Watching half of the video might result in another call adding value 3.0. Finishing the video, another 3.0. Liking or sharing the video, an additional 10.0. Clicking away from a video within 10 seconds might result in a -3.0.

Specified by:

setPreference in interface org.apache.mahout.cf.taste.recommender.Recommender

Parameters:

userID - user involved in the new preference

itemID - item involved

value - strength value

Throws:

org.apache.mahout.cf.taste.common.TasteException - if the preference cannot be updated, due to a server error

NotReadyException - if the implementation has no usable model yet

removePreference

void removePreference(long userID,
                      long itemID)
                      throws org.apache.mahout.cf.taste.common.TasteException

This method will remove an item from the user's set of known items, making it eligible for recommendation again. If the user has no more items, this method will remove the user too, such that new calls to Recommender.recommend(long, int) for example will fail with NoSuchUserException.

It does not affect any user-item association strengths.

Contrast with calling setPreference(long, long, float) with a negative value, which merely records a negative association between the user and item.

Specified by:

removePreference in interface org.apache.mahout.cf.taste.recommender.Recommender

Throws:

org.apache.mahout.cf.taste.common.TasteException

isReady

boolean isReady()
                throws org.apache.mahout.cf.taste.common.TasteException

Returns:

true if and only if the instance is ready to make recommendations; may be false for example while the recommender is still building an initial model

Throws:

org.apache.mahout.cf.taste.common.TasteException