FranKGraphBench 0.0.1a0__py2.py3-none-any.whl

framework/dataloader/graph/graph.py

@@ -0,0 +1,314 @@
+from collections import defaultdict
+
+from .node import *
+from ...utils import get_optional_argument
+
+import networkx as nx
+import pandas as pd
+from tqdm import tqdm
+import numpy as np
+
+from typing import Set, Tuple, Dict
+
+"""
+    Class wrapper on the top of a nx.Graph
+"""
+
+
+class Graph(nx.Graph):
+
+    def __init__(self):
+        super().__init__()
+        self.datatype_separator = "::"
+        self.item_nodes = set()
+        self.user_nodes = set()
+        self.rating_edges = defaultdict(set)  # { user: Set([items]) }
+        self.rating_item2users = defaultdict(set)  # { item: Set([users]) }
+
+    def build(self, name, item, user, ratings, enrich=None, social=None):
+        # Adding item, user and properties nodes
+        self.name = name
+        self._add_item_info(item, enrich)
+        self._add_user_info(user)
+        self._add_ratings(ratings)
+        if social is not None:
+            self._add_social_links(social)
+
+    def info(self):
+        n_nodes = self.number_of_nodes()
+        n_edges = self.number_of_edges()
+        message = (
+            f"{self.name} graph with a total of {n_nodes} nodes and {n_edges} edges"
+        )
+        message += f" ({len(self.user_nodes)} users, {len(self.item_nodes)} items and {len(list(self.get_rating_edges()))} ratings)"
+        return message
+
+    def get_item_nodes(self) -> Set[ItemNode]:
+        return self.item_nodes
+
+    def get_user_nodes(self) -> Set[UserNode]:
+        return self.user_nodes
+
+    def get_rating_edges(self) -> Tuple[UserNode, ItemNode]:
+        for user, items in self.rating_edges.items():
+            for item in items:
+                yield (user, item)
+
+    def get_user_property_edges(self) -> Tuple[UserNode, PropertyNode]:
+        for node, edge in self.edges():
+            if isinstance(node, UserNode) and isinstance(edge, PropertyNode):
+                yield (node, edge)
+            elif isinstance(node, PropertyNode) and isinstance(edge, UserNode):
+                yield (edge, node)
+
+    def get_item_property_edges(self) -> Tuple[ItemNode, PropertyNode]:
+        for node, edge in self.edges():
+            if isinstance(node, ItemNode) and isinstance(edge, PropertyNode):
+                yield (node, edge)
+            elif isinstance(node, PropertyNode) and isinstance(edge, ItemNode):
+                yield (edge, node)
+
+    def get_ratings_with_labels(self):
+        ratings = defaultdict(list)
+        for u, v in list(self.get_rating_edges()):
+            data = self.get_edge_data(u, v)
+            ratings[u].append((v, data["rating"]))
+
+        return ratings
+
+    def get_all_triples(self):
+        triples_return = {"head": [], "relation": [], "tail": []}
+
+        # ratings triples
+        ratings = self.get_ratings_with_labels()
+        desc = f"Generating ratings triples"
+        n_total = len(ratings.keys())
+        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__())
+                triples_return["relation"].append(f"rating{rating[1]}")
+                triples_return["tail"].append(rating[0].__str__())
+
+        # 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__())
+            triples_return["relation"].append("is")
+            triples_return["tail"].append(user_property.__str__())
+
+        # 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__())
+            triples_return["relation"].append("has")
+            triples_return["tail"].append(item_property.__str__())
+
+        return pd.DataFrame(triples_return)
+
+    def get_ratings_triples(self):
+        triples_return = {"head": [], "relation": [], "tail": []}
+
+        # ratings triples
+        ratings = self.get_ratings_with_labels()
+        desc = f"Generating ratings triples"
+        n_total = len(ratings.keys())
+        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__())
+                triples_return["relation"].append(f"rating{rating[1]}")
+                triples_return["tail"].append(rating[0].__str__())
+
+        return pd.DataFrame(triples_return)
+
+    def get_user_rated_items(self, user: UserNode) -> Set[ItemNode]:
+        return self.rating_edges[user]
+
+    def add_node(self, node_for_adding: Node, **attr):
+        super().add_node(node_for_adding, **attr)
+        if isinstance(node_for_adding, ItemNode):
+            self.item_nodes.add(node_for_adding)
+        elif isinstance(node_for_adding, UserNode):
+            self.user_nodes.add(node_for_adding)
+
+    def add_edge(self, u_of_edge, v_of_edge, **attr):
+        super().add_edge(u_of_edge, v_of_edge, **attr)
+        data = self.get_edge_data(u_of_edge, v_of_edge, default={})
+        edge_type = data.get("type")
+
+        if edge_type == "rated":
+            self.rating_edges[u_of_edge].add(v_of_edge)
+            self.rating_item2users[v_of_edge].add(u_of_edge)
+
+    def remove_edge(self, u, v):
+        if isinstance(u, UserNode) and isinstance(v, ItemNode):
+            self.rating_edges[u].remove(v)
+            self.rating_item2users[v].remove(u)
+
+        super().remove_edge(u, v)
+
+    def remove_node(self, n):
+        super().remove_node(n)
+        if isinstance(n, ItemNode):
+            self.item_nodes.remove(n)
+            del self.rating_item2users[n]
+            for user, items in self.rating_edges.items():
+                if n in items:
+                    self.rating_edges[user].remove(n)
+        elif isinstance(n, UserNode):
+            self.user_nodes.remove(n)
+            del self.rating_edges[n]
+            for item, users in self.rating_item2users.items():
+                if n in users:
+                    self.rating_item2users[item].remove(n)
+
+    def convert_node_labels_to_integer(self):
+        N = self.number_of_nodes()
+        mapping = dict(zip(self.nodes(), range(0, N)))
+        G = nx.relabel_nodes(self, mapping, copy=True)
+        nx.set_node_attributes(G, {v: k for k, v in mapping.items()}, "old_label")
+
+        G.item_nodes = self.item_nodes.copy()
+        G.user_nodes = self.user_nodes.copy()
+        G.rating_edges = self.rating_edges.copy()
+        G.rating_item2users = self.rating_item2users.copy()
+
+        return G
+
+    def convert_back(self):
+        mapping = {node: self.nodes[node]["old_label"] for node in self.nodes()}
+        G = nx.relabel_nodes(self, mapping, copy=True)
+        nx.set_node_attributes(G, {v: k for k, v in mapping.items()}, "old_label")
+
+        G.item_nodes = self.item_nodes.copy()
+        G.user_nodes = self.user_nodes.copy()
+        G.rating_edges = self.rating_edges.copy()
+        G.rating_item2users = self.rating_item2users.copy()
+
+        return G
+
+    def __read_csv(self, path: str) -> pd.DataFrame:
+        df = pd.read_csv(path)
+        col_names = []
+        for col in df.columns:
+            try:
+                col_name, data_type = col.split("::")
+                col_names.append(col_name)
+
+                if data_type == "string":
+                    df[col] = df[col].astype(str)
+                elif data_type == "string_list":
+                    df[col] = df[col].apply(lambda x: str(x).split("::"))
+                elif data_type == "number":
+                    df[col] = pd.to_numeric(df[col])
+            except Exception as e:
+                print(
+                    f"Couldn't parse data type of column named {col}. Should be col_name::data_type"
+                )
+                print(f"Supported types are: string, string_list, number")
+                exit()
+        df.columns = col_names
+
+        return df
+
+    def _add_item_info(self, item, enrich):
+        # Extracting info from .csv
+        df_item = self.__read_csv(item["path"])
+        extra_features = get_optional_argument(item, "extra_features", [])
+        df_item = df_item[["item_id"] + extra_features]
+        if enrich is not None:
+            # Merging info from original dataset and enriched
+            df_map = self.__read_csv(enrich["map_path"])
+            df_item = pd.merge(df_item, df_map, on="item_id", how="left")
+            if enrich["remove_unmatched"]:
+                df_item = df_item[df_item["URI"].notna()]
+
+            df_enriched = self._get_enrich_dataframe(**enrich)
+            df_item = pd.merge(df_item, df_enriched, on="item_id", how="left")
+
+        # Creating graph from dataframe
+        desc = "Adding item info into network"
+        n_items = df_item.shape[0]
+        properties = list(df_item.columns)
+        properties.remove("item_id")
+
+        # Adding item nodes and properties nodes
+        for _, row in tqdm(df_item.iterrows(), total=n_items, desc=desc):
+            item_node = ItemNode(row["item_id"])
+            self.add_node(item_node)
+
+            for property_ in properties:
+                self._add_node_property(item_node, row, property_)
+
+    def _add_node_property(self, source: Node, row: pd.Series, property_: str):
+        prop_value = row[property_]
+        if not isinstance(prop_value, list) and pd.notna(prop_value):
+            # Single property_
+            property_node = PropertyNode(row[property_], property_)
+            self.add_edge(source, property_node, type="has_property")
+        elif isinstance(prop_value, list):
+            # Multiples properties
+            for value in row[property_]:
+                property_node = PropertyNode(value, property_)
+                self.add_edge(source, property_node, type="has_property")
+
+    def _get_optional_argument(self, config, key, default):
+        try:
+            return config[key]
+        except KeyError:
+            return default
+
+    def _get_enrich_dataframe(self, **enrich_config):
+        df_enriched = self.__read_csv(enrich_config["enrich_path"])
+        properties = enrich_config["properties"]
+        df_enriched = df_enriched[["item_id"] + properties]
+
+        return df_enriched
+
+    def _add_user_info(self, user):
+        df_user = self.__read_csv(user["path"])
+        extra_features = get_optional_argument(user, "extra_features", [])
+        df_user = df_user[["user_id"] + extra_features]
+
+        total_users = df_user.shape[0]
+        desc = "Adding user info into network"
+        properties = list(df_user.columns)
+        properties.remove("user_id")
+
+        for _, row in tqdm(df_user.iterrows(), total=total_users, desc=desc):
+            user_node = UserNode(row["user_id"])
+            self.add_node(user_node)
+
+            for property_ in properties:
+                self._add_node_property(user_node, row, property_)
+
+    def _add_ratings(self, ratings):
+        df_ratings = self.__read_csv(ratings["path"])
+        total_ratings = df_ratings.shape[0]
+        desc = "Adding ratings into network"
+
+        for _, row in tqdm(df_ratings.iterrows(), total=total_ratings, desc=desc):
+            item_node = ItemNode(row["item_id"])
+            user_node = UserNode(row["user_id"])
+
+            if item_node in self and user_node in self:
+                attrs = {"type": "rated", "rating": row["rating"]}
+                if ratings["timestamp"]:
+                    attrs["timestamp"] = row["timestamp"]
+
+                self.add_edge(user_node, item_node, **attrs)
+
+    def _add_social_links(self, social):
+        df_social = self.__read_csv(social["path"])
+        total_links = df_social.shape[0]
+        desc = "Adding social links between users into network"
+
+        for _, row in tqdm(df_social.iterrows(), total=total_links, desc=desc):
+            user1_node = UserNode(row["user1"])
+            user2_node = UserNode(row["user2"])
+
+            if user1_node in self and user2_node in self:
+                self.add_edge(user1_node, user2_node)

