net.myrrix.client.translating

Interface TranslatingRecommender

All Known Implementing Classes:

TranslatingClientRecommender

public interface TranslatingRecommender

This is a variation on the usual ItemBasedRecommender from Mahout (which uses long values to identify users and items) that instead uses String as keys. Implementations of this interface perform the same functions, but internally translate from instances of type String to long and back. In particular, Strings are hashed to long values using MD5, and the reverse mapping is stored locally for a reverse translation.

To do this, the client must be aware of all item IDs that may be returned. It will receive a hashed value from the Serving Layer, and must have been initialized with addItemIDs(Iterable) or addItemIDs(File) first in order to perform the reverse translation. Otherwise the returned item IDs will be (string representations of) the hashed value only.

Since:

1.0

Author:

Sean Owen

Method Summary

Methods

Modifier and Type	Method and Description
void	addItemIDs(File idFile) Like addItemIDs(Iterable), but accepts a file containing item IDs, one per line.
void	addItemIDs(Iterable<String> ids) "Teaches" the client about item IDs, so that when the underlying recommender returns their hashed representation, this client can translate them back into true IDs.
void	await() Blocks indefinitely until isReady() returns true.
boolean	await(long time, TimeUnit unit) Blocks until isReady() returns true, or the given timeout is reached.
float	estimateForAnonymous(String toItemID, String[] itemIDs)
float	estimateForAnonymous(String toItemID, String[] itemIDs, float[] values)
float	estimatePreference(String userID, String itemID)
float[]	estimatePreferences(String userID, String... itemIDs)
Collection<String>	getAllItemIDs()
Collection<String>	getItemCluster(int n)
int	getNumItemClusters()
int	getNumUserClusters()
Collection<String>	getUserCluster(int n)
void	ingest(File file)
void	ingest(Reader reader)
boolean	isReady()
List<TranslatedRecommendedItem>	mostPopularItems(int howMany)
List<TranslatedRecommendedItem>	mostSimilarItems(String[] itemIDs, int howMany)
List<TranslatedRecommendedItem>	mostSimilarItems(String[] itemIDs, int howMany, String[] rescorerParams, String contextUserID)
List<TranslatedRecommendedItem>	mostSimilarItems(String itemID, int howMany)
List<TranslatedRecommendedItem>	recommend(String userID, int howMany)
List<TranslatedRecommendedItem>	recommend(String userID, int howMany, boolean considerKnownItems, String[] rescorerParams)
List<TranslatedRecommendedItem>	recommendedBecause(String userID, String itemID, int howMany)
List<TranslatedRecommendedItem>	recommendToAnonymous(String[] itemIDs, float[] values, int howMany)
List<TranslatedRecommendedItem>	recommendToAnonymous(String[] itemIDs, float[] values, int howMany, String[] rescorerParams, String contextUserID)
List<TranslatedRecommendedItem>	recommendToAnonymous(String[] itemIDs, int howMany)
List<TranslatedRecommendedItem>	recommendToMany(String[] userIDs, int howMany, boolean considerKnownItems, String[] rescorerParams)
void	refresh()
void	removePreference(String userID, String itemID)
void	setItemTag(String tag, String itemID)
void	setItemTag(String tag, String itemID, float value)
void	setPreference(String userID, String itemID)
void	setPreference(String userID, String itemID, float value)
void	setUserTag(String userID, String tag)
void	setUserTag(String userID, String tag, float value)
float[]	similarityToItem(String toItemID, String... itemIDs)
float[]	similarityToItem(String toItemID, String[] itemIDs, String contextUserID)

Method Detail

recommend

List<TranslatedRecommendedItem> recommend(String userID,
                                        int howMany)
                                          throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.recommend(long, int)

recommend

List<TranslatedRecommendedItem> recommend(String userID,
                                        int howMany,
                                        boolean considerKnownItems,
                                        String[] rescorerParams)
                                          throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

ClientRecommender.recommend(long, int, boolean, String[])

recommendToMany

List<TranslatedRecommendedItem> recommendToMany(String[] userIDs,
                                              int howMany,
                                              boolean considerKnownItems,
                                              String[] rescorerParams)
                                                throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

ClientRecommender.recommendToMany(long[], int, boolean, String[])

estimatePreference

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

Throws:

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

See Also:

MyrrixRecommender.estimatePreference(long, long)

estimatePreferences

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

Throws:

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

See Also:

MyrrixRecommender.estimatePreferences(long, long...)

estimateForAnonymous

float estimateForAnonymous(String toItemID,
                         String[] itemIDs)
                           throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.estimateForAnonymous(long, long[])

estimateForAnonymous

