Online Challenge

Introduction

For the online challenge, we add the feature of name recommendations to Nameling. The user will see a personalized list of “recommended names” on every page within the system. This list will automatically adapt to the user’s activities (e.g., the user’s click, entering of favorite actions). The user may use this list to further search for names by clicking on one, add a name to his favorite names, or ban a name which the user doesn’t want to be recommended again.

This task’s target is to recommend a personalized list of names, suitable to the user. The evaluation will be based on the names a user clicked on, requested details for, or added as favorite. We will provide a framework for the easy integration of your recommender system into the live system based on lightweight REST (HTTP + XML / JSON) interaction. Participants can implement a simple Java interface to produce their recommendations, or implement the REST interaction on their own. All data serialization / deserialization will be handled by our framework. Participants may choose to run their recommender in a web service on their own or to provide a JAR file to be deployed by us.

New: We also provide a lightweight Python binding so that participants may easily integrate a Python based recommender.

There are two use cases for name recommendations implemented in Nameling during the challenge:

Sidebar recommendations:
On most pages within Nameling, a short list of recommended names is displayed on the right sidebar, beneath the list of favourite names. A user might click on a name for further inspection, add a name to the list of favourite names, or permanently hide a name by disliking it.
Recommendation form:
There will be a new main menu entry, where a user might explicitly query for suitable names, given a (possibly empty) list of query names (image, e.g. the parents’ names).

All recommendation requests are passed out to all registered recommendation systems. But only one (randomly) selected recommender’s result will be presented to the user. The selection of a recommender for a given user is fix for a session (i.e. a time frame where the user interacts with Nameling), until the user requests new recommendations, which will select another recommender for the user. Whenever a user interacts with a recommended name (e.g. by clicking on it), the respective recommender system gets an according feedback (i.e. which user clicked on which name, based on which recommendation). For this, all recommendation processes are uniquely identified. For evaluation, we log all activities and interactions.

For all participants of the challenge, we will publish an anonymized nightly snapshot of the usage data in order to regularly update the recommender models. Additionally, the actual user object which is passed the recommender, contains the user’s complete interaction history. All registered participants of the offline challenge are cleared for taking part in the online challenge. It is not mandatory to participate in the offline challenge, nevertheless, we kindly ask you to follow the same registration procedure as we requested for the offline challenge, if you just want to take part in the online challenge.

Also have a look at download page for a summary of all available data sets and program files concerning the online challenge.

For now, you can visit beta.nameling.net for getting a preview of the new recommendation feature. Please note that we are currently polishing the user interface integration of name recommendations. You can help us by sending us feedback.

Nameling’s Java based recommender interface

Getting Started

This section explains how to set up a simple basic remote installation of your name recommender for integration into Nameling. After successfully following the subsequently listed steps, you will have a running recommender on your site which (technically) could already be integrated into Nameling.

Please note: This is a preliminary description of the online challenge, intended for publishing technical details of the challenge as soon as possible. The described technical details (e.g. the Java interfaces as well as installation steps) are unlikely to change, but in case of bugs, we may have to publish an update. Please give us feedback, by asking questions or hinting at errors, so that we can quickly update this description.

