Skip to content

from cluster_experiments.inference.metric import *

Metric

Bases: ABC

An abstract base class used to represent a Metric with an alias.

Attributes

alias : str A string representing the alias of the metric

Source code in cluster_experiments/inference/metric.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
class Metric(ABC):
    """
    An abstract base class used to represent a Metric with an alias.

    Attributes
    ----------
    alias : str
        A string representing the alias of the metric
    """

    def __init__(self, alias: str):
        """
        Parameters
        ----------
        alias : str
            The alias of the metric
        """
        self.alias = alias
        self._validate_alias()

    def _validate_alias(self):
        """
        Validates the alias input for the Metric class.

        Raises
        ------
        TypeError
            If the alias is not a string
        """
        if not isinstance(self.alias, str):
            raise TypeError("Metric alias must be a string")

    @property
    @abstractmethod
    def target_column(self) -> str:
        """
        Abstract property to return the target column to feed the experiment analysis class, from the metric definition.

        Returns
        -------
        str
            The target column name
        """
        pass

    @abstractmethod
    def get_mean(self, df: pd.DataFrame) -> float:
        """
        Abstract method to return the mean value of the metric, given a dataframe.

        Returns
        -------
        float
            The mean value of the metric
        """
        pass

    @classmethod
    def from_metrics_config(cls, config: dict) -> "Metric":
        """
        Class method to create a Metric instance from a configuration dictionary.

        Parameters
        ----------
        config : dict
            A dictionary containing the configuration of the metric

        Returns
        -------
        Metric
            A Metric instance
        """
        if "numerator_name" in config:
            return RatioMetric.from_metrics_config(config)
        return SimpleMetric.from_metrics_config(config)

target_column: str abstractmethod property

Abstract property to return the target column to feed the experiment analysis class, from the metric definition.

Returns

str The target column name

__init__(alias)

Parameters

alias : str The alias of the metric

Source code in cluster_experiments/inference/metric.py 
16
17
18
19
20
21
22
23
24
def __init__(self, alias: str):
    """
    Parameters
    ----------
    alias : str
        The alias of the metric
    """
    self.alias = alias
    self._validate_alias()

from_metrics_config(config) classmethod

Class method to create a Metric instance from a configuration dictionary.

Parameters

config : dict A dictionary containing the configuration of the metric

Returns

Metric A Metric instance

Source code in cluster_experiments/inference/metric.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
@classmethod
def from_metrics_config(cls, config: dict) -> "Metric":
    """
    Class method to create a Metric instance from a configuration dictionary.

    Parameters
    ----------
    config : dict
        A dictionary containing the configuration of the metric

    Returns
    -------
    Metric
        A Metric instance
    """
    if "numerator_name" in config:
        return RatioMetric.from_metrics_config(config)
    return SimpleMetric.from_metrics_config(config)

get_mean(df) abstractmethod

Abstract method to return the mean value of the metric, given a dataframe.

Returns

float The mean value of the metric

Source code in cluster_experiments/inference/metric.py 
51
52
53
54
55
56
57
58
59
60
61
@abstractmethod
def get_mean(self, df: pd.DataFrame) -> float:
    """
    Abstract method to return the mean value of the metric, given a dataframe.

    Returns
    -------
    float
        The mean value of the metric
    """
    pass

RatioMetric

Bases: Metric

A class used to represent a Ratio Metric with an alias, a numerator name, and a denominator name. To be used when the metric is defined at a lower level than the data used for the analysis.

Example

In a clustered experiment the participants were randomised based on their country of residence. The metric of interest is the salary of each participant. If the dataset fed into the analysis is at country-level, then a RatioMetric must be used: the numerator would be the sum of all salaries in the country, the denominator would be the number of participants in the country.

Attributes

alias : str A string representing the alias of the metric numerator_name : str A string representing the numerator name of the metric denominator_name : str A string representing the denominator name of the metric

