org.grouplens.lenskit

Interface ItemRecommender

All Known Implementing Classes:

AbstractItemRecommender, RescoringItemRecommender, TopNItemRecommender

public interface ItemRecommender

Interface for recommending items. Several methods are provided, of varying generality.

The core idea of the recommend API is to recommend n items for a user, where the items recommended are taken from a set of candidate items and further constrained by an exclude set of forbidden items. Items in the candidate set but not in the exclude set are considered viable for recommendation.

Candidate Items

By default, the candidate set is the universe of all items the recommender knows about. The default exclude set is somewhat more subtle. Its exact definition varies across implementations, but will be the set of items the system believes the user will not be interested in by virtue of already having or knowing about them. For example, rating-based recommenders will exclude the items the user has rated, and purchase-based recommenders will typically exclude items the user has purchased. Some implementations may allow this to be configured. Client code always has the option of manually specifying the exclude set, however, so applications with particular needs in this respect can manually provide the sets they need respected.

Ordering

If the recommender has an opinion about the order in which recommendations should be displayed, it will return the items in that order. For many recommenders, this will be descending order by score; however, this interface imposes no such limitation.

Compatibility

Public

Method Summary

Modifier and Type	Method and Description
List<ScoredId>	recommend(long user) Recommend all possible items for a user using the default exclude set.
List<ScoredId>	recommend(long user, int n) Recommend up to n items for a user using the default exclude set.
List<ScoredId>	recommend(long user, int n, Set<Long> candidates, Set<Long> exclude) Produce a set of recommendations for the user.
List<ScoredId>	recommend(long user, Set<Long> candidates) Recommend all possible items for a user from a set of candidates using the default exclude set.

Method Detail

recommend

List<ScoredId> recommend(long user)

Recommend all possible items for a user using the default exclude set.

Parameters:

user - The user ID.

Returns:

The recommended items.

See Also:

recommend(long, int, Set, Set)

recommend

List<ScoredId> recommend(long user,
                         int n)

Recommend up to n items for a user using the default exclude set.

Parameters:

user - The user ID.

n - The number of recommendations to return.

Returns:

The recommended items.

See Also:

recommend(long, int, Set, Set)

recommend

List<ScoredId> recommend(long user,
                         @Nullable
                         Set<Long> candidates)

Recommend all possible items for a user from a set of candidates using the default exclude set.

Parameters:

user - The user ID.

candidates - The candidate set (can be null to represent the universe).

Returns:

The recommended items.

See Also:

recommend(long, int, Set, Set)

recommend

List<ScoredId> recommend(long user,
                         int n,
                         @Nullable
                         Set<Long> candidates,
                         @Nullable
                         Set<Long> exclude)

Produce a set of recommendations for the user. This is the most general recommendation method, allowing the recommendations to be constrained by both a candidate set and an exclude set. The exclude set is applied to the candidate set, so the final effective candidate set is canditates minus exclude.

Parameters:

user - The user's ID

n - The number of ratings to return. If negative, there is no specific recommendation list size requested.

candidates - A set of candidate items which can be recommended. If null, all items are considered candidates.

exclude - A set of items to be excluded. If null, a default exclude set is used.

Returns:

A list of recommended items. If the recommender cannot assign meaningful scores, the scores will be Double.NaN. For most scoring recommenders, the items will be ordered in decreasing order of score. This is not a hard requirement — e.g. set recommenders are allowed to be more flexible.