Merge pull request #18 from AKSW/entity2rec

Entity2rec

Author: paulorvdc

config_files/test_entity2rec.yml

@@ -0,0 +1,91 @@
+experiment:
+  dataset:
+    name: ml-100k
+    item: # infos related to item dataset (mandatory, at least item_id)
+      path: datasets/ml-100k/processed/item.csv
+      extra_features: [movie_year, movie_title] # features(columns) beside item_id to be used
+    user: # mandatory (at least user_id)
+      path: datasets/ml-100k/processed/user.csv
+      extra_features: [gender, occupation] # features beside user_id
+    ratings: # mandatory (at least [user_id, item_id, rating])
+      path: datasets/ml-100k/processed/rating.csv
+      timestamp: True
+    enrich:
+      map_path: datasets/ml-100k/processed/map.csv
+      enrich_path: datasets/ml-100k/processed/enriched.csv
+      remove_unmatched: False
+      properties: [subject, director]
+
+  preprocess:
+    # - method: filter_by_rating
+    #   parameters:
+    #     threshold: 20
+    # - method: binarize
+    #   parameters:
+    #     threshold: 4
+    - method: filter_kcore
+      parameters:
+        k: 20
+        iterations: 1
+        target: user # user or rating
+
+  split:
+    seed: 42
+    # test:
+    #   method: random_by_ratio
+    #   level: global
+    #   p: 0.2
+    # validation:
+    #   method: random_by_ratio
+    #   level: global
+    #   p: 0.2
+
+    # test:
+    #   method: timestamp_by_ratio
+    #   level: user
+    #   p: 0.1
+    # validation:
+    #   level: user
+    #   method: timestamp_by_ratio
+    #   p: 0.2
+
+    # test:
+    #   method: fixed_timestamp
+    #   # type: global_level
+    #   timestamp: 890000000
+    # validation:
+    #   method: fixed_timestamp
+    #   timestamp: 880000000
+
+    test:
+      method: k_fold
+      k: 5
+      level: "user"
+
+  models:
+    - name: entity2rec
+      config:
+        save_weights: True
+      parameters:
+        embedding_model: deepwalk_based
+        embedding_model_kwargs:
+          config:
+            save_weights: True
+          parameters:
+            walk_len: 10
+            p: 1.0
+            q: 1.0
+            n_walks: 50
+            embedding_size: 64
+            epochs: 1
+        workers: 32
+        frac_negative_candidates: 0.1
+        seed: 42
+
+  evaluation:
+    k: 5
+    relevance_threshold: 0
+    metrics: [MAP, nDCG]
+
+  report:
+    file: "experiment_results/ml100k_enriched/e2rec_ratings_negative0.1.csv"

docs/source/getting_started/support.md

@@ -109,6 +109,20 @@ Currently the supported Recommender System models are:
     - `iterations`: the number of iterations for the regularization propagation.
     - `mi`: the mi factor number that dictates how much of the start embedding will affect the final embedding, values fluctuate between `0` and `1`.
 
+### entity2rec
+- Entity2Rec recommendation model based on Node2Vec.
+  - Reference: Palumbo, Enrico, Giuseppe Rizzo, and Raphaël Troncy. 2017. Entity2rec: Learning user-item relatedness from knowledge graphs for top-n item recommendation. Proceedings of the eleventh ACM conference on recommender systems. 32-36.
+  - Main parameters
+    - `embedding_model`: the embedding model name of a previously implemented graph embedding model.
+    - `embedding_model_kwargs`: arguments for the embedding model.
+    - `collab_only`: using only collaboration filtering properties' embeddings for the recommendations.
+    - `content_only`: using only item content properties' embeddings for the recommendations.
+    - `social_only`: using only user social interaction properties' embeddings for the recommendations.
+    - `workers`: the number of threads to be used in creating candidates for recommendations. `-1` automatically inputs the number of cores as the amount of workers. number of physical cores is recommended in case the computer needs to be usable for other tasks.
+    - `frac_negative_candidates`: calculates a fraction from the amount of unrated items for a user to be used in the train data. Values between `0` and `1` with `0.1` recommended.
+    - `seed`: seed for fixing the sampling of negative and positive examples for training.
+    - `relevance`: the necessary relevance of an evaluation from a user to be counted as a recommendation.
+
 
 ## Pre-processing Methods
 

docs/source/imgs/framework.svg

@@ -19,4 +19,6 @@ py-cpuinfo
 gputil
 psutil
 sentence-transformers
-graph-walker @ git+https://github.com/AlvaroJoseLopes/graph-walker
+graph-walker @ git+https://github.com/AlvaroJoseLopes/graph-walker
+SPARQLWrapper
+multiprocess

requirements_framework.txt

@@ -76,7 +76,7 @@ def get_ratings_with_labels(self):
 
         return ratings
 
-    def get_all_triples(self):
+    def get_all_triples(self, return_type='str'):
         triples_return = {"head": [], "relation": [], "tail": []}
 
         # ratings triples
@@ -86,25 +86,31 @@ def get_all_triples(self):
         for user, ratings in tqdm(ratings.items(), total=n_total, desc=desc):
             ratings.sort(key=lambda x: x[1], reverse=True)
             for rating in ratings:
-                triples_return["head"].append(user.__str__())
+                if return_type == "str": triples_return["head"].append(user.__str__()) 
+                else: triples_return["head"].append(user)
                 triples_return["relation"].append(f"rating{rating[1]}")
-                triples_return["tail"].append(rating[0].__str__())
+                if return_type == "str": triples_return["tail"].append(rating[0].__str__())
+                else: triples_return["tail"].append(rating[0])
 
         # user property triples
         user_properties = self.get_user_property_edges()
         desc = f"Generating user properties triples"
         for user, user_property in tqdm(user_properties, desc=desc):
-            triples_return["head"].append(user.__str__())
+            if return_type == "str": triples_return["head"].append(user.__str__())
+            else: triples_return["head"].append(user)
             triples_return["relation"].append("is")
-            triples_return["tail"].append(user_property.__str__())
+            if return_type == "str": triples_return["tail"].append(user_property.__str__())
+            else: triples_return["tail"].append(user_property)
 
         # item property triples
         item_properties = self.get_item_property_edges()
         desc = f"Generating item properties triples"
         for item, item_property in tqdm(item_properties, desc=desc):
-            triples_return["head"].append(item.__str__())
+            if return_type == "str": triples_return["head"].append(item.__str__())
+            else: triples_return["head"].append(item)
             triples_return["relation"].append("has")
-            triples_return["tail"].append(item_property.__str__())
+            if return_type == "str": triples_return["tail"].append(item_property.__str__())
+            else: triples_return["tail"].append(item_property)
 
         return pd.DataFrame(triples_return)
 

src/framework/dataloader/graph/graph.py

@@ -42,5 +42,9 @@
     'ePHEN': {
         'submodule': 'ePHEN.model',
         'class': 'EPHEN'
+    },
+    'entity2rec': {
+        'submodule': 'entity2rec.model',
+        'class': 'Entity2Rec'
     }
 }

src/framework/recommender/model2class.py

@@ -0,0 +1 @@
+# based on: https://github.com/D2KLab/entity2rec