## org.apache.mahout.cf.taste.impl.recommender
Class TreeClusteringRecommender

    java.lang.Object
      org.apache.mahout.cf.taste.impl.recommender.AbstractRecommender
          org.apache.mahout.cf.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(long, long)` 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.

Constructor Summary
`TreeClusteringRecommender(DataModel dataModel, ClusterSimilarity clusterSimilarity, double clusteringThreshold)`
`TreeClusteringRecommender(DataModel dataModel, ClusterSimilarity clusterSimilarity, double clusteringThreshold, double samplingRate)`
`TreeClusteringRecommender(DataModel dataModel, ClusterSimilarity clusterSimilarity, int numClusters)`
`TreeClusteringRecommender(DataModel dataModel, ClusterSimilarity clusterSimilarity, int numClusters, double samplingRate)`

Method Summary
`float` `estimatePreference(long userID, long itemID)`
`FastIDSet` `getCluster(long userID)` Returns the cluster of users to which the given user, denoted by user ID, belongs.
`FastIDSet[]` `getClusters()` Returns all clusters of users.
`java.util.List<RecommendedItem>` `recommend(long userID, int howMany, IDRescorer rescorer)`
`void` `refresh(java.util.Collection<Refreshable> alreadyRefreshed)` Triggers "refresh" -- whatever that means -- of the implementation.
`java.lang.String` `toString()`

Methods inherited from class org.apache.mahout.cf.taste.impl.recommender.AbstractRecommender
`getAllOtherItems, getDataModel, getDefaultCandidateItemsStrategy, recommend, removePreference, setPreference`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Methods inherited from interface org.apache.mahout.cf.taste.recommender.Recommender
`getDataModel, recommend, removePreference, setPreference`

Constructor Detail

### TreeClusteringRecommender

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

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

### TreeClusteringRecommender

    public TreeClusteringRecommender(DataModel dataModel,
                                     ClusterSimilarity clusterSimilarity,
                                     int numClusters,
                                     double samplingRate)
                              throws TasteException

Parameters:
  `dataModel` - `DataModel` which provdes users
  `clusterSimilarity` - `ClusterSimilarity` used to compute cluster similarity
  `numClusters` - desired number of clusters to create
  `samplingRate` - 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 samplingRate is `Double.NaN` or nonpositive or greater than 1.0
  `TasteException`

### TreeClusteringRecommender

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

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

### TreeClusteringRecommender

    public TreeClusteringRecommender(DataModel dataModel,
                                     ClusterSimilarity clusterSimilarity,
                                     double clusteringThreshold,
                                     double samplingRate)
                              throws TasteException

Parameters:
  `dataModel` - `DataModel` which provides 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
  `samplingRate` - 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 samplingRate is `Double.NaN` or nonpositive or greater than 1.0
  `TasteException`

Method Detail

### recommend

    public java.util.List<RecommendedItem> recommend(long userID,
                                                     int howMany,
                                                     IDRescorer 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 `RecommendedItem`s, ordered from most strongly recommend to least
  Throws:
    `TasteException` - if an error occurs while accessing the `DataModel`

### estimatePreference

    public float estimatePreference(long userID,
                                    long 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

    public FastIDSet getCluster(long userID)
                         throws TasteException

  Description copied from interface: `ClusteringRecommender`

  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:
    `FastIDSet` of IDs of users in the requested user's cluster
  Throws:
    `TasteException` - if an error occurs while accessing the `DataModel`

### getClusters

    public FastIDSet[] getClusters()
                            throws TasteException

  Description copied from interface: `ClusteringRecommender`

  Returns all clusters of users.

  Specified by:
    `getClusters` in interface `ClusteringRecommender`
  Returns:
    array of `FastIDSet`s of user IDs
  Throws:
    `TasteException` - if an error occurs while accessing the `DataModel`

### refresh

    public void refresh(java.util.Collection<Refreshable> alreadyRefreshed)

  Description copied from interface: `Refreshable`

  Triggers "refresh" -- whatever that means -- of the implementation. The general contract is that any 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`
  Parameters:
    `alreadyRefreshed` - s that are known to have already been refreshed as a result of an initial call to a method on some object. This ensure that objects in a refresh dependency graph aren't refreshed twice needlessly.

### toString

    public java.lang.String toString()

  Overrides:
    `toString` in class `java.lang.Object`

Copyright © 2008-2010 The Apache Software Foundation. All Rights Reserved.