If you consider participating in this online challenge, or if you have any questions, please don’t hesitate to contact us. We will happily assist you in adopting your recommender system to Nameling’s recommendation interface.

  1. Download Apache Tomcat and store it on your installation base path
  2. Unpack the downloaded file within your installation base path (in a Unix-like operating system: $ unzip apache-tomcat-6.0.37.zip)
  3. Download the Nameling recommender servlet and store it in Tomcat’s web application folder
  4. Download Nameling’s model classes and Nameling’s recommender classes and store it in your Tomcat installation’s shared library folder
  5. Start up your Tomcat
  6. Navigate with your browser to your recommender’s base URL (e.g., http://localhost:8080/nameling-recommender-servlet/)

You can now already get some recommendations! Next, we will explain, how you can implement and deploy your own recommender system into Nameling.

 

Implement Your Own Recommender

Now we will look at the implementation aspects of a custom recommender in Java using Nameling’s model classes and the provided recommender servlet.

Firstly, you will need the following JAR files, which provide the necessary base classes:

Basically, you only have to implement the INamelingRecommender interface:

package net.nameling.recommender;
...
/**
 * Interface for Nameling's name recommendation framework
 */
public interface INamelingRecommender {

	/**
	 * get list of recommended names
	 *
	 * @param user Nameling user for whom recommendations are requested
	 * @param names current query names of the Nameling user
	 * @param offset pagination start position
	 * @param limit number of names to recommend
	 * @param traceId id which identifies subsequent user interactions
         * @param activityType type of the user interaction which  triggered this recommendation process
         * @param activityId id of this recommendation process
         * @param refActivity id of the activity which triggered this recommendation
	 * @return
	 */
	public List<RecommendedName> recommend(User user, List<Name> names, Integer offset, Integer limit, String traceId, Activity activityType, int activityId, Integer refActivity);

	/**
	 * notify recommender about user interaction
	 *
	 * @param user Nameling user for whom recommendation was requested
	 * @param activity describes the user's interaction with the previously recommended name (including the activityId of the recommendation process)
	 */
	public void setFeedback(User user, String traceId, Activity activityType, String value, int activityId, Integer refActivity);

}

That is, you only have to implement the following two methods:

recommend(...)
Given a user (identified via user.getName()) and a set of query names, you return an ordered list of recommended names, where an instance of RecommendedName must at least contain a known name’s UTF-8 string representation (set via recommendedName.setValue(<name>)) and possibly a ranking score (recommendedName.setScore(<score>) with score∈[-1,1]). The score value may be used for visualizing the quality of recommendations in Nameling’s user interface.Beside the query names, the user object contains the user’s complete activity history (user.getHistory()) as well as the list of favorite names. Additionally, we will publish nightly dump of usage data on the download page.

The offset and limit parameters are used for allowing users to request more recommended names.

setFeedback(...)
This method is called, whenever a user interacts with a recommendation, e.g., when the user adds a recommended name to the list of favorites. The user is identified via the user name (user.getName()) while the recommendation process is identified by the activityId (activity.getId()) and the traceId(activity.getTraceId()).

For deploying your recommender, you only have to follow the subsequent steps:

  1. Compile a JAR file which contains all referenced Java libraries (you do not need to provide the nameling-* modules).
  2. Set up your Tomcat servlet container according to the Getting Started section.
  3. Copy your JAR file to your Tomcat installation’s shared library folder
  4. Add the following line to your Tomcat’s context configuration file, assuming that you called your recommender class MyNameRecommender in the Java package my.package: 
    <Parameter name="NameRecommender" value="my.package.MyNameRecommender" override="false"/>
  5. Start up your Tomcat!
  6. Navigate with your browser to your recommender’s base URL (e.g., http://localhost:8080/nameling-recommender-servlet/) and get some recommendations!

For your convenience, you we have compiled a small Maven project which exemplifies the implementation by statically recommending the given names of all main characters of The Big Bang Theory. You can download the project for reference.

The integration of remotely installed recommender systems in Nameling is implemented via REST-like communication and JSON object serialization. If you want to use another programming language or servlet, please contact us.

Nameling’s Python based recommender interface

Based on web.py, we also provide a lightweight Python binding to Nameling’s recommender interface (nameling-python-servlet.zip). Firstly, you will need (assuming that Python is readily installed) the web.py module: 

sudo easy_install web.py

We included a small example, on how the recommender interface works (myRecommender.py): 

class MyRecommender(Recommender):
    def recommend(self, user, inputNames, offset, limit, traceId, activityType, activityId, refActivity):
        recommendation = [
            {'value': 'Leonard', 'score': 0.9},
            {'value': 'Sheldon', 'score': 0.8},
            {'value': 'Penny', 'score': 0.7},
            {'value': 'Howard', 'score': 0.6},
            {'value': 'Rajesh', 'score': 0.5},
            ]
        return recommendation

    def setFeedback(self, user, traceId, activityType, value, activityId, refActivity):
        print "SETTING FEEDBACK for user "+user['name']+" via "+activityType+" ("+str(activityId)+") with value '"+value+"' referring to "+str(refActivity);

You can start this recommender with python pythlet.py 9988 which will start the server, listening on port 9988. If you want to implement your own recommender, simply overwrite the myRecommener.py file accordingly! For testing your recommender, we compiled a small Java based test client, which uses the same code for querying and parsing a recommender as Nameling. Just download nameling-test-client.jar and query you recommender via 

java -jar nameling-test-client.jar http://localhost:9988 testuser

where ‘testuser’ is just an arbitrary string for testing purposes. You will get the following result (according to the MyRecommender class above): 

URL: http://localhost:9988       User Name: testuser
Querying recommender
Got name: Leonard
Got name: Sheldon
Got name: Penny
Got name: Howard
Got name: Rajesh

 

Final Testing

We now show you, how to test the connection from our server’s to your recommender system. For this, navigate to test.nameling.net and enter your recommender’s base URL to the corresponding input field. After hitting the “Query Recommender” button, our server will query your recommender system via the provided base URL and display the received recommendation together with the total processing time. Any processing time below 500 ms is fine. If your recommender system constantly lies above 500 ms, please contact us for discussing the possibility of hosting your recommender on our site.

 

Additional Examples

Within this section, we present some simple recommender implementations which may help you
to develop and deploy your own system.

 

File-based Recommendations

In this section we describe, how to deploy the item-based NameRank recommender, which is described in our name recommendation paper. We pre-calculated for each name the top 100 recommended names, together with the corresponding pair-wise NameRank scores and stored the result as a list of triples (<query name>, <recommended name>, <score>) in a tab-separated text file:

Folke   Emma    0.00212623378963727
Folke   Tumai   0.00147136818626244
Folke   Kevin   0.00130191069681237
Folke   Tim     0.0010356402037229
Folke   Amelie  0.00102964668938194
⋮

Download

For a given set of query names, the final recommendation is obtained by averaging the scores for all other names element-wise (actually, only the scores are summed up, as the division by the number of query names does not affect the ordering).

For deploying this recommender on your server, you simply have to do the following steps:

  1. Set up your Tomcat servlet container according to the Getting Started section.
  2. Download Nameling’s recommender classes and store it in your Tomcat installation’s shared library folder
  3. Download the pre-calculated NameRank result file and extract it in your Tomcat installation’s shared library folder
  4. Add the following line to your Tomcat’s context configuration file: 
    <Parameter name="NameRecommender" value="net.nameling.recommender.base.NameRankRecommender" override="false"/>
  5. Start up your Tomcat!
  6. Navigate with your browser to your recommender’s base URL (e.g., http://localhost:8080/nameling-recommender-servlet/) and get some recommendations!

If your recommender also works with pre-calculated scores, you might already use this implementation and only provide a custom “nameling-recommendation.tsv” file.
In the next section, we will describe the implementation and deployment of a custom name recommender for Nameling.

 

Further Explanation

Installation base path
This is the directory on your server, where your recommender system will be installed. On a Unix-like operating system, this might look like /home/<your user id>/20DC13/.
Tomcat’s web application folder
This folder contains all web applications which are deployed by your Tomcat servlet container. Following our installation instructions, your web application folder is located at <installation base path>/apache-tomcat-6.0.37/webapps/.
Tomcat’s shared library folder
This folder contains files which are available to all applications in your Tomcat servlet container. Following our installation instructions, your shared library folder is located at <installation base path>/apache-tomcat-6.0.37/lib/. More information about Tomcat’s shared library folder is available in the Tomcat online reference.
Context configuration file
This file can be used to configure site specific parameters of your web application, located at <installation base path>/apache-tomcat-6.0.37/conf/context.xml. For Nameling recommender servlet, you can provide the canonical Java class name of your recommender. A minimal example which configures the NameRank recommender looks as follows:

<?xml version='1.0' encoding='utf-8'?>
<Context>
    <WatchedResource>WEB-INF/web.xml</WatchedResource>
    <Parameter name="NameRecommender" value="net.nameling.recommender.base.NameRankRecommender" override="false"/>
</Context>
Start and configuration of Tomcat
Tomcat is invoked via <installation base path>/apache-tomcat-6.0.37/bin/startup.sh and listens on port 8080 per default.
Recommender base URL
Your recommender system’s base URL is determined by your server’s host name (or IP address), your Tomcat installation’s HTTP connector port (which is by default set to 8080), as well as the context path of Nameling’s recommender servlet (which is ‘/nameling-recommender-servlet/’ by default). That is, you can access your installation with your browser via http://localhost:8080/nameling-recommender-servlet/