Source code in cluster_experiments/inference/metric.py 
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
class RatioMetric(Metric):
    """
    A class used to represent a Ratio Metric with an alias, a numerator name, and a denominator name.
    To be used when the metric is defined at a lower level than the data used for the analysis.

    Example
    ----------
    In a clustered experiment the participants were randomised based on their country of residence.
    The metric of interest is the salary of each participant. If the dataset fed into the analysis is at country-level,
    then a RatioMetric must be used: the numerator would be the sum of all salaries in the country,
    the denominator would be the number of participants in the country.

    Attributes
    ----------
    alias : str
        A string representing the alias of the metric
    numerator_name : str
        A string representing the numerator name of the metric
    denominator_name : str
        A string representing the denominator name of the metric
    """

    def __init__(self, alias: str, numerator_name: str, denominator_name: str):
        """
        Parameters
        ----------
        alias : str
            The alias of the metric
        numerator_name : str
            The numerator name of the metric
        denominator_name : str
            The denominator name of the metric
        """
        super().__init__(alias)
        self.numerator_name = numerator_name
        self.denominator_name = denominator_name
        self._validate_names()

    def _validate_names(self):
        """
        Validates the numerator and denominator names input for the RatioMetric class.

        Raises
        ------
        TypeError
            If the numerator or denominator names are not strings
        """
        if not isinstance(self.numerator_name, str) or not isinstance(
            self.denominator_name, str
        ):
            raise TypeError("RatioMetric names must be strings")

    @property
    def target_column(self) -> str:
        """
        Returns the target column for the RatioMetric.

        Returns
        -------
        str
            The numerator name of the metric
        """
        return self.numerator_name

    def get_mean(self, df: pd.DataFrame) -> float:
        """
        Returns the mean value of the metric, given a dataframe.

        Returns
        -------
        float
            The mean value of the metric
        """
        return df[self.numerator_name].mean() / df[self.denominator_name].mean()

    @classmethod
    def from_metrics_config(cls, config: dict) -> "Metric":
        """
        Class method to create a RatioMetric instance from a configuration dictionary.

        Parameters
        ----------
        config : dict
            A dictionary containing the configuration of the metric

        Returns
        -------
        RatioMetric
            A RatioMetric instance
        """
        return cls(
            alias=config["alias"],
            numerator_name=config["numerator_name"],
            denominator_name=config["denominator_name"],
        )

target_column: str property

Returns the target column for the RatioMetric.

Returns

str The numerator name of the metric

__init__(alias, numerator_name, denominator_name)

Parameters

alias : str The alias of the metric numerator_name : str The numerator name of the metric denominator_name : str The denominator name of the metric

Source code in cluster_experiments/inference/metric.py 
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
def __init__(self, alias: str, numerator_name: str, denominator_name: str):
    """
    Parameters
    ----------
    alias : str
        The alias of the metric
    numerator_name : str
        The numerator name of the metric
    denominator_name : str
        The denominator name of the metric
    """
    super().__init__(alias)
    self.numerator_name = numerator_name
    self.denominator_name = denominator_name
    self._validate_names()

from_metrics_config(config) classmethod

Class method to create a RatioMetric instance from a configuration dictionary.

Parameters

config : dict A dictionary containing the configuration of the metric

Returns

RatioMetric A RatioMetric instance

Source code in cluster_experiments/inference/metric.py 
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
@classmethod
def from_metrics_config(cls, config: dict) -> "Metric":
    """
    Class method to create a RatioMetric instance from a configuration dictionary.

    Parameters
    ----------
    config : dict
        A dictionary containing the configuration of the metric

    Returns
    -------
    RatioMetric
        A RatioMetric instance
    """
    return cls(
        alias=config["alias"],
        numerator_name=config["numerator_name"],
        denominator_name=config["denominator_name"],
    )

get_mean(df)

Returns the mean value of the metric, given a dataframe.

Returns

float The mean value of the metric

Source code in cluster_experiments/inference/metric.py 
232
233
234
235
236
237
238
239
240
241
def get_mean(self, df: pd.DataFrame) -> float:
    """
    Returns the mean value of the metric, given a dataframe.

    Returns
    -------
    float
        The mean value of the metric
    """
    return df[self.numerator_name].mean() / df[self.denominator_name].mean()

