Getting Started with LensKit

This chapter describes how to embed LensKit in an application.

The lenskit-hello project provides a working example of configuring, building, and using a recommender. This document is based on that code.

Getting LensKit

We recommend getting LensKit from the Maven central repositories. To use it from a Gradle project, add the following to your build.gradle:

repositories {
    mavenCentral()
}
dependencies {
    compile 'org.grouplens.lenskit:lenskit-all:3.0-M1'
}

Or in Maven:

<dependency>
  <groupId>org.grouplens.lenskit</groupId>
  <artifactId>lenskit-all</artifactId>
  <version>3.0-M1</version>
</dependency>

lenskit-all will pull in all of LensKit except the command line interface. You can instead depend on the particular pieces of LensKit that you need, if you want. But lenskit-all is a good way to get started.

You can also retrieve LensKit from Maven using SBT, Ivy, or any other Maven-compatible dependency resolver. If you don’t want to let your build system manage your dependencies, download the binary distribution and put the JARs in your project’s library directory.

Configuring the Recommender

In order to use LensKit, you first need to configure the LensKit algorithm you want to use. This consists primarily of selecting the component implementations you want and configuring them with a LenskitConfiguration. For example, to configure a basic item-item kNN recommender with baseline, use the following configuration (save it in a file, such as item-item.groovy)

// Use item-item CF to score items
bind ItemScorer to ItemItemScorer
// let's use personalized mean rating as the baseline/fallback predictor.
// 2-step process:
// First, use the user-item bias to compute item scores
bind (BaselineScorer, ItemScorer) to BiasItemScorer
// Second, use user-item biases
bind BiasModel to LiveUserItemBiasModel
// and normalize ratings by baseline prior to computing similarities
bind (UserVectorNormalizer) to BiasUserVectorNormalizer
// little speed tweek
within (UserVectorNormalizer) {
    bind Biasmodel to UserItemBiasModel
}

You can then load that configuration in your Java program:

LenskitConfiguration config = ConfigHelpers.load(new File("item-item.groovy"))

Connecting the Data Source

LensKit also requires a data source. We can use one of the MovieLens data sets. Download the Latest-Small (or Latest) file from there. You will also need a data manifest to tell LensKit how to use it; download this one and save it in the MovieLens data directory (alongside the .csv files).

You can then load the data source:

StaticDataSource source = StaticDataSource.load("ml-latest-small/movielens.yml");

Creating the Recommender

You then need to create a recommender to actually be able to recommend:

LenskitRecommender rec = LenskitRecommender.build(config, source);

When you’re finished with a LenskitRecommender, close it with rec.close(). try-with-resources blocks work great for this:

try (LenskitRecommender rec = LenskitRecommender.build(config)) {
    /* do things */
}

Generating Recommendations

The recommender object provides access to components like ItemRecommender that can do the actual recommendation. For example, to generate 10 recommendations for user 42:

ItemRecommender irec = rec.getItemRecommender();
ResultList recommendations = irec.recommend(42, 10);

Since we did not configure an ItemRecommender when configuring LensKit, it uses the default: the TopNItemRecommender, which scores items using the configured ItemScorer and returns the N highest-scored items. Since we are using item-item CF, these scores are the raw predicted ratings from item-item collaborative filtering.

You can also also predict ratings with the RatingPredictor:

RatingPredictor pred = rec.getRatingPredictor();
Result score = pred.predict(42, 17);

Next Steps

This is just the beginning! There’s a lot more to explore in LensKit, including how to configure different recommenders, connecting to data sources, and evaluating recommenders.

Getting Started