framework/dataloader/graph/node.py

@@ -0,0 +1,80 @@
+"""
+    Base node class
+""" 
+class Node():
+    def __init__(self, idx, **attrs):
+        self.id = idx
+        self.attrs = attrs
+    
+    def __hash__(self):
+        return hash(str(self))
+    
+    def get_id(self):
+        return self.id
+
+"""
+    Node of type Item class
+"""
+class ItemNode(Node):
+    def __init__(self, idx, **attrs):
+        super().__init__(idx, **attrs)
+    
+    def __str__(self):
+        return f'Item({self.id})'
+    
+    def __repr__(self):
+        return str(self)
+    
+    def __hash__(self):
+        return super().__hash__()
+    
+    def __eq__(self, other):
+        if isinstance(self, ItemNode) and isinstance(other, ItemNode):
+            return self.id == other.id
+        return False
+
+"""
+    Node of type User class
+"""
+class UserNode(Node):
+    def __init__(self, idx, **attrs):
+        super().__init__(idx, **attrs)
+    
+    def __str__(self):
+        return f'User({self.id})'
+
+    def __repr__(self):
+        return str(self)
+    
+    def __hash__(self):
+        return super().__hash__()
+    
+    def __eq__(self, other):
+        if isinstance(self, UserNode) and isinstance(other, UserNode):
+            return self.id == other.id
+        return False
+
+"""
+    Node of type Property class
+"""
+class PropertyNode(Node):
+    def __init__(self, idx, property_type, **attrs):
+        super().__init__(idx, **attrs)
+        self.property_type = property_type
+    
+    def __str__(self):
+        return f'Property({self.id}, {self.property_type})'
+    
+    def __repr__(self):
+        return str(self)
+    
+    def __hash__(self):
+        return super().__hash__()
+    
+    def __eq__(self, other):
+        if isinstance(self, PropertyNode) and isinstance(other, PropertyNode) and self.property_type == other.property_type:
+            return self.id == other.id
+        return False
+    
+    def get_property_type(self):
+        return self.property_type

