Hi-Rec by fmoghaddam

Hi-Rec (A Java Framework for Recommender Systems)

Hi-Rec is a Java framework for recommender systems (Java version 1.8 or higher required). This framework is Cross-Platform, Open Source , Scalable, Extensible and Easy to Use. It not only implements state-of-art algorithms but only makes it possible for others to extend it and implement more user-specific algorithms. This framework developed to be used across with Mise-en-scène Project. You won't need to install any extrenal framework, library or tool.

Implemented Algorithms:

ItemBased KNN
Average Popularity
Factorization Machine
FunkSVD

Implemented Metrics:

MAE
RMSE
Coverage
Precision
Recall

MAP
Diversity
Noverlty
Populairty
NDCG

Implemeted Features:

Visual Features (Related to Mise-en-scène Project)
Genre
Tag
Rating (Collaborative Filtering)

Running

Based on your platform (PC or Linux) download the compresed related version from Releases. After extracting the zip file, you can run either HiRec.sh or HiRec.bat

Running inside Eclipse

This project is based on Gradle. So it could be easily imported to Eclipse. For importing it, the Eclipse should contain Buildship Plugin. After installing Buildship Plugin, you can donwload the sourse code from here and easily import the project into the Eclipse as a Gradle project.

Code structure

Public interfaces:

Recommender.java : All the algorithms can implement this interface
AbstractRecommender.java : All the algorithms should implement this abstract class
AccuracyEvaluation.java : All the rating prediction metrics (RMSE, MAE, ...) should implement this interface
ListEvaluation.java : All the list generators metrics (Precision, Recall, ...) should implement this interface

Sample result:

All the experiments have been done over data in data folder.

Rating:

Algorithm	RMSE	MAE	Coverage	Precision	Recall	NDCG
ItemBasedKNN	0.75198567	0.5812379	0.9809702	0.88165295	0.46150175	0.85933286
Average Popularity	0.87274086	0.7008808	0.9817214	0.9297659	0.16849223	0.8572529
Factorization Machine	1.0924361	0.847448	0.9811511	0.7052688	0.40766105	0.7255255

Visual features:

Algorithm	RMSE	MAE	Coverage	Precision	Recall	NDCG
ItemBasedKNN	0.75276524	0.5802754	0.98175746	0.90045756	0.50048786	0.861112
Factorization Machine	1.2744157	1.0030644	0.98076487	0.71231234	0.48030663	0.7239859

Genre:

Algorithm	RMSE	MAE	Coverage	Precision	Recall	NDCG
ItemBasedKNN	0.7796999	0.6023326	0.8747948	0.9150926	0.46745244	0.845462
Factorization Machine	1.1264656	0.8723874	0.98105305	0.7536468	0.5395745	0.75031984

Visual Features + Genre:

Algorithm	RMSE	MAE	Coverage	Precision	Recall	NDCG
ItemBasedKNN	0.7572874	0.5857588	0.982289	0.89470136	0.47212344	0.85523474
Factorization Machine	1.2027843	0.9487314	0.9805652	0.74588954	0.4479124	0.7380162

FAQ

1. I want to change the java code and run the project without importing it into Eclipse, How can I do that?

You can open any of the java classes in your favorite editor such as notepad and change the code. Then you can build and run the code with the following steps:

In cmd or terminal go to the root folder of the project
Run gradlew.bat build or gradlew.sh build

In case of any compilation error, you will see the proper error message. If you see BUILD SUCCESSFUL you can continue.

Run gradlew.bat installDist or gradlew.sh installDist

If you see BUILD SUCCESSFUL then you can follow the steps which have been explained in Question 1.

2. How to import project into Eclipse?

For importing project into Eclipse, you can use Buildship Plugin. For installing this plugin do the following steps:

Open the Eclipse
From Help menu select Eclipse MarketPlace
Insert buildship into search bar and install Buildship Gradle Integration

After installing and restarting the Eclipse, you should be able to import the project as a Gradle project.

3. How to run the project inside the Eclipse?

For running the project inside the Eclipse you should import it first (Question 3). After importing, from Gradle Tasks tab you will be able to select different Gradle tasks. In the simplest scenario, just build and run task is needed.

4. How to implement my own algorithm?

If you need to implement your specific algorithm you only need to create a class in algorithms package and extend AbstractRecommender class. By doing this, your algorithm will be accessible from config.properties file.

5. How to implement my own metric?

If you need to implement another metric, you only need to create a class in metrics package and extend one of the AccuracyEvaluation or ListEvaluation interfaces. By doing this, your metric will be accessible from config.properties file. Keep in mind that all the metrics should have hashCode() function and this function should return a static fixed number. Currently numbers in [1,6] range occupied. So you can use 7,8,.... You can have a look at the hashCode() function in MAE.

6. I use this code for my research. Do I have to cite it?

To acknowledge the use of this recommendation engine in your work, please cite the following paper:


Mohammad Hossein Rimaz, Mehdi  Elahi, Farshad Bakhshandegan Moghaddam, Reza Hosseini. 
“Exploring the Power of Visual Features for the Recommendation of Movies”,
Proceedings of the 27th ACM Conference on User Modeling, Adaptation and Personalization
Pages 303-308, Larnaca, Cyprus
https://dl.acm.org/citation.cfm?id=3320470

7. How can I obtain your dataset?

Low level features which have been collected in Mise-en-scène Project can be downloaded from this link. If you need to have Tags, Genre and Ratings, you can use MovieLens latest dataset. For simplicity we have preproccesed corresponding Tags, Genre and Ratings data and put them in data folder.

8. How can I give my feedback about the project?

In case of any question or feedback about the project you can use pull requests or you can contact us directly by this email:f.bakhshandegan@gmail.com

Hi-Rec

Version 3.0.1