/** * Component that truncates vectors. */ @DefaultImplementation(NoOpTruncator.class) public interface VectorTruncator { /** * Truncate a vector, removing any entries that do not satisfy some condition. * * @param v The vector to truncate. */ Long2DoubleMap truncate(Long2DoubleMap v); }
/** * Abstraction of strategies for iterating over potential neighboring items. This is used by the * item-item model builder to iterate over the potential neighbors of an item. It is abstracted * so that different strategies can be used depending on the properties of the similarity function * and data set. * * @since 2.1 * @author <a href="http://www.grouplens.org">GroupLens Research</a> */ @DefaultProvider(DefaultNeighborIterationStrategyProvider.class) public interface NeighborIterationStrategy { /** * Get an iterator over possible neighbors of an item. * @param context The build context (to get item & neighbor information). * @param item The item ID. The item may or may not be included in the returned items. * @param onlyAfter If {@code true}, only consider item IDs after {@code item}, because * the caller only needs unique unordered pairs. * @return An iterator over possible neighbors of {@code item}. */ LongIterator neighborIterator(ItemItemBuildContext context, long item, boolean onlyAfter); }
/** * Normalizes an item's vector. */ @DefaultImplementation(DefaultItemVectorNormalizer.class) public interface ItemVectorNormalizer { /** * Make a vector transformation for a item. The resulting transformation will be applied * to item vectors to normalize and denormalize them. * * @param itemId The item ID to normalize for. * @param vector The item's vector to use as the reference vector. * @return The vector transformation normalizing for this item. */ InvertibleFunction<Long2DoubleMap,Long2DoubleMap> makeTransformation(long itemId, Long2DoubleMap vector); }
/** * The Poisson Factorization Model. This extends the SVD model. * * Poisson Factorization models each item as a vector of K latent attributes, * and each user as a vector of K latent preferences. * Then each rating is modeled as a Poisson distribution, * and the rate (mean) of the Poisson distribution is the inner product of * corresponding item latent vector and user latent vector. */ @DefaultProvider(HPFModelParallelProvider.class) @Shareable public final class HPFModel extends MFModel { private static final long serialVersionUID = 4L; /** * Construct a Poisson Factorization Model. * @param umat The user feature matrix (users x features). * @param imat The item feature matrix (items x features). * @param uidx The user index mapping * @param iidx The item index mapping */ public HPFModel(RealMatrix umat, RealMatrix imat, KeyIndex uidx, KeyIndex iidx) { super(umat, imat, uidx, iidx); } }
/** * Score an item using a neighborhood of users. */ @DefaultImplementation(WeightedAverageUserNeighborhoodScorer.class) public interface UserNeighborhoodScorer { /** * Compute the score for an item given a list of neighbors. * @param item The item to score. * @param neighbors The list of neighbors. * @return The result, or {@code null}. */ @Nullable UserUserResult score(long item, List<Neighbor> neighbors); }
/** * Bias model that provides global and item biases. The item biases are precomputed and are *not* updated based on * new data added since the model builds */ @Shareable @Immutable @DefaultProvider(ItemAverageRatingBiasModelProvider.class) public class ItemBiasModel extends UserItemBiasModel { private static final long serialVersionUID = 1L; /** * Construct a new item bias model. * @param global The global bias. * @param items The item biases. */ public ItemBiasModel(double global, Long2DoubleMap items) { super(global, Long2DoubleMaps.EMPTY_MAP, items); } }
/** * Determine whether similarity values should be accepted into * or rejected from similarity models. */ @DefaultImplementation(RealThreshold.class) public interface Threshold { /** * Checks a similarity value against retention criteria for * inclusion in similarity models. * * @param sim The double similarity value to check against * the threshold. * @return {@code true} if the parameter similarity value should be * retained in the similarity model, false otherwise. */ boolean retain(double sim); }
/** * Bias model that provides global and user biases. The user biases are precomputed and are *not* refreshed based * on user data added since the model build. */ @Shareable @Immutable @DefaultProvider(UserAverageRatingBiasModelProvider.class) public class UserBiasModel extends UserItemBiasModel { private static final long serialVersionUID = 1L; /** * Construct a new user bias model. * @param global The global bias. * @param users The user biases. */ public UserBiasModel(double global, Long2DoubleMap users) { super(global, users, Long2DoubleMaps.EMPTY_MAP); } }
/** * Function for clamping user-item data, typically a preference or rating. * * @author <a href="http://www.grouplens.org">GroupLens Research</a> * @since 0.11 */ @DefaultImplementation(IdentityClampingFunction.class) public interface ClampingFunction { /** * Clamp a value. * * @param user The user ID. * @param item The item ID. * @param value The value to clamp. * @return The clamped value. */ double apply(long user, long item, double value); }
/** * Finds candidate neighbors for a user. * * @author <a href="http://www.grouplens.org">GroupLens Research</a> * @since 2.1 */ @DefaultImplementation(LiveNeighborFinder.class) public interface NeighborFinder { /** * Get potential neighbors for a particular user. * * @param user The user ID whose neighbors are wanted. * @param items The items that the client needs to be able to score or recommend. * @return A collection of potential neighbors for {@code user}. This collection may include * neighbors that are not useful for scoring any item in {@code items}; the item set * is just to help the neighbor finder guide its search if relevant. */ Iterable<Neighbor> getCandidateNeighbors(long user, LongSet items); }
/** * Strategy of splitting ratings data into training data and validation data. * * @author <a href="http://www.grouplens.org">GroupLens Research</a> */ @DefaultImplementation(RandomDataSplitStrategy.class) public interface DataSplitStrategy { /** * Get a list of item ratings * * @return The training list of RatingMatrixEntry */ List<RatingMatrixEntry> getTrainRatings(); /** * Get a list of validation ratings * * @return The validation list of RatingMatrixEntry */ List<RatingMatrixEntry> getValidationRatings(); KeyIndex getUserIndex(); KeyIndex getItemIndex(); }
/** * Proxy DAO for user 'rating vectors', which are mappings of items to user preference. This is used * to access use ratings, or to transform other types of data into something that looks like a rating vector. * * This DAO interface is generally *proxy DAO*: that is, it provides a different view of data typically implemented * on top of the base {@link org.lenskit.data.dao.DataAccessObject} interface. However, an application can specialize * it with some other kind of optimized implementation if desired; for example, if user rating vectors are stored in * a Redis cache. */ @DefaultImplementation(StandardRatingVectorPDAO.class) public interface RatingVectorPDAO { /** * Get a user's rating vector. * @param user The rating vector summarizing a user's historical preferences. * @return The unnormmalized user rating vector. Will return an empty vector for nonexistent users. */ @Nonnull Long2DoubleMap userRatingVector(long user); /** * Stream all users in the data set. * @return A stream over the users in the data set. */ ObjectStream<IdBox<Long2DoubleMap>> streamUsers(); }
/** * Compute scores from neighborhoods and score vectors. * * <p> * This interface encapsulates aggregating user scores and item similarities into a final * score. The neighborhood is pre-filtered to only contain items for which * scores are available, and truncated to the neighborhood size, so all functions * implementing this interface need to do is accumulate scores. * * @author <a href="http://www.grouplens.org">GroupLens Research</a> */ @DefaultImplementation(WeightedAverageNeighborhoodScorer.class) public interface NeighborhoodScorer { /** * Compute a score based on similar neighbors and their corresponding * scores. * * @param item The item ID to score. * @param neighbors A vector of neighbors with similarity measures. * @param scores A vector of item scores. It should contain a score for * every item in <var>neighbors</var>. * @param accum An accumulator to receive the score computed by this method. */ void score(long item, Long2DoubleMap neighbors, Long2DoubleMap scores, ItemItemScoreAccumulator accum); }
@DefaultImplementation(ItemVectorSimilarity.class) public interface ItemSimilarity {
@DefaultImplementation(CosineVectorSimilarity.class) public interface VectorSimilarity {
@DefaultImplementation(IdentityVectorNormalizer.class) public interface VectorNormalizer {
@DefaultImplementation(SimilarityMatrixModel.class) public interface ItemItemModel {
@DefaultImplementation(DefaultUserVectorNormalizer.class) public interface UserVectorNormalizer {
@DefaultImplementation(UserVectorSimilarity.class) public interface UserSimilarity {
/** * Construct the item scorer. * * @param model The model. * @param baseline The baseline scorer. Be very careful when configuring a different baseline * at runtime than at model-build time; such a configuration is unlikely to * perform well. * @param dom The preference domain. */ @Inject public FunkSVDItemScorer(@DefaultImplementation(FunkSVDModel.class) MFModel model, BiasModel baseline, @Nullable PreferenceDomain dom) { super(model, baseline); domain = dom; }