README.md

lenskit is a Java-based open-source toolkit for recommendation systems. This example shows how to use lenskit in your Ruby code via JRuby.

Using lenskit from Ruby

Example

$ ruby main.rb
Recommendations for user with id=0:
  [score(62) = 4.914649362279286, score(15) = 4.63731255034173, score(49) = 4.607799688330525, score(89) = 4.528461033828778, score(6) = 4.408179843204389]
Recommendations for user with id=1:
  [score(66) = 4.931632515735108, score(45) = 4.696943825952708, score(3) = 4.6625575654628335, score(15) = 4.5866827948589135, score(17) = 4.138864980730785]
Recommendations for user with id=2:
  [score(45) = 4.41033605687315, score(58) = 4.259395566799698, score(8) = 4.237214609505099, score(83) = 4.188428706960753, score(72) = 4.045670217692879]
Recommendations for user with id=3:
  [score(62) = 4.527597077214233, score(45) = 4.2550354023110595, score(49) = 4.220747403265472, score(76) = 4.135953313920664, score(17) = 4.051224458102281]

See example_runner.rb for implementation details. Note that the sample_data file is simply provided so that we have some useful output for this example.

Setup

Because we need to run native Java code, we'll need to use the JRuby interpreter. If you have RVM installed, that's easy:

rvm install jruby

Now, set JRuby as your interpreter:

rvm use jruby

We'll be using jbundler to automatically pull in the lenskit JAR files.

gem install jbundler

Finally, download the lenskit JAR files our code depends on:

jbundle

Purpose

Provide a simple starting point for interacting with lenskit in Ruby for those who would prefer working in Ruby to Java. You can clone this repository to bootstrap a new application and make sure that your lenskit dependencies are set up properly. This may be of special interest to those taking the Intro to Recommender Systems course.

Input

The input data defined in sample_data is a tab-delimited set of user_id, item_id, and rating tuples. This data represents simulated events wherein 20 users rated 100 arbitrary items on a scale from 0 to 5.

License & Notice

Do whatever the hell you want with this. Do not sue me. Be aware that I am not the original author of lenskit nor am I affiliated with grouplens.

example_runner.rb

module ExampleRunner
  import org.grouplens.lenskit
  import org.grouplens.lenskit.baseline
  import org.grouplens.lenskit.core
  import org.grouplens.lenskit.cursors
  import org.grouplens.lenskit.data.dao
  import org.grouplens.lenskit.knn.item
  import org.grouplens.lenskit.transform.normalize

  def item_recommender
    @item_recommender ||= recommender.get_item_recommender
  end

  def user_ids
    @user_ids ||= cached_events.stream_events.collect(&:user_id).uniq
  end

  private

  def recommender
    LenskitRecommender.build(config)
  end

  def config
    LenskitConfiguration.new.tap do |config|
      config.bind(EventDAO.java_class).to(cached_events)
      config.bind(ItemScorer.java_class).to(ItemItemScorer.java_class)
      config.bind(BaselineScorer.java_class, ItemScorer.java_class).to(ItemMeanRatingItemScorer.java_class)
      config.bind(UserMeanBaseline.java_class, ItemScorer.java_class).to(ItemMeanRatingItemScorer.java_class)
      config.bind(UserVectorNormalizer.java_class).to(BaselineSubtractingUserVectorNormalizer.java_class)
    end
  end

  def cached_events
    EventCollectionDAO.new(Cursors.makeList(raw_event_stream))
  end

  def raw_event_stream
    SimpleFileRatingDAO.new(input_file, "\t").stream_events
  end

  def input_file
    java.io.File.new('sample_data')
  end
end

Jarfile

# Include dependencies declared by lenskit-package to ensure we load all lenskit JAR files
# Reference: http://mvnrepository.com/artifact/org.grouplens.lenskit/lenskit-package/2.0
jar 'org.grouplens.lenskit:lenskit-core'
jar 'org.grouplens.lenskit:lenskit-eval'
jar 'org.grouplens.lenskit:lenskit-knn'
jar 'org.grouplens.lenskit:lenskit-slopeone'
jar 'org.grouplens.lenskit:lenskit-svd'

Jarfile.lock

org.grouplens.lenskit:lenskit-core:jar:2.0
it.unimi.dsi:fastutil:jar:6.5.6
org.grouplens.lenskit:lenskit-data-structures:jar:2.0
com.google.guava:guava:jar:14.0.1
org.apache.commons:commons-lang3:jar:3.1
org.grouplens.lenskit:lenskit-api:jar:2.0
org.grouplens.grapht:grapht:jar:0.6.0
javax.inject:javax.inject:jar:1
com.google.code.findbugs:jsr305:jar:1.3.9
org.slf4j:slf4j-api:jar:1.7.5
org.grouplens.lenskit:lenskit-eval:jar:2.0
org.grouplens.lenskit:lenskit-groovy:jar:2.0
org.codehaus.groovy:groovy-all:jar:2.1.5
commons-cli:commons-cli:jar:1.2
org.apache.ant:ant:jar:1.8.4
org.apache.ant:ant-launcher:jar:1.8.4
org.grouplens.lenskit:lenskit-knn:jar:2.0
org.grouplens.lenskit:lenskit-slopeone:jar:2.0
org.grouplens.lenskit:lenskit-svd:jar:2.0