framework/dataloader/preprocess/methods.py

@@ -0,0 +1,47 @@
+from ..graph.graph import Graph
+
+from tqdm import tqdm
+
+def apply_method(G, **info):
+    method2fun = {
+        'binarize': binarize,
+        'filter_kcore': filter_kcore
+    }
+
+    try:
+        f = method2fun[info['method']]
+        f(G, **info['parameters'])
+    except KeyError:
+        raise KeyError(f'Preprocessing method {info["method"]} is not implemented.')
+
+def binarize(G: Graph, threshold: int):
+    desc='Binarizing user rating'
+    for (user, item) in tqdm(list(G.get_rating_edges()), desc=desc):
+        edge_data = G.get_edge_data(user,item)
+        
+        bin_rate = 0 # negative
+        if edge_data['rating'] >= threshold:
+            bin_rate = 1
+
+        G[user][item]['rating'] = bin_rate
+
+def filter_kcore(G: Graph, k: int, target: str, iterations: int = 1):
+    print(f'K-core filtering (target={target}), where core={k} and {iterations} it.')
+    for it in range(iterations):
+        desc = f'K-core filtering {it+1} iteration over edges from each {target}'
+
+        data = None
+        if target == 'user':
+            data = G.rating_edges.copy()
+        elif target == 'item':
+            data = G.rating_item2users.copy()
+
+        n_total = len(list(data.keys()))
+
+        count = 0
+        for (u, vs) in tqdm(data.items(), total=n_total, desc=desc):
+            if len(vs) < k:
+                G.remove_node(u)
+                count += 1
+        if count == 0:
+            break

