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

    java.lang.Object
      org.apache.mahout.cf.taste.impl.recommender.AbstractRecommender
          org.apache.mahout.cf.taste.impl.recommender.TreeClusteringRecommender2

All Implemented Interfaces:
  Refreshable, ClusteringRecommender, Recommender

    public final class TreeClusteringRecommender2

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.

This is an experimental implementation which tries to gain a lot of speed at the cost of accuracy in building clusters, compared to `TreeClusteringRecommender`. It will sometimes cluster two other clusters together that may not be the exact closest two clusters in existence. This may not affect the recommendation quality much, but it potentially speeds up the clustering process dramatically.

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

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

### TreeClusteringRecommender2

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

Parameters:
  `dataModel` - `DataModel` which provides 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`

### TreeClusteringRecommender2

    public TreeClusteringRecommender2(DataModel dataModel,
                                      ClusterSimilarity clusterSimilarity,
                                      double clusteringThreshold)
                               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
Throws:
  `java.lang.IllegalArgumentException` - if arguments are `null`, or `clusteringThreshold` is `Double.NaN`
  `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.