SimpleMetric

Bases: Metric

A class used to represent a Simple Metric with an alias and a name. To be used when the metric is defined at the same level of the data used for the analysis.

Example

In a clustered experiment the participants were randomised based on their country of residence. The metric of interest is the salary of each participant. If the dataset fed into the analysis is at participant-level, then a SimpleMetric must be used. However, if the dataset fed into the analysis is at country-level, then a RatioMetric must be used.

Attributes

alias : str A string representing the alias of the metric name : str A string representing the name of the metric

Source code in cluster_experiments/inference/metric.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
class SimpleMetric(Metric):
    """
    A class used to represent a Simple Metric with an alias and a name.
    To be used when the metric is defined at the same level of the data used for the analysis.

    Example
    ----------
    In a clustered experiment the participants were randomised based on their country of residence.
    The metric of interest is the salary of each participant. If the dataset fed into the analysis is at participant-level,
    then a SimpleMetric must be used. However, if the dataset fed into the analysis is at country-level, then a RatioMetric must be used.

    Attributes
    ----------
    alias : str
        A string representing the alias of the metric
    name : str
        A string representing the name of the metric
    """

    def __init__(self, alias: str, name: str):
        """
        Parameters
        ----------
        alias : str
            The alias of the metric
        name : str
            The name of the metric
        """
        super().__init__(alias)
        self.name = name
        self._validate_name()

    def _validate_name(self):
        """
        Validates the name input for the SimpleMetric class.

        Raises
        ------
        TypeError
            If the name is not a string
        """
        if not isinstance(self.name, str):
            raise TypeError("SimpleMetric name must be a string")

    @property
    def target_column(self) -> str:
        """
        Returns the target column for the SimpleMetric.

        Returns
        -------
        str
            The name of the metric
        """
        return self.name

    def get_mean(self, df: pd.DataFrame) -> float:
        """
        Returns the mean value of the metric, given a dataframe.

        Returns
        -------
        float
            The mean value of the metric
        """
        return df[self.name].mean()

    @classmethod
    def from_metrics_config(cls, config: dict) -> "Metric":
        """
        Class method to create a SimpleMetric instance from a configuration dictionary.

        Parameters
        ----------
        config : dict
            A dictionary containing the configuration of the metric

        Returns
        -------
        SimpleMetric
            A SimpleMetric instance
        """
        return cls(alias=config["alias"], name=config["name"])

target_column: str property

Returns the target column for the SimpleMetric.

Returns

str The name of the metric

__init__(alias, name)

Parameters

alias : str The alias of the metric name : str The name of the metric

Source code in cluster_experiments/inference/metric.py 
102
103
104
105
106
107
108
109
110
111
112
113
def __init__(self, alias: str, name: str):
    """
    Parameters
    ----------
    alias : str
        The alias of the metric
    name : str
        The name of the metric
    """
    super().__init__(alias)
    self.name = name
    self._validate_name()

from_metrics_config(config) classmethod

Class method to create a SimpleMetric instance from a configuration dictionary.

Parameters

config : dict A dictionary containing the configuration of the metric

Returns

SimpleMetric A SimpleMetric instance

Source code in cluster_experiments/inference/metric.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
@classmethod
def from_metrics_config(cls, config: dict) -> "Metric":
    """
    Class method to create a SimpleMetric instance from a configuration dictionary.

    Parameters
    ----------
    config : dict
        A dictionary containing the configuration of the metric

    Returns
    -------
    SimpleMetric
        A SimpleMetric instance
    """
    return cls(alias=config["alias"], name=config["name"])

get_mean(df)

Returns the mean value of the metric, given a dataframe.

Returns

float The mean value of the metric

Source code in cluster_experiments/inference/metric.py 
139
140
141
142
143
144
145
146
147
148
def get_mean(self, df: pd.DataFrame) -> float:
    """
    Returns the mean value of the metric, given a dataframe.

    Returns
    -------
    float
        The mean value of the metric
    """
    return df[self.name].mean()