float estimateForAnonymous(String toItemID,
                         String[] itemIDs,
                         float[] values)
                           throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.estimateForAnonymous(long, long[], float[])

setPreference

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

Throws:

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

See Also:

MyrrixRecommender.setPreference(long, long)

setPreference

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

Throws:

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

See Also:

MyrrixRecommender.setPreference(long, long, float)

removePreference

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

Throws:

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

See Also:

MyrrixRecommender.removePreference(long, long)

setUserTag

void setUserTag(String userID,
              String tag)
                throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.setUserTag(long, String)

setUserTag

void setUserTag(String userID,
              String tag,
              float value)
                throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.setUserTag(long, String, float)

setItemTag

void setItemTag(String tag,
              String itemID)
                throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.setItemTag(String, long)

setItemTag

void setItemTag(String tag,
              String itemID,
              float value)
                throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.setItemTag(String, long, float)

mostSimilarItems

List<TranslatedRecommendedItem> mostSimilarItems(String itemID,
                                               int howMany)
                                                 throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.mostSimilarItems(long, int)

mostSimilarItems

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

Throws:

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

See Also:

MyrrixRecommender.mostSimilarItems(long[], int)

mostSimilarItems

List<TranslatedRecommendedItem> mostSimilarItems(String[] itemIDs,
                                               int howMany,
                                               String[] rescorerParams,
                                               String contextUserID)
                                                 throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

ClientRecommender.mostSimilarItems(long[], int, String[], Long)

similarityToItem

float[] similarityToItem(String toItemID,
                       String... itemIDs)
                         throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

ClientRecommender.similarityToItem(long, long...)

similarityToItem

float[] similarityToItem(String toItemID,
                       String[] itemIDs,
                       String contextUserID)
                         throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

ClientRecommender.similarityToItem(long, long[], Long)

recommendedBecause

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

Throws:

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

See Also:

MyrrixRecommender.recommendedBecause(long, long, int)

recommendToAnonymous

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

Throws:

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

See Also:

MyrrixRecommender.recommendToAnonymous(long[], int)

recommendToAnonymous

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

Throws:

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

See Also:

MyrrixRecommender.recommendToAnonymous(long[], float[], int)

recommendToAnonymous

List<TranslatedRecommendedItem> recommendToAnonymous(String[] itemIDs,
                                                   float[] values,
                                                   int howMany,
                                                   String[] rescorerParams,
                                                   String contextUserID)
                                                     throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

ClientRecommender.recommendToAnonymous(long[], float[], int, String[], Long)

mostPopularItems

List<TranslatedRecommendedItem> mostPopularItems(int howMany)
                                                 throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.mostPopularItems(int)

ingest

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

Throws:

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

See Also:

MyrrixRecommender.ingest(Reader)

ingest

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

Throws:

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

See Also:

MyrrixRecommender.ingest(File)

addItemIDs

void addItemIDs(Iterable<String> ids)

"Teaches" the client about item IDs, so that when the underlying recommender returns their hashed representation, this client can translate them back into true IDs. The client must be told about all IDs it may need to return, using this method of addItemIDs(File).

Parameters:

ids - item IDs that are in use by the system

addItemIDs

void addItemIDs(File idFile)
                throws org.apache.mahout.cf.taste.common.TasteException

Like addItemIDs(Iterable), but accepts a file containing item IDs, one per line.

Parameters:

idFile - file with one ID per line

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

refresh

void refresh()

See Also:

MyrrixRecommender.refresh()

await

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

Blocks indefinitely until isReady() returns true.

Throws:

org.apache.mahout.cf.taste.common.TasteException - if an error occurs while checking isReady()

InterruptedException - if the thread is interrupted while waiting

await

boolean await(long time,
            TimeUnit unit)
              throws org.apache.mahout.cf.taste.common.TasteException,
                     InterruptedException

Blocks until isReady() returns true, or the given timeout is reached.

Returns:

true if isReady() is true, or false if it timed out

Throws:

org.apache.mahout.cf.taste.common.TasteException - if an error occurs while checking isReady()

InterruptedException - if the thread is interrupted while waiting

getAllItemIDs

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

getNumUserClusters

int getNumUserClusters()
                       throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.getNumUserClusters()

getNumItemClusters

int getNumItemClusters()
                       throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.getNumItemClusters()

getUserCluster

Collection<String> getUserCluster(int n)
                                  throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.getUserCluster(int)

getItemCluster

Collection<String> getItemCluster(int n)
                                  throws org.apache.mahout.cf.taste.common.TasteException

Throws:

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

See Also:

MyrrixRecommender.getItemCluster(int)