Return-Path: Delivered-To: apmail-lucene-mahout-commits-archive@minotaur.apache.org Received: (qmail 89147 invoked from network); 13 Feb 2010 20:55:42 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 13 Feb 2010 20:55:42 -0000 Received: (qmail 36408 invoked by uid 500); 13 Feb 2010 20:55:42 -0000 Delivered-To: apmail-lucene-mahout-commits-archive@lucene.apache.org Received: (qmail 36334 invoked by uid 500); 13 Feb 2010 20:55:42 -0000 Mailing-List: contact mahout-commits-help@lucene.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: mahout-dev@lucene.apache.org Delivered-To: mailing list mahout-commits@lucene.apache.org Received: (qmail 36325 invoked by uid 99); 13 Feb 2010 20:55:42 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 13 Feb 2010 20:55:42 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 13 Feb 2010 20:55:37 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 5B7AC2388B45; Sat, 13 Feb 2010 20:54:46 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r909912 [10/10] - in /lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste: common/ eval/ hadoop/ hadoop/cooccurence/ hadoop/item/ hadoop/pseudo/ hadoop/slopeone/ impl/common/ impl/common/jdbc/ impl/eval/ impl/model/ impl/model... Date: Sat, 13 Feb 2010 20:54:31 -0000 To: mahout-commits@lucene.apache.org From: robinanil@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20100213205446.5B7AC2388B45@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/model/Preference.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/model/Preference.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/model/Preference.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/model/Preference.java Sat Feb 13 20:54:05 2010 @@ -18,28 +18,31 @@ package org.apache.mahout.cf.taste.model; /** - *

A {@link Preference} encapsulates an item and a preference value, which indicates the strength of the - * preference for it. {@link Preference}s are associated to users.

+ *

+ * A {@link Preference} encapsulates an item and a preference value, which indicates the strength of the + * preference for it. {@link Preference}s are associated to users. + *

*/ public interface Preference { - + /** @return ID of user who prefers the item */ long getUserID(); - + /** @return item ID that is preferred */ long getItemID(); - + /** - * @return strength of the preference for that item. Zero should indicate "no preference either way"; positive values - * indicate preference and negative values indicate dislike + * @return strength of the preference for that item. Zero should indicate "no preference either way"; + * positive values indicate preference and negative values indicate dislike */ float getValue(); - + /** * Sets the strength of the preference for this item - * - * @param value new preference + * + * @param value + * new preference */ void setValue(float value); - + } Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/model/PreferenceArray.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/model/PreferenceArray.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/model/PreferenceArray.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/model/PreferenceArray.java Sat Feb 13 20:54:05 2010 @@ -20,108 +20,119 @@ import java.io.Serializable; /** - * An alternate representation of an array of {@link Preference}. - * Implementations, in theory, can produce a more - * memory-efficient representation. + * An alternate representation of an array of {@link Preference}. Implementations, in theory, can produce a + * more memory-efficient representation. */ public interface PreferenceArray extends Cloneable, Serializable, Iterable { - + /** * @return size of length of the "array" */ int length(); - + /** - * @param i index + * @param i + * index * @return a materialized {@link Preference} representation of the preference at i */ Preference get(int i); - + /** * Sets preference at i from information in the given {@link Preference} - * + * * @param i * @param pref */ void set(int i, Preference pref); - + /** - * @param i index + * @param i + * index * @return user ID from preference at i */ long getUserID(int i); - + /** * Sets user ID for preference at i. - * - * @param i index - * @param userID new user ID + * + * @param i + * index + * @param userID + * new user ID */ void setUserID(int i, long userID); - + /** - * @param i index + * @param i + * index * @return item ID from preference at i */ long getItemID(int i); - + /** * Sets item ID for preference at i. - * - * @param i index - * @param itemID new item ID + * + * @param i + * index + * @param itemID + * new item ID */ void setItemID(int i, long itemID); - + /** - * @param i index + * @param i + * index * @return preference value from preference at i */ float getValue(int i); - + /** * Sets preference value for preference at i. - * - * @param i index - * @param value new preference value + * + * @param i + * index + * @param value + * new preference value */ void setValue(int i, float value); - + /** * @return independent copy of this object */ PreferenceArray clone(); - + /** * Sorts underlying array by user ID, ascending. */ void sortByUser(); - + /** * Sorts underlying array by item ID, ascending. */ void sortByItem(); - + /** * Sorts underlying array by preference value, ascending. */ void sortByValue(); - + /** * Sorts underlying array by preference value, descending. */ void sortByValueReversed(); - + /** - * @param userID user ID + * @param userID + * user ID * @return true if array contains a preference with given user ID */ boolean hasPrefWithUserID(long userID); - + /** - * @param itemID item ID + * @param itemID + * item ID * @return true if array contains a preference with given item ID */ boolean hasPrefWithItemID(long itemID); - + } \ No newline at end of file Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/neighborhood/UserNeighborhood.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/neighborhood/UserNeighborhood.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/neighborhood/UserNeighborhood.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/neighborhood/UserNeighborhood.java Sat Feb 13 20:54:05 2010 @@ -21,16 +21,20 @@ import org.apache.mahout.cf.taste.common.TasteException; /** - *

Implementations of this interface compute a "neighborhood" of users like a given user. This - * neighborhood can be used to compute recommendations then.

+ *

+ * Implementations of this interface compute a "neighborhood" of users like a given user. This neighborhood + * can be used to compute recommendations then. + *

*/ public interface UserNeighborhood extends Refreshable { - + /** - * @param userID ID of user for which a neighborhood will be computed + * @param userID + * ID of user for which a neighborhood will be computed * @return IDs of users in the neighborhood - * @throws TasteException if an error occurs while accessing data + * @throws TasteException + * if an error occurs while accessing data */ long[] getUserNeighborhood(long userID) throws TasteException; - + } Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/ClusteringRecommender.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/ClusteringRecommender.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/ClusteringRecommender.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/ClusteringRecommender.java Sat Feb 13 20:54:05 2010 @@ -20,26 +20,35 @@ import org.apache.mahout.cf.taste.common.TasteException; import org.apache.mahout.cf.taste.impl.common.FastIDSet; -import java.util.Collection; - -/**

Interface implemented by "clustering" recommenders.

*/ +/** + *

+ * Interface implemented by "clustering" recommenders. + *

+ */ public interface ClusteringRecommender extends Recommender { - + /** - *

Returns the cluster of users to which the given user, denoted by user ID, belongs.

- * - * @param userID user ID for which to find a cluster + *

+ * Returns the cluster of users to which the given user, denoted by user ID, belongs. + *

+ * + * @param userID + * user ID for which to find a cluster * @return {@link Collection} of IDs of users in the requested user's cluster - * @throws TasteException if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} + * @throws TasteException + * if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} */ FastIDSet getCluster(long userID) throws TasteException; - + /** - *

Returns all clusters of users.

- * + *

+ * Returns all clusters of users. + *

+ * * @return {@link Collection} of {@link Collection}s of user IDs - * @throws TasteException if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} + * @throws TasteException + * if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} */ FastIDSet[] getClusters() throws TasteException; - + } Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/IDRescorer.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/IDRescorer.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/IDRescorer.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/IDRescorer.java Sat Feb 13 20:54:05 2010 @@ -18,26 +18,30 @@ package org.apache.mahout.cf.taste.recommender; /** - *

A {@link Rescorer} which operates on {@code long} primitive IDs, rather than - * arbitrary {@link Object}s. This is provided since most uses of this interface - * in the framework take IDs (as {@code long}) as an argument, and so this - * can be used to avoid unnecessary boxing/unboxing.

+ *

+ * A {@link Rescorer} which operates on {@code long} primitive IDs, rather than arbitrary {@link Object}s. + * This is provided since most uses of this interface in the framework take IDs (as {@code long}) as an + * argument, and so this can be used to avoid unnecessary boxing/unboxing. + *

*/ public interface IDRescorer { - + /** - * @param ID ID of thing (user, item, etc.) to rescore - * @param originalScore original score + * @param ID + * ID of thing (user, item, etc.) to rescore + * @param originalScore + * original score * @return modified score, or {@link Double#NaN} to indicate that this should be excluded entirely */ double rescore(long ID, double originalScore); - + /** * Returns true to exclude the given thing. - * - * @param ID ID of thing (user, item, etc.) to rescore + * + * @param ID + * ID of thing (user, item, etc.) to rescore * @return true to exclude, false otherwise */ boolean isFiltered(long ID); - + } \ No newline at end of file Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/ItemBasedRecommender.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/ItemBasedRecommender.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/ItemBasedRecommender.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/ItemBasedRecommender.java Sat Feb 13 20:54:05 2010 @@ -17,71 +17,93 @@ package org.apache.mahout.cf.taste.recommender; +import java.util.List; + import org.apache.mahout.cf.taste.common.TasteException; import org.apache.mahout.common.LongPair; -import java.util.List; - -/**

Interface implemented by "item-based" recommenders.

*/ +/** + *

+ * Interface implemented by "item-based" recommenders. + *

+ */ public interface ItemBasedRecommender extends Recommender { - + /** - * @param itemID ID of item for which to find most similar other items - * @param howMany desired number of most similar items to find + * @param itemID + * ID of item for which to find most similar other items + * @param howMany + * desired number of most similar items to find * @return items most similar to the given item, ordered from most similar to least - * @throws TasteException if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} + * @throws TasteException + * if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} */ List mostSimilarItems(long itemID, int howMany) throws TasteException; - + /** - * @param itemID ID of item for which to find most similar other items - * @param howMany desired number of most similar items to find - * @param rescorer {@link Rescorer} which can adjust item-item similarity estimates used to determine most similar - * items + * @param itemID + * ID of item for which to find most similar other items + * @param howMany + * desired number of most similar items to find + * @param rescorer + * {@link Rescorer} which can adjust item-item similarity estimates used to determine most similar + * items * @return itemss most similar to the given item, ordered from most similar to least - * @throws TasteException if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} + * @throws TasteException + * if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} */ - List mostSimilarItems(long itemID, - int howMany, - Rescorer rescorer) throws TasteException; - + List mostSimilarItems(long itemID, int howMany, Rescorer rescorer) throws TasteException; + /** - * @param itemIDs IDs of item for which to find most similar other items - * @param howMany desired number of most similar items to find estimates used to determine most similar items + * @param itemIDs + * IDs of item for which to find most similar other items + * @param howMany + * desired number of most similar items to find estimates used to determine most similar items * @return items most similar to the given items, ordered from most similar to least - * @throws TasteException if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} + * @throws TasteException + * if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} */ List mostSimilarItems(long[] itemIDs, int howMany) throws TasteException; - + /** - * @param itemIDs IDs of item for which to find most similar other items - * @param howMany desired number of most similar items to find - * @param rescorer {@link Rescorer} which can adjust item-item similarity estimates used to determine most similar - * items + * @param itemIDs + * IDs of item for which to find most similar other items + * @param howMany + * desired number of most similar items to find + * @param rescorer + * {@link Rescorer} which can adjust item-item similarity estimates used to determine most similar + * items * @return items most similar to the given items, ordered from most similar to least - * @throws TasteException if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} + * @throws TasteException + * if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} */ - List mostSimilarItems(long[] itemIDs, - int howMany, - Rescorer rescorer) throws TasteException; - + List mostSimilarItems(long[] itemIDs, int howMany, Rescorer rescorer) throws 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 {@link List} of {@link 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.

- * - * @param userID ID of user who was recommended the item - * @param itemID ID of item that was recommended - * @param howMany maximum number of items to return - * @return {@link List} of {@link RecommendedItem}, ordered from most influential in recommended the - * given item to least - * @throws TasteException if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} + *

+ * 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 {@link List} of {@link 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. + *

+ * + * @param userID + * ID of user who was recommended the item + * @param itemID + * ID of item that was recommended + * @param howMany + * maximum number of items to return + * @return {@link List} of {@link RecommendedItem}, ordered from most influential in recommended the given + * item to least + * @throws TasteException + * if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} */ List recommendedBecause(long userID, long itemID, int howMany) throws TasteException; - + } Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/RecommendedItem.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/RecommendedItem.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/RecommendedItem.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/RecommendedItem.java Sat Feb 13 20:54:05 2010 @@ -18,20 +18,24 @@ package org.apache.mahout.cf.taste.recommender; /** - *

Implementations encapsulate items that are recommended, and include the item - * recommended and a value expressing the strength of the preference.

+ *

+ * Implementations encapsulate items that are recommended, and include the item recommended and a value + * expressing the strength of the preference. + *

*/ public interface RecommendedItem extends Comparable { - + /** @return the recommended item ID */ long getItemID(); - + /** - *

A value expressing the strength of the preference for the recommended item. The range of the values - * depends on the implementation. Implementations must use larger values to express stronger preference.

- * + *

+ * A value expressing the strength of the preference for the recommended item. The range of the values + * depends on the implementation. Implementations must use larger values to express stronger preference. + *

+ * * @return strength of the preference */ float getValue(); - + } Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/Recommender.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/Recommender.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/Recommender.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/Recommender.java Sat Feb 13 20:54:05 2010 @@ -17,61 +17,82 @@ package org.apache.mahout.cf.taste.recommender; +import java.util.List; + import org.apache.mahout.cf.taste.common.Refreshable; import org.apache.mahout.cf.taste.common.TasteException; import org.apache.mahout.cf.taste.model.DataModel; -import java.util.List; - /** - *

Implementations of this interface can recommend items for a user. - * Implementations will likely take advantage of several classes in other packages here to compute this.

+ *

+ * Implementations of this interface can recommend items for a user. Implementations will likely take + * advantage of several classes in other packages here to compute this. + *

*/ public interface Recommender extends Refreshable { - + /** - * @param userID user for which recommendations are to be computed - * @param howMany desired number of recommendations - * @return {@link List} of recommended {@link RecommendedItem}s, ordered from most strongly recommend to least - * @throws TasteException if an error occurs while accessing the {@link DataModel} + * @param userID + * user for which recommendations are to be computed + * @param howMany + * desired number of recommendations + * @return {@link List} of recommended {@link RecommendedItem}s, ordered from most strongly recommend to + * least + * @throws TasteException + * if an error occurs while accessing the {@link DataModel} */ List recommend(long userID, int howMany) throws TasteException; - + /** - * @param userID user for which recommendations are to be computed - * @param howMany desired number of recommendations - * @param rescorer rescoring function to apply before final list of recommendations is determined - * @return {@link List} of recommended {@link RecommendedItem}s, ordered from most strongly recommend to least - * @throws TasteException if an error occurs while accessing the {@link DataModel} + * @param userID + * user for which recommendations are to be computed + * @param howMany + * desired number of recommendations + * @param rescorer + * rescoring function to apply before final list of recommendations is determined + * @return {@link List} of recommended {@link RecommendedItem}s, ordered from most strongly recommend to + * least + * @throws TasteException + * if an error occurs while accessing the {@link DataModel} */ - List recommend(long userID, int howMany, IDRescorer rescorer) - throws TasteException; - + List recommend(long userID, int howMany, IDRescorer rescorer) throws TasteException; + /** - * @param userID user ID whose preference is to be estimated - * @param itemID item ID to estimate preference for - * @return an estimated preference if the user has not expressed a preference for the item, or else the user's actual - * preference for the item. If a preference cannot be estimated, returns {@link Double#NaN} - * @throws TasteException if an error occurs while accessing the {@link DataModel} + * @param userID + * user ID whose preference is to be estimated + * @param itemID + * item ID to estimate preference for + * @return an estimated preference if the user has not expressed a preference for the item, or else the + * user's actual preference for the item. If a preference cannot be estimated, returns + * {@link Double#NaN} + * @throws TasteException + * if an error occurs while accessing the {@link DataModel} */ float estimatePreference(long userID, long itemID) throws TasteException; - + /** - * @param userID user to set preference for - * @param itemID item to set preference for - * @param value preference value - * @throws TasteException if an error occurs while accessing the {@link DataModel} + * @param userID + * user to set preference for + * @param itemID + * item to set preference for + * @param value + * preference value + * @throws TasteException + * if an error occurs while accessing the {@link DataModel} */ void setPreference(long userID, long itemID, float value) throws TasteException; - + /** - * @param userID user from which to remove preference - * @param itemID item for which to remove preference - * @throws TasteException if an error occurs while accessing the {@link DataModel} + * @param userID + * user from which to remove preference + * @param itemID + * item for which to remove preference + * @throws TasteException + * if an error occurs while accessing the {@link DataModel} */ void removePreference(long userID, long itemID) throws TasteException; - + /** @return {@link DataModel} used by this {@link Recommender} */ DataModel getDataModel(); - + } Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/Rescorer.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/Rescorer.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/Rescorer.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/Rescorer.java Sat Feb 13 20:54:05 2010 @@ -18,28 +18,34 @@ package org.apache.mahout.cf.taste.recommender; /** - *

A {@link Rescorer} simply assigns a new "score" to a thing like an ID of an item - * or user which a {@link Recommender} is considering returning as a top - * recommendation. It may be used to arbitrarily re-rank the results according to application-specific logic before - * returning recommendations. For example, an application may want to boost the score of items in a certain category - * just for one request.

- * - *

A {@link Rescorer} can also exclude a thing from consideration entirely by returning true from {@link - * #isFiltered(Object)}.

+ *

+ * A {@link Rescorer} simply assigns a new "score" to a thing like an ID of an item or user which a + * {@link Recommender} is considering returning as a top recommendation. It may be used to arbitrarily re-rank + * the results according to application-specific logic before returning recommendations. For example, an + * application may want to boost the score of items in a certain category just for one request. + *

+ * + *

+ * A {@link Rescorer} can also exclude a thing from consideration entirely by returning true from + * {@link #isFiltered(Object)}. + *

*/ public interface Rescorer { - + /** - * @param thing thing to rescore - * @param originalScore original score + * @param thing + * thing to rescore + * @param originalScore + * original score * @return modified score, or {@link Double#NaN} to indicate that this should be excluded entirely */ double rescore(T thing, double originalScore); - + /** * Returns true to exclude the given thing. - * - * @param thing the thing to filter + * + * @param thing + * the thing to filter * @return true to exclude, false otherwise */ boolean isFiltered(T thing); Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/UserBasedRecommender.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/UserBasedRecommender.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/UserBasedRecommender.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/UserBasedRecommender.java Sat Feb 13 20:54:05 2010 @@ -19,25 +19,36 @@ import org.apache.mahout.cf.taste.common.TasteException; import org.apache.mahout.common.LongPair; -/**

Interface implemented by "user-based" recommenders.

*/ +/** + *

+ * Interface implemented by "user-based" recommenders. + *

+ */ public interface UserBasedRecommender extends Recommender { - + /** - * @param userID ID of user for which to find most similar other users - * @param howMany desired number of most similar users to find + * @param userID + * ID of user for which to find most similar other users + * @param howMany + * desired number of most similar users to find * @return users most similar to the given user - * @throws TasteException if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} + * @throws TasteException + * if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} */ long[] mostSimilarUserIDs(long userID, int howMany) throws TasteException; - + /** - * @param userID ID of user for which to find most similar other users - * @param howMany desired number of most similar users to find - * @param rescorer {@link Rescorer} which can adjust user-user similarity estimates used to determine most similar - * users + * @param userID + * ID of user for which to find most similar other users + * @param howMany + * desired number of most similar users to find + * @param rescorer + * {@link Rescorer} which can adjust user-user similarity estimates used to determine most similar + * users * @return IDs of users most similar to the given user - * @throws TasteException if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} + * @throws TasteException + * if an error occurs while accessing the {@link org.apache.mahout.cf.taste.model.DataModel} */ long[] mostSimilarUserIDs(long userID, int howMany, Rescorer rescorer) throws TasteException; - + } Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/slopeone/DiffStorage.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/slopeone/DiffStorage.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/slopeone/DiffStorage.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/recommender/slopeone/DiffStorage.java Sat Feb 13 20:54:05 2010 @@ -24,47 +24,56 @@ import org.apache.mahout.cf.taste.model.PreferenceArray; /** - *

Implementations store item-item preference diffs for a - * {@link org.apache.mahout.cf.taste.impl.recommender.slopeone.SlopeOneRecommender}. - * It actually does a bit more for this implementation, like listing all items that may be - * considered for recommendation, in order to maximize what implementations can do to optimize - * the slope-one algorithm.

- * + *

+ * Implementations store item-item preference diffs for a + * {@link org.apache.mahout.cf.taste.impl.recommender.slopeone.SlopeOneRecommender}. It actually does a bit + * more for this implementation, like listing all items that may be considered for recommendation, in order to + * maximize what implementations can do to optimize the slope-one algorithm. + *

+ * * @see org.apache.mahout.cf.taste.impl.recommender.slopeone.SlopeOneRecommender */ public interface DiffStorage extends Refreshable { - + /** - * @return {@link RunningAverage} encapsulating the average difference in preferences between items corresponding to - * itemID1 and itemID2, in that direction; that is, it's the average of item 2's - * preferences minus item 1's preferences + * @return {@link RunningAverage} encapsulating the average difference in preferences between items + * corresponding to itemID1 and itemID2, in that direction; that is, it's + * the average of item 2's preferences minus item 1's preferences */ RunningAverage getDiff(long itemID1, long itemID2) throws TasteException; - + /** - * @param userID user ID to get diffs for - * @param itemID itemID to assess - * @param prefs user's preferendces + * @param userID + * user ID to get diffs for + * @param itemID + * itemID to assess + * @param prefs + * user's preferendces * @return {@link RunningAverage}s for that user's item-item diffs */ RunningAverage[] getDiffs(long userID, long itemID, PreferenceArray prefs) throws TasteException; - + /** @return {@link RunningAverage} encapsulating the average preference for the given item */ RunningAverage getAverageItemPref(long itemID) throws TasteException; - + /** - *

Updates internal data structures to reflect an update in a preference value for an item.

- * - * @param itemID item to update preference value for - * @param prefDelta amount by which preference value changed (or its old value, if being removed - * @param remove if true, operation reflects a removal rather than change of preference + *

+ * Updates internal data structures to reflect an update in a preference value for an item. + *

+ * + * @param itemID + * item to update preference value for + * @param prefDelta + * amount by which preference value changed (or its old value, if being removed + * @param remove + * if true, operation reflects a removal rather than change of preference */ void updateItemPref(long itemID, float prefDelta, boolean remove) throws TasteException; - + /** - * @return item IDs that may possibly be recommended to the given user, which may not be all items since - * the item-item diff matrix may be sparse + * @return item IDs that may possibly be recommended to the given user, which may not be all items since the + * item-item diff matrix may be sparse */ FastIDSet getRecommendableItemIDs(long userID) throws TasteException; - + } Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/ItemSimilarity.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/ItemSimilarity.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/ItemSimilarity.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/ItemSimilarity.java Sat Feb 13 20:54:05 2010 @@ -21,22 +21,29 @@ import org.apache.mahout.cf.taste.common.TasteException; /** - *

Implementations of this interface define a notion of similarity between two items. Implementations should - * return values in the range -1.0 to 1.0, with 1.0 representing perfect similarity.

- * + *

+ * Implementations of this interface define a notion of similarity between two items. Implementations should + * return values in the range -1.0 to 1.0, with 1.0 representing perfect similarity. + *

+ * * @see UserSimilarity */ public interface ItemSimilarity extends Refreshable { - + /** - *

Returns the degree of similarity, of two items, based on the preferences that - * users have expressed for the items.

- * - * @param itemID1 first item ID - * @param itemID2 second item ID + *

+ * Returns the degree of similarity, of two items, based on the preferences that users have expressed for + * the items. + *

+ * + * @param itemID1 + * first item ID + * @param itemID2 + * second item ID * @return similarity between the items, in [-1,1] - * @throws TasteException if an error occurs while accessing the data + * @throws TasteException + * if an error occurs while accessing the data */ double itemSimilarity(long itemID1, long itemID2) throws TasteException; - + } Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/PreferenceInferrer.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/PreferenceInferrer.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/PreferenceInferrer.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/PreferenceInferrer.java Sat Feb 13 20:54:05 2010 @@ -21,20 +21,27 @@ import org.apache.mahout.cf.taste.common.TasteException; /** - *

Implementations of this interface compute an inferred preference for a user and an item that the - * user has not expressed any preference for. This might be an average of other preferences scores from that user, for - * example. This technique is sometimes called "default voting".

+ *

+ * Implementations of this interface compute an inferred preference for a user and an item that the user has + * not expressed any preference for. This might be an average of other preferences scores from that user, for + * example. This technique is sometimes called "default voting". + *

*/ public interface PreferenceInferrer extends Refreshable { - + /** - *

Infers the given user's preference value for an item.

- * - * @param userID ID of user to infer preference for - * @param itemID item ID to infer preference for + *

+ * Infers the given user's preference value for an item. + *

+ * + * @param userID + * ID of user to infer preference for + * @param itemID + * item ID to infer preference for * @return inferred preference - * @throws TasteException if an error occurs while inferring + * @throws TasteException + * if an error occurs while inferring */ float inferPreference(long userID, long itemID) throws TasteException; - + } Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/UserSimilarity.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/UserSimilarity.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/UserSimilarity.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/similarity/UserSimilarity.java Sat Feb 13 20:54:05 2010 @@ -21,28 +21,38 @@ import org.apache.mahout.cf.taste.common.TasteException; /** - *

Implementations of this interface define a notion of similarity between two users. Implementations should - * return values in the range -1.0 to 1.0, with 1.0 representing perfect similarity.

- * + *

+ * Implementations of this interface define a notion of similarity between two users. Implementations should + * return values in the range -1.0 to 1.0, with 1.0 representing perfect similarity. + *

+ * * @see ItemSimilarity */ public interface UserSimilarity extends Refreshable { - + /** - *

Returns the degree of similarity, of two users, based on the their preferences.

- * - * @param userID1 first user ID - * @param userID2 second user ID + *

+ * Returns the degree of similarity, of two users, based on the their preferences. + *

+ * + * @param userID1 + * first user ID + * @param userID2 + * second user ID * @return similarity between the two users, in [-1,1] - * @throws TasteException if an error occurs while accessing the data + * @throws TasteException + * if an error occurs while accessing the data */ double userSimilarity(long userID1, long userID2) throws TasteException; - + /** - *

Attaches a {@link PreferenceInferrer} to the {@link UserSimilarity} implementation.

- * - * @param inferrer {@link PreferenceInferrer} + *

+ * Attaches a {@link PreferenceInferrer} to the {@link UserSimilarity} implementation. + *

+ * + * @param inferrer + * {@link PreferenceInferrer} */ void setPreferenceInferrer(PreferenceInferrer inferrer); - + } Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/transforms/PreferenceTransform.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/transforms/PreferenceTransform.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/transforms/PreferenceTransform.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/transforms/PreferenceTransform.java Sat Feb 13 20:54:05 2010 @@ -22,13 +22,15 @@ import org.apache.mahout.cf.taste.model.Preference; /** - *

Implementations encapsulate a transform on a {@link Preference}'s value. These transformations are typically - * applied to values before they are used to compute a similarity value. They are typically not applied elsewhere; in - * particular {@link org.apache.mahout.cf.taste.model.DataModel}s no longer use a transform like this to transform all - * of their preference values at the source.

+ *

+ * Implementations encapsulate a transform on a {@link Preference}'s value. These transformations are + * typically applied to values before they are used to compute a similarity value. They are typically not + * applied elsewhere; in particular {@link org.apache.mahout.cf.taste.model.DataModel}s no longer use a + * transform like this to transform all of their preference values at the source. + *

*/ public interface PreferenceTransform extends Refreshable { - + float getTransformedValue(Preference pref) throws TasteException; - + } \ No newline at end of file Modified: lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/transforms/SimilarityTransform.java URL: http://svn.apache.org/viewvc/lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/transforms/SimilarityTransform.java?rev=909912&r1=909911&r2=909912&view=diff ============================================================================== --- lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/transforms/SimilarityTransform.java (original) +++ lucene/mahout/trunk/core/src/main/java/org/apache/mahout/cf/taste/transforms/SimilarityTransform.java Sat Feb 13 20:54:05 2010 @@ -20,15 +20,18 @@ import org.apache.mahout.cf.taste.common.Refreshable; /** - *

Implementations encapsulate some transformation on similarity values between two things, where things might be - * IDs of users or items or something else.

+ *

+ * Implementations encapsulate some transformation on similarity values between two things, where things might + * be IDs of users or items or something else. + *

*/ public interface SimilarityTransform extends Refreshable { - + /** - * @param value original similarity between thing1 and thing2 (should be in [-1,1]) + * @param value + * original similarity between thing1 and thing2 (should be in [-1,1]) * @return transformed similarity (should be in [-1,1]) */ double transformSimilarity(long id1, long id2, double value); - + }