com.planetj.taste.impl.recommender
Class TreeClusteringRecommender

java.lang.Object
  com.planetj.taste.impl.recommender.AbstractRecommender
      com.planetj.taste.impl.recommender.TreeClusteringRecommender

All Implemented Interfaces:

Refreshable, ClusteringRecommender, Recommender

public final class TreeClusteringRecommender
extends AbstractRecommender
implements ClusteringRecommender

A Recommender that clusters Users, then determines the clusters' top recommendations. This implementation builds clusters by repeatedly merging clusters until only a certain number remain, meaning that each cluster is sort of a tree of other clusters.

This Recommender therefore has a few properties to note:

• For all Users in a cluster, recommendations will be the same
• estimatePreference(Object, Object) may well return Double.NaN; it does so when asked to estimate preference for an Item for which no preference is expressed in the Users in the cluster.

Since:

1.1

Author:

Sean Owen

Constructor Summary

TreeClusteringRecommender(DataModel dataModel, ClusterSimilarity clusterSimilarity, double clusteringThreshold)

TreeClusteringRecommender(DataModel dataModel, ClusterSimilarity clusterSimilarity, double clusteringThreshold, double samplingPercentage)

TreeClusteringRecommender(DataModel dataModel, ClusterSimilarity clusterSimilarity, int numClusters)

TreeClusteringRecommender(DataModel dataModel, ClusterSimilarity clusterSimilarity, int numClusters, double samplingPercentage)

Method Summary

double	estimatePreference(java.lang.Object userID, java.lang.Object itemID)
java.util.Collection<User>	getCluster(java.lang.Object userID) Returns the cluster of users to which the given User, denoted by user ID, belongs.
java.util.Collection<java.util.Collection<User>>	getClusters() Returns all clusters of users.
java.util.List<RecommendedItem>	recommend(java.lang.Object userID, int howMany, Rescorer<Item> rescorer)
void	refresh() Triggers "refresh" -- whatever that means -- of the implementation. The general contract is that any Refreshable should always leave itself in a consistent, operational state, and that the refresh atomically updates internal state from old to new.
java.lang.String	toString()

Methods inherited from class com.planetj.taste.impl.recommender.AbstractRecommender

getAllOtherItems, getDataModel, recommend, removePreference, setPreference

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.planetj.taste.recommender.Recommender

getDataModel, recommend, removePreference, setPreference

Constructor Detail

TreeClusteringRecommender

public TreeClusteringRecommender(DataModel dataModel,
                                 ClusterSimilarity clusterSimilarity,
                                 int numClusters)

Parameters:

dataModel - DataModel which provdes Users

clusterSimilarity - ClusterSimilarity used to compute cluster similarity

numClusters - desired number of clusters to create

Throws:

java.lang.IllegalArgumentException - if arguments are null, or numClusters is less than 2

TreeClusteringRecommender

public TreeClusteringRecommender(DataModel dataModel,
                                 ClusterSimilarity clusterSimilarity,
                                 int numClusters,
                                 double samplingPercentage)

Parameters:

dataModel - DataModel which provdes Users

clusterSimilarity - ClusterSimilarity used to compute cluster similarity

numClusters - desired number of clusters to create

samplingPercentage - percentage of all cluster-cluster pairs to consider when finding next-most-similar clusters. Decreasing this value from 1.0 can increase performance at the cost of accuracy

Throws:

java.lang.IllegalArgumentException - if arguments are null, or numClusters is less than 2, or samplingPercentage is Double.NaN or nonpositive or greater than 1.0

Since:

1.4.5

TreeClusteringRecommender

public TreeClusteringRecommender(DataModel dataModel,
                                 ClusterSimilarity clusterSimilarity,
                                 double clusteringThreshold)

Parameters:

dataModel - DataModel which provdes Users

clusterSimilarity - ClusterSimilarity used to compute cluster similarity

clusteringThreshold - clustering similarity threshold; clusters will be aggregated into larger clusters until the next two nearest clusters' similarity drops below this threshold

Throws:

java.lang.IllegalArgumentException - if arguments are null, or clusteringThreshold is Double.NaN

Since:

1.1.1

TreeClusteringRecommender

public TreeClusteringRecommender(DataModel dataModel,
                                 ClusterSimilarity clusterSimilarity,
                                 double clusteringThreshold,
                                 double samplingPercentage)

Parameters:

dataModel - DataModel which provdes Users

clusterSimilarity - ClusterSimilarity used to compute cluster similarity

clusteringThreshold - clustering similarity threshold; clusters will be aggregated into larger clusters until the next two nearest clusters' similarity drops below this threshold

samplingPercentage - percentage of all cluster-cluster pairs to consider when finding next-most-similar clusters. Decreasing this value from 1.0 can increase performance at the cost of accuracy

Throws:

java.lang.IllegalArgumentException - if arguments are null, or clusteringThreshold is Double.NaN, or samplingPercentage is Double.NaN or nonpositive or greater than 1.0

Since:

1.4.5

Method Detail

recommend

@NotNull
public java.util.List<RecommendedItem> recommend(java.lang.Object userID,
                                                         int howMany,
                                                         Rescorer<Item> rescorer)
                                          throws TasteException

Specified by:

recommend in interface 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:

TasteException - if an error occurs while accessing the DataModel

estimatePreference

public double estimatePreference(java.lang.Object userID,
                                 java.lang.Object itemID)
                          throws TasteException

Specified by:

estimatePreference in interface Recommender

Parameters:

userID - user ID whose preference is to be estimated

itemID - item ID to estimate preference for

Returns:

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 Double.NaN

Throws:

TasteException - if an error occurs while accessing the DataModel

getCluster

@NotNull
public java.util.Collection<User> getCluster(java.lang.Object userID)
                                      throws TasteException

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

Specified by:

getCluster in interface ClusteringRecommender

Parameters:

userID - user ID for which to find a cluster

Returns:

Collection of Users in the requested user's cluster

Throws:

TasteException - if an error occurs while accessing the DataModel

getClusters

@NotNull
public java.util.Collection<java.util.Collection<User>> getClusters()
                                                             throws TasteException

Returns all clusters of users.

Specified by:

getClusters in interface ClusteringRecommender

Returns:

Collection of Collections of Users

Throws:

TasteException - if an error occurs while accessing the DataModel

refresh

public void refresh()

Triggers "refresh" -- whatever that means -- of the implementation. The general contract is that any Refreshable should always leave itself in a consistent, operational state, and that the refresh atomically updates internal state from old to new.

Specified by:

refresh in interface Refreshable

Overrides:

refresh in class AbstractRecommender

toString

@NotNull
public java.lang.String toString()

Overrides:

toString in class java.lang.Object