GettingStarted

Most people who want to work with LensKit will want to use the LensKit libraries to create their own projects, with their own recommenders. The LensKit libraries make it easier to develop your recommenders and to compare them with world-class implementations of the best-known previously created recommenders, which are already built into LensKit. This document is focused on getting started building your own LensKit project.

Since LensKit is open source, you can always download the source code and work from there. However, most users of LensKit will be able to start from the version of LensKit installed in the Maven repository. With that version you can create your own recommenders and test them against the recommenders built in to LensKit. You can read about starting with the source code elsewhere in this manual. Here we'll discuss how to use LensKit without having to download the sources.

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 do this in a Maven project, add the following to the <dependencies> section of your application's pom.xml:

<dependency>
  <groupId>org.grouplens.lenskit</groupId>
  <artifactId>lenskit-all</artifactId>
  <version>2.0.5</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 Gradle, SBT, Ivy, or any other Maven-compatible dependency resolver. If you don't want to use Maven to 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:

LenskitConfiguration config = new LenskitConfiguration()
// Use item-item CF to score items
config.bind(ItemScorer.class)
      .to(ItemItemScorer.class);
// let's use personalized mean rating as the baseline/fallback predictor.
// 2-step process:
// First, use the user mean rating as the baseline scorer
config.bind(BaselineScorer.class, ItemScorer.class)
      .to(UserMeanItemScorer.class);
// Second, use the item mean rating as the base for user means
config.bind(UserMeanBaseline.class, ItemScorer.class)
      .to(ItemMeanRatingItemScorer.class);
// and normalize ratings by baseline prior to computing similarities
config.bind(UserVectorNormalizer.class)
      .to(BaselineSubtractingUserVectorNormalizer.class);

Connecting the Data Source

LensKit also requires a data source. To keep things simple, we'll just use a CSV file:

config.bind(EventDAO.class).to(new SimpleFileRatingDAO(new File("ratings.csv"), ","));

Creating the Recommender

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

LenskitRecommender rec = LenskitRecommender.create(config);

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();
List<ScoredId> 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();
double score = pred.predict(42, 17);

More Reading

• Configuration — more on configuring LensKit
• Anatomy of a Recommender
• DataAccess — how to connect LensKit to more interesting data sources
• ExperimentQuickStart — how to run an experiment comparing different algorithms using an offline data set