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.

Several methods exist here because they are defined in Mahout, but have no useful meaning in this implementation. These are marked as @Deprecated and should not be used.

Author:

Sean Owen, Mahout

Method Summary

Methods

Modifier and Type	Method and Description
void	await() Blocks until isReady() returns true.
float	estimatePreference(long userID, long itemID)
float[]	estimatePreferences(long userID, long... itemIDs) A bulk version of estimatePreference(long, long), suitable for computing many estimates at once.
FastIDSet	getAllItemIDs()
FastIDSet	getAllUserIDs()
org.apache.mahout.cf.taste.model.DataModel	getDataModel() Deprecated. do not call; only present to satisfy Mahout API
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>	mostSimilarItems(long[] itemIDs, int howMany)
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	mostSimilarItems(long[] itemIDs, int howMany, boolean excludeItemIfNotSimilarToAll) Deprecated. do not call; only present to satisfy Mahout API
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	mostSimilarItems(long[] itemIDs, int howMany, org.apache.mahout.cf.taste.recommender.Rescorer<org.apache.mahout.common.LongPair> rescorer)
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	mostSimilarItems(long[] itemIDs, int howMany, org.apache.mahout.cf.taste.recommender.Rescorer<org.apache.mahout.common.LongPair> rescorer, boolean excludeItemIfNotSimilarToAll) Deprecated. do not call; only present to satisfy Mahout API
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	mostSimilarItems(long itemID, int howMany)
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	mostSimilarItems(long itemID, int howMany, org.apache.mahout.cf.taste.recommender.Rescorer<org.apache.mahout.common.LongPair> rescorer)
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	recommend(long userID, int howMany)
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>	recommend(long userID, int howMany, org.apache.mahout.cf.taste.recommender.IDRescorer rescorer)
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	recommendedBecause(long userID, long itemID, int howMany) Lists the items that were most influential in recommending a given item to a given user.
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	recommendToAnonymous(long[] itemIDs, float[] values, int howMany) Like recommendToAnonymous(long[], int) but allows specifying values associated with items.
List<org.apache.mahout.cf.taste.recommender.RecommendedItem>	recommendToAnonymous(long[] itemIDs, float[] values, int howMany, org.apache.mahout.cf.taste.recommender.IDRescorer rescorer) Like recommendToAnonymous(long[], int, IDRescorer) but lets caller specify strength scores associated to each of the items.
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>	recommendToAnonymous(long[] itemIDs, int howMany, org.apache.mahout.cf.taste.recommender.IDRescorer rescorer) Like recommendToAnonymous(long[], int) but rescorer results like recommend(long, int, boolean, IDRescorer).
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.common.Refreshable

refresh

Method Detail

recommend

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

Specified by:

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

Parameters:

userID - user for which recommendations are to be computed

howMany - desired number of recommendations

Returns:

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

Throws:

org.apache.mahout.cf.taste.common.NoSuchUserException - if the user is not known

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

recommend

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

Specified by:

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

Parameters:

userID - user for which recommendations are to be computed

howMany - desired number of recommendations

rescorer - rescoring function to apply before final list of recommendations is determined

Returns:

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

Throws:

org.apache.mahout.cf.taste.common.NoSuchUserException - if the user is not known

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

estimatePreference

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

Specified by:

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

Parameters:

userID - user ID whose preference is to be estimated

itemID - item ID to estimate preference for

Returns:

an estimated preference, which may not be the total strength from the input. This is always an estimate built from the model alone. Returns 0 if user or item is not known.

Throws:

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

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 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

getDataModel

@Deprecated
org.apache.mahout.cf.taste.model.DataModel getDataModel()

Deprecated. do not call; only present to satisfy Mahout API

Specified by:

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

Throws:

UnsupportedOperationException - in general

mostSimilarItems

List<org.apache.mahout.cf.taste.recommender.RecommendedItem> mostSimilarItems(long itemID,
                                                                            int howMany)
                                                                              throws org.apache.mahout.cf.taste.common.TasteException

Specified by:

mostSimilarItems in interface org.apache.mahout.cf.taste.recommender.ItemBasedRecommender

Parameters:

itemID - ID of item for which to find most similar other items

howMany - desired number of most similar items to find

Returns:

items most similar to the given item, ordered from most similar to least

Throws:

org.apache.mahout.cf.taste.common.NoSuchItemException - if the item is not known

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

mostSimilarItems

List<org.apache.mahout.cf.taste.recommender.RecommendedItem> mostSimilarItems(long itemID,
                                                                            int howMany,
                                                                            org.apache.mahout.cf.taste.recommender.Rescorer<org.apache.mahout.common.LongPair> rescorer)
                                                                              throws org.apache.mahout.cf.taste.common.TasteException

Specified by:

mostSimilarItems in interface org.apache.mahout.cf.taste.recommender.ItemBasedRecommender

Parameters:

itemID - ID of item for which to find most similar other items

howMany - desired number of most similar items to find

rescorer - Rescorer which can adjust item-item similarity estimates used to determine most similar items

Returns:

items most similar to the given item, ordered from most similar to least

Throws:

org.apache.mahout.cf.taste.common.NoSuchItemException - if the item is not known

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

mostSimilarItems

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

Specified by:

