1 Introduction to Mahout Recommender plugin

Then, the selected recommender can be enabled by configuration and used by your application instantly.

You only need to write custom recommender when out-of-the-box recommenders doesn't meet your application-specific requirements.

1.1 Consulting and Community

When you found some issues for the plugin, please write a detail issue report at https://github.com/limcheekin/mahout-recommender/issues.

Lastly, we are welcome your feedback and would like to hear your comments for the plugin or the plugin's documentation. You are invited to join the project's discussion forum at http://groups.google.com/group/grails-mahout-recommender, see you there!

1.2 Change Log

• Remove mahout's jar files and using dependency resolution. Thanks for contribution from Robin Bramley (rbramley).

20-Dec-2011 0.5.1

• Fixed issue #1: The web-based recommenders' evaluator is broken in Grails 2.0.0.
• Fixed issue #2: Improve interactivity of web-based recommenders' evaluator.

18-Dec-2011 0.5

• First release of the plugin.
• Included Apache Mahout 0.5 jar files.
• Introduced command line: average-diff-evaluator, create-table, import-data, install-libimseti-sample-app, irstats-evaluator, load-runner, recommender and uninstall-libimseti-sample-app.
• Introduced recommender controller (enhanced version of Mahout's RecommenderServlet) and web-based recommenders' evaluator.

2 Getting Started

grails install-plugin mahout-recommender

After the plugin installed into your project, the following configurations will be appended to your project's Config.groovy file:

// Added by the Mahout Recommender plugin:
mahout.recommender.mode = 'input'  // 'input', 'config' or 'class'

3 Configuration

For file data model, no additional configuration is required to make use of command line tool of the plugin, but the data file must be located in classpath such as grails-app/conf and data file name must be specified in mahout.recommender.data.file for web-based tools such as recommenders' evaluator and recommender.

For MySQL data model, change mahout.recommender.data.model from 'file' to 'mysql' and configure the DataSource.groovy properly.

3.1 Basic Configuration

• Item 10 to 21 below only applicable when mahout.recommender.data.model = 'mysql'
• MahoutRecommenderConstants = org.grails.mahout.recommender.MahoutRecommenderConstants
• AbstractJDBCDataModel = org.apache.mahout.cf.taste.impl.model.jdbc.AbstractJDBCDataModel
• AbstractJDBCDiffStorage = org.apache.mahout.cf.taste.impl.recommender.slopeone.jdbc.AbstractJDBCDiffStorage

3.2 The MySQL Data Model

Steps to setup Mahout Recommendation Plugin with MySQL database

Create Recommender Database in MySQL

• Login to MySQL using command below:

mysql -u root

• Create recommender database using command below:

create database recommender

Download and Setup MySQL Connector/J (JDBC Driver)

• Download latest MySQL Connector/J at http://www.mysql.com/downloads/connector/j/.
• Extract the downloaded compressed file and copy the mysql-connector-java-5.1.x-bin.jar to lib directory of your grails application.

Update Config.groovy

• Update mahout.recommender.data.model in grails-app/conf/Config.groovy from 'file' to 'mysql', for example:

mahout.recommender.data.model = 'mysql'  // 'file' or 'mysql'

Update Datasource.groovy

• Update database configurations in grails-app/conf/DataSource.groovy from HSQL or H2 to MySQL, for example:

dataSource {
    pooled = true
    driverClassName = "com.mysql.jdbc.Driver"
    username = "root"
    password = ""
}
hibernate {
    cache.use_second_level_cache = true
    cache.use_query_cache = true
    cache.provider_class = 'net.sf.ehcache.hibernate.EhCacheProvider'
}
// environment specific settings
environments {
    development {
        dataSource {
            dbCreate = "create-drop" // one of 'create', 'create-drop','update'
            url = "jdbc:mysql://localhost:3306/recommender"
        }
    }
    test {
        dataSource {
            dbCreate = "create-drop"          
            url = "jdbc:mysql://localhost:3306/recommender"
        }
    }
    production {
        dataSource {
            dbCreate = "update"
            url = "jdbc:mysql://localhost:3306/recommender"
        }
    }
}

To save your typing, you can download the MySQL's DataSource.groovy.

Done! You should able run your mahout recommender application with MySQL data model without any problem.

4 The Command Line

Recommender

• average-diff-evaluator
• irstats-evaluator
• load-runner
• recommender

Database

• create-table
• import-data

Libimseti Sample Application

• install-libimseti-sample-app
• uninstall-libimseti-sample-app

5 The Recommender Controller

5.1 Web-based Recommenders' Evaluator

By access to http://localhost:8080/<yourApplication>/recommender/evaluator in your browser, you will see a screen similar to the following image:

Start running the evaluation process by click on "Run Evaluator" link.

5.2 Web-based Recommender

By access to http://localhost:8080/<yourApplication>/recommender/settings in your browser, you will see a screen similar to the following image:

After fill-in all required fields, click on "Submit" button to see the recommendations.

You can checked the check box of "Enabled debug?" to see the recommendation results with more debugging information.

Recommendations Without Debug-enabled

Recommendations With Debug-enabled

5.2.1 REST Support

XML Recommended Items

http://localhost:8080/<yourApplication>/recommender.xml?userID=1&howMany=20&
r=1&p=true&s=PearsonCorrelation&w=true&n=4

You will see XML message similar to the below display in your browser

<recommendedItems>
  <item>
    <value>5.0</value>
    <id>104</id>
  </item>
  <item>
    <value>4.0</value>
    <id>106</id>
  </item>
</recommendedItems>

If some error occur, you will see XML message similar to the following:

<error>
  <message>Recommender cannot be blank.</message>
</error>

JSON Recommended Items

http://localhost:8080/<yourApplication>/recommender.json?userID=1&howMany=20&
r=1&p=true&s=PearsonCorrelation&w=true&n=4

The URL above is identical to the XML request, except it invoke to recommender.json instead of recommender.xml.

You will see JSON message similar to the below display in your browser

{"recommendedItems":[{"value":5,"id":104},{"value":4,"id":106}]}

If some error occur, you will see JSON message similar to the following:

{"error":{"message":"Recommender cannot be blank."}}

Usage

http://localhost:8080/<yourApplication>/recommender.[json|xml]?
userID=[Long]&howMany=[Integer]&r=[1|2|3]&p=[true|false]&
s=[PearsonCorrelation|EuclideanDistance|LogLikelihood|TanimotoCoefficient]&
w=[true|false]&n=[Integer|Double]

1. File extension: recommender.xml for XML request, recommender.json for JSON request.
2. userID: Specify user ID. in numeric value as java.lang.Long type.
3. howMany: Specify expected number of recommendations return in numeric value as java.lang.Integer type.
4. r: Specify recommender. Valid values: 1, 2 or 3 (1. user-based, 2. item-based or 3. slope-one).
5. p: Specify "has preference value". Valid values: true or false.
6. s: Specify similarity metric. Valid values: PearsonCorrelation, EuclideanDistance, LogLikelihood or TanimotoCoefficient.
7. w: Specify whether weighting is enabled. Valid values: true or false. Applicable to 'PearsonCorrelation' or 'EuclideanDistance' similarity metric or Slope-one recommender only.
8. n: Specify whether fix-size neighborhood or threshold-based neighborhood when user-based recommender is selected in r above. Integer value for fix-size neighborhood such as 4 and Double value (< 1.0) for threshold-based neighborhood such as 0.5.

Item 4 to 8 above need to be specified only when mahout.recommender.mode = 'input' in Config.groovy file.

6 The Libimseti Sample Application

Thanks to Sean Owen, one of the book authors of Mahout In Action granted the right in this message to use the source code in the plugin as sample application.

The sample application's data set derived from the Czech dating site Líbímseti (http://libimseti.cz/). Users of this site are able to rate other users’ profiles on a scale of 1 to 10. A 1 means NELÍBÍ, or dislike, and a 10 means LÍBÍ, or like. The presentation of profiles on the site suggests that users of such a site are expressing some assessment of the profiled user’s appeal, attractiveness, and dateability.

You’ll need to download a copy of the complete data from this site, at http://www.occamslab.com/petricek/data/libimseticomplete.zip, then extract the gender.dat and ratings.dat file to grails-app/conf directory.

There is 17,359,346 ratings in ratings.dat file. It contains users’ explicit ratings for items, where items are other people’s user profiles. That means a recommender system built on this data will be recommending people to people.

Please see Recommender System for Online Dating Service by Lukas Brozovsky and Vaclav Petricek for more information.

You may run the sample application using file data model or MySQL data model. Please see the following commands to install and unstall the sample application:

• install-libimseti-sample-app
• uninstall-libimseti-sample-app