main.rb

require 'jbundler'
require 'example_runner'

#In a real application, include this module in your Ruby class
include ExampleRunner

user_ids.each do |user_id|
  puts "Recommendations for user with id=#{user_id}:"
  puts "  #{item_recommender.recommend(user_id, 5)}"
end

sample_data

0  48	0.1001161486609381
0	80	1.9373323191087832
0	72	3.744815754301993
0	94	3.0960215864607745
0	19	0.9320990242698729
0	81	2.728479844065129
0	95	2.9821697731283
0	33	3.7430435429091617
0	46	1.9024094274651793
0	70	4.8363559518514885
1	74	3.06575955551509
1	29	1.498343419207454
1	91	2.6252467012269234
1	12	3.09145399377394
1	26	2.5548537152253106
1	50	0.004717076338155435
1	69	0.1104292265058987
1	93	1.2117684756838116
1	23	1.9384757741950338
1	52	2.753302296182821
1	92	4.284822073881195
1	49	3.001257050497915
1	11	3.504328495627143
1	87	2.8678164001335498
1	38	4.68362277926745
1	5	2.4862694329543897
1	25	0.5407750728667837
1	62	4.078726903130605
1	61	0.9586810869513324
2	5	1.0349680062252908
2	53	0.44067215488345746
2	48	1.7804654258321084
2	71	0.9090882641866938
2	66	4.138375973906359
2	73	3.5330206449710886
2	37	0.5955326793835813
2	2	0.9824348347810558
2	18	2.5903858259878056
2	80	1.6103376759786485
2	12	3.521676579785902
2	98	3.6937175480796514
3	13	1.325406421692863
3	9	4.6508260143127504
3	35	0.26413343182360993
3	18	0.6065149900276706
3	65	4.05786002175774
3	0	2.8220829388987383
3	4	0.872949256235932
3	91	3.0859711355848334
3	5	2.9134307327729143
3	24	4.613018785469789
3	89	3.6056617867841183
3	8	0.9601168456817227
3	59	2.4360600346095698
3	67	3.012345852286332
3	84	2.0394480425364003
3	16	0.6818516373378292
4	9	4.065738275839925
4	7	3.8720974730315167
4	77	2.533428954270014
4	55	3.7497684090120393
4	89	2.790855919452204
4	51	0.3485971291686474
4	21	4.61322569801786
4	6	1.4393983903484042
4	29	3.6856620697831954
4	67	2.373845030218256
4	48	4.26106195600837
4	70	0.06001513636341271
4	19	3.1175959758707723
5	23	1.6230458425508076
5	72	1.6863344802711318
5	70	3.070931221595057
5	39	2.417490425534019
5	60	3.91500115673601
5	96	0.5308017677373361
5	80	1.1990997610329512
5	27	1.2767667511445073
5	54	1.8899701931307655
5	26	2.331266407639177
5	22	0.1823052541280923
5	57	2.124767595312152
5	98	0.5898624181403078
5	73	2.7375894202999724
5	36	4.2199673597101235
6	46	2.108563087629582
6	98	3.08356353823388
6	51	2.8880654031856685
6	17	1.662133460871826
6	90	3.0860979149722905
6	30	1.833991603231342
6	9	2.021208210535196
6	53	4.831371488740929
6	63	2.8231992894810096
6	35	3.0039607466980955
6	43	2.586047138467647
7	18	3.425872566388903
7	94	2.4100866988846628
7	23	1.3260426849841456
7	81	1.5901980584725994
7	25	2.095680872210275
7	7	0.8595627886355217
7	4	0.8229963684978736
7	58	1.248720896146776
7	33	1.1015954931098375
7	64	2.5737109687838995
7	84	4.531167597175693
7	32	2.664135187006971
7	97	3.4745918989075375
7	8	4.662833543529804
7	87	0.6305766118770528
7	47	3.7308981927613614
7	85	2.0320826828700933
7	15	3.2434147667868225
7	89	3.5961720952207337
8	52	1.5810756128166503
8	14	1.0089747412622847
8	6	3.8020003364374135
8	33	1.4900342859687772
8	16	0.9202238602510676
8	89	1.864999177834315
8	3	1.1289477607531455
8	29	4.721044191730538
8	26	1.6308512706412674
8	99	4.236347049813619
8	84	0.6517656502163277
8	19	1.709328843990755
8	76	4.193044437669811
8	38	0.10504578493180372
8	31	0.04388605973964732
8	10	2.691815510505114
8	65	3.1727823387076235
8	37	4.147829157141843
9	97	4.676972448338994
9	76	2.2263701238235227
9	57	1.8170196599971349
9	41	2.1432213960426587
9	53	1.6608626103086626
9	58	3.137339493830364
9	51	1.0240120452810475
9	14	3.6927302669848174
9	4	1.9956305022248304
9	60	1.413827285300493
9	12	4.7727692120875
9	20	0.23496250501558735
9	39	4.883088186575046
9	87	1.1950726733297168
10	66	3.2019037332212053
10	52	0.9032877065565159
10	34	2.712866634829778
10	80	1.9687757078270334
10	41	0.666722336581852
10	51	3.711849685448909
10	43	4.62154783526279
10	74	1.446219514098341
10	0	0.8401002609633929
10	98	0.5911919623607026
10	96	2.9165362409210225
10	45	3.370189337124784
10	55	1.6947238767422435
10	23	2.0966734020964415
11	58	2.05365771745506
11	71	1.282065138494709
11	48	3.458600570673444
11	97	2.5397434595320414
11	39	1.5535766415572372
11	43	2.509727025659209
11	92	2.334390495615522
11	95	2.9103506556211176
11	81	4.321831332279866
11	72	4.694384875711365
12	66	3.485831271451752
12	86	4.3182052620857805
12	48	0.5557543989165592
12	87	2.0858213948785105
12	98	4.3700683565435785
12	58	4.132323047460915
12	53	0.3110254576284549
12	22	4.859226506627423
12	37	2.0084844637988826
12	16	2.3470342099462904
12	83	3.254166107807425
12	47	0.9633819824335016
12	69	2.5659494585491487
13	51	4.866304415152459
13	43	1.1374080184677
13	44	0.37650716799234873
13	33	4.1027232387299355
13	58	4.9406203797731765
13	42	1.6461530767069728
13	74	2.2511814333630866
13	9	3.5483567175226223
13	66	3.528076523921465
13	21	0.4834727989378357
13	87	0.9215069847504953
13	95	0.39606575004185407
13	17	3.8724280155989543
14	61	2.3386030798557544
14	60	4.679130667014114
14	42	0.13553326168116553
14	50	0.05256612270826744
14	81	3.047529455024916
14	65	2.1641996052858614
14	49	4.9334380580851205
14	9	2.5482822540188033
14	62	4.469667553349953
14	64	2.437031515504038
14	89	4.810292494706758
14	97	0.25253696191403274
14	57	4.4522047400054285
14	4	0.7140715223643368
14	19	1.6216443956848332
14	68	1.395041451738983
14	77	2.9381349330755437
14	45	2.8927090910176574
15	39	0.7726041499525949
15	55	0.3716730444303573
15	44	0.4348351012796653
15	87	2.361132128781022
15	90	1.9645466780244663
15	79	1.7359608378110596
15	75	0.030919113204483373
15	68	4.68819889978951
15	6	2.8509081587734695
15	43	4.803731513856777
15	20	3.9410046493335305
15	28	1.2881599938176458
15	70	3.441692057732824
15	19	3.6658018906839978
15	45	4.335886772256761
15	83	2.666617739298025
15	40	0.4848938125804769
15	3	4.887282815919213
16	29	2.491665141471186
16	88	0.29525072229135974
16	68	2.7189353519587343
16	13	1.4771101815688248
16	43	4.951425852924706
16	11	0.6666340817128757
16	32	3.8607601380791907
16	24	1.9225790685313326
16	85	0.1447215837168353
16	8	3.9088991296436317
16	27	1.67921743519658
16	41	2.8824445156993295
16	94	1.6899077523491806
16	22	1.191448352765458
17	0	1.1799830295461877
17	59	0.9270442518702715
17	87	2.227589072465806
17	46	0.39802538496252815
17	95	4.317157888946922
17	39	4.3625997591468115
17	85	4.339898133654515
17	56	4.629136872217587
17	34	1.8602178390610369
17	18	0.6570619142763423
18	8	4.335300911894737
18	72	4.83367113767554
18	35	2.7517563941937553
18	14	1.7402597773866024
18	3	4.187247975417309
18	67	2.2171955141802204
18	81	0.8031680630927535
18	84	3.4388460318286738
18	25	0.5976543477353891
18	42	0.532058814514223
18	88	1.9314385257277262
18	0	3.736487787799284
18	15	4.742601637569575
18	57	0.03398274293055892
18	16	2.5704096038309263
18	77	2.223563884291679
18	22	1.208006382178815
18	74	0.013540749102260441
18	43	0.3204735551808774
18	55	3.697905886108713
19	43	3.435949982343383
19	70	4.21906431829153
19	31	1.0879396996582225
19	88	3.385724833358346
19	52	0.36332793790578355
19	79	2.417749253951845
19	16	3.1011742448056023
19	69	0.6282174620615699
19	95	1.1937588554301204
19	5	3.8016411070206884
19	81	0.03695950722146513