datasets

1
# Copyright 2021 The HuggingFace Datasets Authors and the current dataset script contributor.
2
#
3
# Licensed under the Apache License, Version 2.0 (the "License");
4
# you may not use this file except in compliance with the License.
5
# You may obtain a copy of the License at
6
#
7
#     http://www.apache.org/licenses/LICENSE-2.0
8
#
9
# Unless required by applicable law or agreed to in writing, software
10
# distributed under the License is distributed on an "AS IS" BASIS,
11
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
# See the License for the specific language governing permissions and
13
# limitations under the License.
14
"""Mahalanobis metric."""
15

16
import numpy as np
17

18
import datasets
19

20

21
_DESCRIPTION = """
22
Compute the Mahalanobis Distance
23

24
Mahalonobis distance is the distance between a point and a distribution.
25
And not between two distinct points. It is effectively a multivariate equivalent of the Euclidean distance.
26
It was introduced by Prof. P. C. Mahalanobis in 1936
27
and has been used in various statistical applications ever since
28
[source: https://www.machinelearningplus.com/statistics/mahalanobis-distance/]
29
"""
30

31
_CITATION = """\
32
@article{de2000mahalanobis,
33
  title={The mahalanobis distance},
34
  author={De Maesschalck, Roy and Jouan-Rimbaud, Delphine and Massart, D{\'e}sir{\'e} L},
35
  journal={Chemometrics and intelligent laboratory systems},
36
  volume={50},
37
  number={1},
38
  pages={1--18},
39
  year={2000},
40
  publisher={Elsevier}
41
}
42
"""
43

44
_KWARGS_DESCRIPTION = """
45
Args:
46
    X: List of datapoints to be compared with the `reference_distribution`.
47
    reference_distribution: List of datapoints from the reference distribution we want to compare to.
48
Returns:
49
    mahalanobis: The Mahalonobis distance for each datapoint in `X`.
50
Examples:
51

52
    >>> mahalanobis_metric = datasets.load_metric("mahalanobis")
53
    >>> results = mahalanobis_metric.compute(reference_distribution=[[0, 1], [1, 0]], X=[[0, 1]])
54
    >>> print(results)
55
    {'mahalanobis': array([0.5])}
56
"""
57

58

59
@datasets.utils.file_utils.add_start_docstrings(_DESCRIPTION, _KWARGS_DESCRIPTION)
60
class Mahalanobis(datasets.Metric):
61
    def _info(self):
62
        return datasets.MetricInfo(
63
            description=_DESCRIPTION,
64
            citation=_CITATION,
65
            inputs_description=_KWARGS_DESCRIPTION,
66
            features=datasets.Features(
67
                {
68
                    "X": datasets.Sequence(datasets.Value("float", id="sequence"), id="X"),
69
                }
70
            ),
71
        )
72

73
    def _compute(self, X, reference_distribution):
74
        # convert to numpy arrays
75
        X = np.array(X)
76
        reference_distribution = np.array(reference_distribution)
77

78
        # Assert that arrays are 2D
79
        if len(X.shape) != 2:
80
            raise ValueError("Expected `X` to be a 2D vector")
81
        if len(reference_distribution.shape) != 2:
82
            raise ValueError("Expected `reference_distribution` to be a 2D vector")
83
        if reference_distribution.shape[0] < 2:
84
            raise ValueError(
85
                "Expected `reference_distribution` to be a 2D vector with more than one element in the first dimension"
86
            )
87

88
        # Get mahalanobis distance for each prediction
89
        X_minus_mu = X - np.mean(reference_distribution)
90
        cov = np.cov(reference_distribution.T)
91
        try:
92
            inv_covmat = np.linalg.inv(cov)
93
        except np.linalg.LinAlgError:
94
            inv_covmat = np.linalg.pinv(cov)
95
        left_term = np.dot(X_minus_mu, inv_covmat)
96
        mahal_dist = np.dot(left_term, X_minus_mu.T).diagonal()
97

98
        return {"mahalanobis": mahal_dist}
99