framework/evaluator/metric.py

@@ -0,0 +1,39 @@
+class Metric:
+    def __init__(self, k : int, relevance_threshold : int = 0):
+        self.k = k
+        self.relevance_threshold = relevance_threshold
+
+    def name(self) -> str:
+        raise NotImplementedError('Implement the name() method for your metric subclass')
+
+    def eval(self, ratings, recommendations):
+        """
+        Evaluate recommendation metric over user ratings
+        :param ratings: ratings used as ground truth
+            of type {user: [(item1, rating1), (item2, rating2), ...]}
+        :param recommendations: model k first recommendations
+            of type {user: [(item1, rating1), (item2, rating2), ...]}
+        """
+        raise NotImplementedError('Implement the eval() method for your metric subclass')
+    
+    def _get_relevant_ratings(self, ratings, with_ratings=False):
+        relevant_ratings = {}
+        for u, u_ratings in ratings.items():
+            relevant_items = []
+            for (i, rating) in u_ratings:
+                if rating >= self.relevance_threshold:
+                    if not with_ratings:
+                        relevant_items.append(i)
+                    else:
+                        relevant_items.append((i, rating))
+                else:
+                    # It's sorted, so I'm sure the next ones wont be greater than threshold
+                    break
+            
+            if len(relevant_items) > 0:
+                relevant_ratings[u] = relevant_items
+        
+        return relevant_ratings
+            
+            
+                

