src.fairreckitlib.data.ratings.kl_converter

 1"""This module contains the Kullback-Leibler converter.
 2
 3This way of converting is not implemented in the data pipeline.
 4The intended use of this stems from the following paper about mainstreaminess:
 5
 6https://www.christinebauer.eu/publications/bauer-2019-plosone-mainstreaminess/
 7
 8see pages 10-11.
 9
10This paper describes an altered version of the Kullback-Leibler formla
11and converts implicit ratings to explicit ratings in the range [0,1].
12
13Classes:
14
15    KLConverter: can convert ratings using the Kullback-Leibler formula.
16
17Functions:
18
19    create_kl_converter: create an instance of the class (factory creation compatible).
20    create_kl_converter_params: create kl converter config parameters.
21
22This program has been developed by students from the bachelor Computer Science at
23Utrecht University within the Software Project course.
24© Copyright Utrecht University (Department of Information and Computing Sciences)
25"""
26
27from typing import Any, Dict
28
29import pandas as pd
30
31from ...core.config.config_parameters import ConfigParameters
32from .base_converter import RatingConverter
33
34
35class KLConverter(RatingConverter):
36    """Kullback-Leibler Converter on data ratings.
37
38    Applies the Kullback-Leibler formula to the rating column of the dataframe.
39    """
40
41    def run(self, dataframe: pd.DataFrame) -> pd.DataFrame:
42        """Apply the Kullback-Leibler formula to convert ratings.
43
44        Args:
45            dataframe: with 'user', 'item' and 'rating' columns.
46
47        Returns:
48            the converted dataframe.
49        """
50        # TODO apply kullback-leibler formula on the rating column. Needs APC/ALC arg.
51        # method = self.params['method']
52        # use the APC/ALC parameter, import count.py from this package to calculate either
53        # apply the altered kl formula to each row of the given dataframe:
54        #       1 / np.mean(1 - np.exp(-KL(P||Q)), 1 - np.exp(-KL(Q||P)))
55        #       where
56        #           KL(P||Q) = sum(A.C(u) * np.log(A.C(u) / A.C   ))
57        #           KL(Q||P) = sum(A.C    * np.log(A.C    / A.C(u)))
58        #   note that the above is a slightly abstract and incomplete notation,
59        #   please consult the paper linked at the top.
60        # return converted_dataframe
61        raise RuntimeError()
62
63
64def create_kl_converter(name: str, params: Dict[str, Any], **_) -> KLConverter:
65    """Create the KL Converter.
66
67    Args:
68        name: the name of the converter.
69        params: containing the following name-value pairs:
70            method(str): the method to apply, either 'APC' or 'ALC'.
71
72    Returns:
73        the data kl converter.
74    """
75    return KLConverter(name, params)
76
77
78def create_kl_converter_params(**_) -> ConfigParameters:
79    """Create the parameters of the kl converter.
80
81    Returns:
82        the configuration parameters of the converter.
83    """
84    methods = ['APC', 'ALC']
85
86    params = ConfigParameters()
87    params.add_single_option('method', str, methods[0], methods)
88    return params