LensKit

LensKit is an implementation of collaborative filtering algorithms and a set of tools for benchmarking them. This readme is about working with the LensKit source code. For more information about LensKit and its documentation, visit the web site or wiki. You can also find information on the wiki about how to use LensKit without downloading the source code. If this is your first time working with LensKit we recommend checking out the Getting Started guide.

LensKit is made available under the MIT license; see LICENSE.md.

Installation and Dependency Management

LensKit is built and deployed with Gradle and publishes its artifacts to Maven Central. To install it to the local Maven repository, making it available to other projects using standard Java-based tools, check out this repository and run ./gradlew install; it is then available to other projects by depending directly on it in your Maven, Gradle, Ivy, or SBT project. The source code can also be checked out and used in most Java IDEs.

Working with the Code

To work with the LensKit code, import the Gradle project into your IDE. Most modern Java IDEs include support for Gradle, including IntelliJ IDEA (used by most LensKit developers), Eclipse, and NetBeans.

No other particular setup is needed.

Modules

LensKit is comprised of several modules. The top-level lenskit module serves as a container to build them and provide common settings and dependencies. The other modules are as follows:

lenskit-api -- the common, public recommender API exposed by LensKit, independent of its actual implementations.
lenskit-test -- infrastructure and helper code for testing.
lenskit-core -- the core support code and configuration facilities for the rest of LensKit. It is the entry point for most of what you want to do with LensKit, providing support for configuring and building recommenders.
lenskit-knn -- k-NN recommenders (user-user and item-item collaborative filtering).
lenskit-svd -- the FunkSVD recommender (and eventually real SVD recommenders).
lenskit-slopeone -- Slope-One recommenders.
lenskit-eval -- the evaluation framework and APIs, along with a command line evaluation runner.
lenskit-groovy -- support for reading LensKit configurations from Groovy files.
lenskit-all -- a metapackage you can depend on to pull in the rest of the LensKit packages.
lenskit-cli -- the LensKit command line interface.
lenskit-gradle -- the Gradle plugin to script the LensKit evaluator
lenskit-integration-tests -- additional integration tests for LensKit.

Running the Tests

After you make changes, it's good to run the unit tests. You can run many of them from your IDE; run all tests in the org.grouplens.lenskit package (and subpackages) across all modules.

To run the full test suite, including data-driven unit tests and integration tests, use Gradle:

$ ./gradlew check

Copyright

LensKit is under the following copyright and license:

Copyright 2014-2017 LensKit Contributors. Copyright 2010-2014 Regents of the University of Minnesota Work on LensKit has been funded by the National Science Foundation under grants IIS 05-34939, 08-08692, 08-12148, and 10-17697.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contributing to LensKit

We welcome contribution to LensKit. If you are looking for something to work on, we recommend perusing the open tickets on GitHub or asking on the mailing list.

We prefer to receive code submissions as GitHub pull requests. To do this:

Fork the LensKit repository (lenskit/lenskit) on GitHub
Push your changes to your fork
Submit a pull request via the GitHub web interface

For additional details, including legal maters, please see CONTRIBUTING.md.