framework/evaluator/metric2class.py

@@ -0,0 +1,10 @@
+metric2class = {
+    'MAP': {
+        'submodule': 'metrics.map',
+        'class': 'MAP'
+    },
+    'nDCG': {
+        'submodule': 'metrics.ndcg',
+        'class': 'nDCG'
+    }
+}

framework/evaluator/metrics/map.py

@@ -0,0 +1,33 @@
+from ..metric import Metric
+
+import numpy as np
+
+class MAP(Metric):
+    # reference: https://github.com/benhamner/Metrics/blob/master/Python/ml_metrics/average_precision.py
+    def init(self, k : int, relevance_threshold=0):
+        super().init(k, relevance_threshold)
+
+    def name(self):
+        return f'MAP@{self.k}'
+    
+    def eval(self, ratings, recommendations):
+        relevant_items = self._get_relevant_ratings(ratings)
+        users_apk = [self._apk(set(rel_items), recommendations[u]) for u, rel_items in relevant_items.items()]
+        return np.mean(users_apk)
+    
+    def _apk(self, rel_items, recommendations):
+        if len(recommendations) > self.k:
+            recommendations = recommendations[:self.k]
+        
+        score = 0.0
+        num_hits = 0.0
+
+        if not rel_items:
+            return score
+
+        for i, rec in enumerate(recommendations):
+            if rec in rel_items and rec not in recommendations[:i]:
+                num_hits += 1.0
+                score += num_hits/(i+1.0)
+
+        return score/min(len(rel_items), self.k)

framework/evaluator/metrics/ndcg.py

@@ -0,0 +1,49 @@
+from ..metric import Metric
+import numpy as np
+
+class nDCG(Metric):
+    def __init__(self, k: int, relevance_threshold: int = 0):
+        super().__init__(k, relevance_threshold)
+    
+    def name(self):
+        return f'nDCG@{self.k}'
+    
+    def eval(self, ratings, recommendations):
+        relevant_items = self._get_relevant_ratings(ratings, with_ratings=True)
+        users_ndcg = []
+        for u, rel_items in relevant_items.items():
+            u_recs = self._get_user_rec_relevance(rel_items, recommendations[u])
+            ndcg = self._calculate_ndcg(rel_items, u_recs)
+            users_ndcg.append(ndcg)
+            
+        return np.mean(users_ndcg)
+
+    def _calculate_dcg(self, recs):
+        recs = np.asfarray(recs)[:self.k]
+        if not recs.size:
+            return 0.0
+        else:
+            return np.sum(recs / np.log2(np.arange(2, recs.size+2)))
+        
+    def _get_user_rec_relevance(self, relevant_items, recs):
+        rel = {} # {item: float(rating)}
+        for (item, rating) in relevant_items:
+            rel[item] = rating
+        
+        recs_relevance = []
+        for item in recs:
+            item_rel = float(rel.get(item, 0.0))
+            recs_relevance.append(item_rel)
+        
+        return recs_relevance
+
+        
+    def _calculate_ndcg(self, relevant_items, recs):
+        # already ordered
+        relevant_items = [rating for _, rating in relevant_items[:self.k]]
+        idcg = self._calculate_dcg(relevant_items)
+        if not idcg:
+            return 0.0
+        else:
+            return self._calculate_dcg(recs) / idcg
+