(Quick Reference)

5 The Recommender Controller - Reference Documentation

Authors: Lim Chee Kin

Version: 0.5.2

5 The Recommender Controller

The recommender controller is enhanced version of mahout's RecommenderServlet implementation. It included a web-based recommenders' evaluator to enabled user to find an effective recommender.

5.1 Web-based Recommenders' Evaluator

The web-based recommenders' evaluator supports user to evaluate recommenders' effectiveness by average difference. Recommenders under evaluation including user-based recommender, item-based recommender and slope-one recommender with different type of similarity metrics such as pearson correlation, euclidean distance, Log-likelihood and tanimoto coefficient.

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

The web-based recommender supports user to test recommender using web user interface with or without debug-enabled.

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

Besides display the recommendation results in HTML format, the web-based recommender support return the results in XML and JSON format too.

XML Recommended Items

By access to the following URL in your browser:
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

By access to the following URL in your browser:
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.