mostSimilarItems in interface org.apache.mahout.cf.taste.recommender.ItemBasedRecommender

Parameters:

itemIDs - IDs of item for which to find most similar other items

howMany - desired number of most similar items to find estimates used to determine most similar items

Returns:

items most similar to the given items, ordered from most similar to least

Throws:

org.apache.mahout.cf.taste.common.NoSuchItemException - if none of itemIDs exist in the model. Otherwise, unknown items are ignored.

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

mostSimilarItems

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

Specified by:

mostSimilarItems in interface org.apache.mahout.cf.taste.recommender.ItemBasedRecommender

Parameters:

itemIDs - IDs of item for which to find most similar other items

howMany - desired number of most similar items to find

rescorer - Rescorer which can adjust item-item similarity estimates used to determine most similar items

Returns:

items most similar to the given items, ordered from most similar to least

Throws:

org.apache.mahout.cf.taste.common.NoSuchItemException - if none of itemIDs exist in the model. Otherwise, unknown items are ignored.

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

mostSimilarItems

@Deprecated
List<org.apache.mahout.cf.taste.recommender.RecommendedItem> mostSimilarItems(long[] itemIDs,
                                                                                       int howMany,
                                                                                       boolean excludeItemIfNotSimilarToAll)
                                                                              throws org.apache.mahout.cf.taste.common.TasteException

Deprecated. do not call; only present to satisfy Mahout API

Specified by:

mostSimilarItems in interface org.apache.mahout.cf.taste.recommender.ItemBasedRecommender

Throws:

UnsupportedOperationException - in general

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

mostSimilarItems

@Deprecated
List<org.apache.mahout.cf.taste.recommender.RecommendedItem> mostSimilarItems(long[] itemIDs,
                                                                                       int howMany,
                                                                                       org.apache.mahout.cf.taste.recommender.Rescorer<org.apache.mahout.common.LongPair> rescorer,
                                                                                       boolean excludeItemIfNotSimilarToAll)
                                                                              throws org.apache.mahout.cf.taste.common.TasteException

Deprecated. do not call; only present to satisfy Mahout API

Specified by:

mostSimilarItems in interface org.apache.mahout.cf.taste.recommender.ItemBasedRecommender

Throws:

UnsupportedOperationException - in general

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

recommendedBecause

List<org.apache.mahout.cf.taste.recommender.RecommendedItem> recommendedBecause(long userID,
                                                                              long itemID,
                                                                              int howMany)
                                                                                throws org.apache.mahout.cf.taste.common.TasteException

Lists the items that were most influential in recommending a given item to a given user. Exactly how this is determined is left to the implementation, but, generally this will return items that the user prefers and that are similar to the given item.

This returns a List of RecommendedItem which is a little misleading since it's returning recommending items, but, I thought it more natural to just reuse this class since it encapsulates an item and value. The value here does not necessarily have a consistent interpretation or expected range; it will be higher the more influential the item was in the recommendation.

Specified by:

recommendedBecause in interface org.apache.mahout.cf.taste.recommender.ItemBasedRecommender

Parameters:

userID - ID of user who was recommended the item

itemID - ID of item that was recommended

howMany - maximum number of items to return

Returns:

List of RecommendedItem, ordered from most influential in recommended the given item to least

Throws:

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

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.NoSuchUserException - if none of userIDs exist in the model. Otherwise, unknown users are ignored.

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

See Also:

recommend(long, int, boolean, IDRescorer)

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.NoSuchItemException - if none of itemIDs exist in the model. Otherwise, unknown items are ignored.

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

See Also:

recommend(long, int)

recommendToAnonymous

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

Like recommendToAnonymous(long[], int) but allows specifying values associated with items.

Parameters:

values - values associated with given itemIDs. If not null, must be as many values as there are item IDs

Throws:

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

recommendToAnonymous

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

Like recommendToAnonymous(long[], int) but rescorer results like recommend(long, int, boolean, IDRescorer). All items are assumed to be equally important to the anonymous users -- strength "1".

Throws:

org.apache.mahout.cf.taste.common.NoSuchItemException - if none of itemIDs exist in the model. Otherwise, unknown items are ignored.

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

See Also:

recommendToAnonymous(long[], int)

recommendToAnonymous

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

Like recommendToAnonymous(long[], int, IDRescorer) but lets caller specify strength scores associated to each of the items.

Parameters:

values - values corresponding to itemIDs

Throws:

org.apache.mahout.cf.taste.common.NoSuchItemException - if none of itemIDs exist in the model. Otherwise, unknown items are ignored.

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

See Also:

recommendToAnonymous(long[], int, IDRescorer)

estimatePreferences

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

A bulk version of 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:

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", deflate ending in ".deflate".

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)

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

await

void await()
           throws org.apache.mahout.cf.taste.common.TasteException

Blocks until isReady() returns true.

Throws:

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

getAllUserIDs

FastIDSet getAllUserIDs()
                        throws org.apache.mahout.cf.taste.common.TasteException

Returns:

all user IDs currently in the model

Throws:

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

getAllItemIDs

FastIDSet getAllItemIDs()
                        throws org.apache.mahout.cf.taste.common.TasteException

Returns:

all item IDs currently in the model

Throws:

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