src.fairreckitlib.data.data_modifier

  1"""This module contains the base class and factory for data modification.
  2
  3Classes:
  4
  5    DataModifier: the base class for data modifying.
  6    DataModifierFactory: the factory that creates data modifiers related to a dataset matrix.
  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 ..core.config.config_factories import Factory, GroupFactory, FUNC_CREATE_PARAMS
 19from ..core.config.config_parameters import ConfigParameters
 20from .set.dataset import Dataset
 21from .set.dataset_registry import DataRegistry
 22
 23class DataModifier(metaclass=ABCMeta):
 24    """Base class for FairRecKit data modifiers.
 25
 26    Public methods:
 27
 28    get_name
 29    get_params
 30    run
 31    """
 32
 33    def __init__(self, name: str, params: Dict[str, Any]):
 34        """Construct the DataModifier.
 35
 36        Args:
 37            name: the name of the modifier.
 38            params: the modifier parameters.
 39        """
 40        self.name = name
 41        self.params = params
 42
 43    def get_name(self) -> str:
 44        """Get the name of the modifier.
 45
 46        Returns:
 47            the modifier name.
 48        """
 49        return self.name
 50
 51    def get_params(self) -> Dict[str, Any]:
 52        """Get the parameters of the modifier.
 53
 54        Returns:
 55            the modifier parameters.
 56        """
 57        return dict(self.params)
 58
 59    @abstractmethod
 60    def run(self, dataframe: pd.DataFrame) -> Any:
 61        """Run the modifier on the specified dataframe.
 62
 63        Args:
 64            dataframe: source df to modify.
 65
 66        Returns:
 67            any modification to the dataframe.
 68        """
 69        raise NotImplementedError()
 70
 71
 72class DataModifierFactory(Factory):
 73    """Factory for data modifier creation.
 74
 75    The intended use is to associate the factory with a specific matrix of a dataset.
 76    Both the created parameters and the created data modifiers are supplied
 77    with a reference to the dataset and the name of the matrix they belong to.
 78    """
 79
 80    def __init__(self, matrix_name: str, dataset: Dataset):
 81        """Construct the DataModifierFactory.
 82
 83        Args:
 84            matrix_name: the name of the matrix that it relates to.
 85            dataset: the dataset associated with the matrix.
 86        """
 87        Factory.__init__(self, matrix_name)
 88        self.dataset = dataset
 89
 90    def create(self, obj_name: str, obj_params: Dict[str, Any]=None, **kwargs) -> DataModifier:
 91        """Create and return a new data modifier with the specified name.
 92
 93        The specified parameters are expected to be of the same structure as the defaults
 94        of the ConfigParameters that are associated with the desired data modifier.
 95        When no parameters are specified it will use the data modifier's defaults.
 96
 97        Args:
 98            obj_name: the name of the data modifier to create.
 99            obj_params: the parameters of the data modifier.
100
101        Keyword Args:
102            Any: extra arguments that need to be passed to the data modifier on creation.
103
104        Returns:
105            the created data modifier or None when it does not exist.
106        """
107        kwargs['dataset'] = self.dataset
108        kwargs['matrix_name'] = self.factory_name
109        return Factory.create(self, obj_name, obj_params, **kwargs)
110
111    def on_create_params(self, obj_name: str) -> ConfigParameters:
112        """Create parameters for the data modifier with the specified name.
113
114        Args:
115            obj_name: name of the data modifier to create parameters for.
116
117        Returns:
118            the configuration parameters of the object or empty parameters when it does not exist.
119        """
120        kwargs = {
121            'column_name': obj_name,
122            'dataset': self.dataset,
123            'matrix_name': self.factory_name
124        }
125        return self.factory[obj_name][FUNC_CREATE_PARAMS](**kwargs)
126
127
128def create_data_modifier_factory(
129        data_registry: DataRegistry,
130        factory_name: str,
131        func_on_add_entries: Callable[[DataModifierFactory, Dataset], None]) -> GroupFactory:
132    """Create a data modifier factory for each dataset-matrix pair.
133
134    Args:
135
136        data_registry: the data registry with available datasets.
137        factory_name: the name of the data modifier factory.
138        func_on_add_entries: callback for each dataset-matrix pair to add data modifiers.
139
140    Returns:
141        the factory with all available data modifiers per dataset-matrix pair.
142    """
143    factory = GroupFactory(factory_name)
144
145    for dataset_name in data_registry.get_available_sets():
146        dataset = data_registry.get_set(dataset_name)
147        dataset_factory = GroupFactory(dataset.get_name())
148
149        factory.add_factory(dataset_factory)
150
151        for matrix_name in dataset.get_available_matrices():
152            matrix_factory = DataModifierFactory(matrix_name, dataset)
153            func_on_add_entries(matrix_factory, dataset)
154            dataset_factory.add_factory(matrix_factory)
155
156    return factory