src.fairreckitlib.evaluation.metrics.metric_base

  1"""This module contains the base class for all metrics.
  2
  3Classes:
  4
  5    BaseMetric: the base class for metrics.
  6    ColumnMetric: metric that uses two columns to compute the evaluation.
  7
  8This program has been developed by students from the bachelor Computer Science at
  9Utrecht University within the Software Project course.
 10© Copyright Utrecht University (Department of Information and Computing Sciences)
 11"""
 12
 13from abc import ABCMeta, abstractmethod
 14from typing import Any, Callable, Dict
 15
 16import pandas as pd
 17
 18from ..evaluation_sets import EvaluationSets
 19
 20
 21class BaseMetric(metaclass=ABCMeta):
 22    """Base class for FairRecKit metrics.
 23
 24    A metric is used for evaluating the performance of recommender system experiments.
 25    Derived metrics are expected to implement the abstract interface.
 26
 27    Abstract methods:
 28
 29    on_evaluate
 30
 31    Public methods:
 32
 33    evaluate
 34    get_name
 35    get_params
 36    """
 37
 38    def __init__(
 39            self,
 40            name: str,
 41            params: Dict[str, Any],
 42            *,
 43            requires_test_set: bool=True,
 44            requires_train_set: bool=False):
 45        """Construct the metric.
 46
 47        Args:
 48            name: the name of the metric.
 49            params: the parameters of the metric.
 50            requires_test_set: whether the metric requires the test set for evaluation.
 51            requires_train_set: whether the metric requires the train set for evaluation.
 52        """
 53        self.metric_name = name
 54        self.params = params
 55        self.requires_test_set = requires_test_set
 56        self.requires_train_set = requires_train_set
 57
 58    @abstractmethod
 59    def on_evaluate(self, eval_sets: EvaluationSets) -> float:
 60        """Evaluate the sets for the performance of the metric.
 61
 62        Derived classes should implement the evaluation logic of the metric.
 63
 64        Args:
 65            eval_sets: the sets to use for computing the performance of the metric.
 66
 67        Returns:
 68            the evaluated performance.
 69        """
 70        raise NotImplementedError()
 71
 72    def evaluate(self, eval_sets: EvaluationSets) -> float:
 73        """Evaluate the sets for the performance of the metric.
 74
 75        Args:
 76            eval_sets: the sets to use for computing the performance of the metric.
 77
 78        Raises:
 79            ArithmeticError: possibly raised by a metric on evaluation.
 80            MemoryError: possibly raised by a metric on evaluation.
 81            RuntimeError: when one of the required evaluation sets is None.
 82
 83        Returns:
 84            the evaluated performance.
 85        """
 86        if self.requires_train_set and eval_sets.train is None or \
 87                self.requires_test_set and eval_sets.test is None:
 88            raise RuntimeError()
 89
 90        return self.on_evaluate(eval_sets)
 91
 92    def get_name(self):
 93        """Get the name of the metric.
 94
 95        Returns:
 96            the metric name.
 97        """
 98        return self.metric_name
 99
100    def get_params(self) -> Dict[str, Any]:
101        """Get the parameters of the metric.
102
103        Returns:
104            the metric parameters.
105        """
106        return dict(self.params)
107
108
109class ColumnMetric(BaseMetric, metaclass=ABCMeta):
110    """Metric that uses two columns to produce the performance evaluation.
111
112    The intended use of this class is to provide a base implementation for
113    computing the evaluation using two pandas Series columns. The actual data
114    that is provided in these columns can be anything depending on the derived class.
115    """
116
117    def __init__(
118            self,
119            name: str,
120            params: Dict[str, Any],
121            eval_func: Callable[[pd.Series, pd.Series], float],
122            *,
123            requires_test_set: bool=True,
124            requires_train_set: bool= False):
125        """Construct the column metric.
126
127        Args:
128            name: the name of the metric.
129            params: the parameters of the metric.
130            eval_func: the evaluation function that uses two columns to compute the evaluation.
131            requires_test_set: whether the metric requires the test set for evaluation.
132            requires_train_set: whether the metric requires the train set for evaluation.
133        """
134        BaseMetric.__init__(
135            self,
136            name,
137            params,
138            requires_test_set=requires_test_set,
139            requires_train_set=requires_train_set
140        )
141        self.eval_func = eval_func