Upgrading to LensKit 1.1

LensKit 1.1 maintains backwards compatibility in its core APIs, but introduces a number of changes and refactorings that require algorithm configurations to be updated.

Mandatory Updates

Parameter moves

All params packages have been removed, with the parameters moved directly into the packages they affect. In a few cases, a parameter has been split into multiple parameters to better-reflect its multiple uses and reduce the need for context-sensitive configuration to just set parameter values. To update your configuration, you mostly just need to change it to use the new package and class names. For split parameters (such as @Damping), you will need to also update the configuration to use the appropriate new parameter.

• The previously-overloaded @Damping is removed:
  • Similarity damping is now configured with [o.g.l.vectors.similarity.SimilarityDamping][]
  • Slope-One deviation damping is now configured with [o.g.l.slopeone.DeviationDamping][]
  • Baseline and normalizer mean damping is now configured with [o.g.l.baseline.MeanDamping][].
• @EventType is now in o.g.l.data.event
• @SigWeightThreshold is now in o.g.l.vectors.similarity
• @ThresholdValue is now in o.g.l.transform.threshold
• Item-item @ModelSize is now in o.g.l.knn.item
• Neighborhood size is now o.g.l.knn.NeighborhoodSize
• @IterationCount and @MinimumIterations are now in o.g.l.iterative
• @ThresholdValue is now split into o.g.l.iterative.StoppingThreshold (for loop stopping) and o.g.l.transform.threshold.ThresholdValue (for general thresholding).
• Funk-SVD @FeatureCount is now in o.g.l.funksvd
• All iterative method parameters (learning rate, stopping threshold, iteration count) are now in o.g.l.iterative.

Default value changes

The default values of a few parameters have now changed. If you were previously using the default values, and want to keep the old values, you will need to add explicit settings to your configuration.

• o.g.l.iterative.MinimumIterations now defaults to 10 (under previous name, was 25)
• New o.g.l.iterative.StoppingThreshold has no default
• o.g.l.knn.NeighborhoodSize now defaults to 20 (was 30)
• o.g.l.knn.item.ModelSize now defaults to 0 (unlimited; was 250)

Item scorers, rating predictors, and baselines

Prior to 1.1, RatingPredictor was just a tag interface that indicates that an ItemScorer produces scores that are interpretable as ratings. In 1.1, it has been given methods of its own and the fact that it extends ItemScorer is deprecated. With this, we have refactored the way item scorers work and are provided by the various algorithms.

If you just replace all RatingPredictor bindings with ItemScorer bindings (e.g. ItemScorer → ItemItemScorer), the default implementation of RatingPredictor (SimpleRatingPredictor) will be available and provide the original behavior — the baseline predictor will be consulted for ratings that the item scorer cannot score, and scores will be clamped to the preference domain's range.

We have removed the baseline prediction logic from all item scorers; they will no longer substitute baseline values if they cannot predict. Substituting baseline predictions is now the job of the rating predictor, or a wrapper component. The TopNItemRecommender, however, will only use the item scorer.

The result of this change is that default configurations will no longer consider baseline-scored items as recommendation candidates. If you want them to be configured, the BaselineItemScorer now has two modes. By default, it just uses a baseline predictor to generate scores. It now has an optional dependency on an item scorer qualified with @PrimaryScorer; if such as scorer is provided, it will use that scorer first and only consult the baseline for items that the primary scorer cannot score. By default, @PrimaryScorer will be null. To configure a primary scorer, do this:

bind (PrimaryScorer, ItemScorer) to ItemItemScorer // or whatever

The baseline item scorer will then use this scorer and delegate to it first, before consulting the baseline predictor. If you do this, you can no longer use the deprecated algorithm-specific ItemRecommender implementations; leave the ItemRecommender unbound and the default Top-N recommender will replicate the original behavior.

FunkSVD structure

Prior to LensKit 1.1, the Funk-SVD model builder took both @IterationCount and @ThresholdValue parameters and examined them to determine which stopping condition to be used. It now uses a StoppingCondition component to decide when to stop training each feature. The default is IterationCountStoppingCondition, which maintains the old default behavior of stopping after a fixed number of iterations. The @IterationCount parameter, now moved to org.grouplens.lenskit.iterative in lenskit-core, still controls this iteration count.

To use a threshold on the change in RMSE to stop, use a ThresholdStoppingCondition:

bind StoppingCondition to ThresholdStoppingCondition
set StoppingThreshold to 0.00001

Optional Updates

Some components are still in place and functional, but have been deprecated and will be removed in LensKit 2.0. These are:

• ScoreBasedItemRecommender and ScoreBasedGlobalItemRecommender. These have been replaced by TopNItemRecommender and TopNGlobalItemRecommender in the new o.g.l.baskc package. The old classes are still there as deprecated no-op subclasses of the new classes.
• The specific ItemRecommender implementations for each algorithm family. Now, to specify that you want an item-item recommender, just bind ItemScorer to ItemItemScorer; a TopNItemRecommender will automatically be available using the scorer with the same core recommendation logic as the previous code where you would configure an ItemItemRecommender.