Update Space (evaluate main: 828c6327)

README.md

@@ -1,12 +1,84 @@
 ---
-title: Mahalanobis
-emoji: 📉
-colorFrom: purple
-colorTo: yellow
+title: Mahalanobis Distance
+emoji: 🤗 
+colorFrom: blue
+colorTo: red
 sdk: gradio
 sdk_version: 3.0.2
 app_file: app.py
 pinned: false
+tags:
+- evaluate
+- metric
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces#reference
+# Metric Card for Mahalanobis Distance
+
+## Metric Description
+Mahalonobis distance is the distance between a point and a distribution (as opposed to the distance between two points), making it the multivariate equivalent of the Euclidean distance.
+
+It is often used in multivariate anomaly detection, classification on highly imbalanced datasets and one-class classification. 
+
+## How to Use
+At minimum, this metric requires two `list`s of datapoints: 
+
+```python
+>>> mahalanobis_metric = evaluate.load("mahalanobis")
+>>> results = mahalanobis_metric.compute(reference_distribution=[[0, 1], [1, 0]], X=[[0, 1]])
+```
+
+### Inputs
+- `X` (`list`): data points to be compared with the `reference_distribution`.
+- `reference_distribution` (`list`): data points from the reference distribution that we want to compare to.
+                    
+### Output Values
+`mahalanobis` (`array`): the Mahalonobis distance for each data point in `X`.
+
+```python
+>>> print(results)
+{'mahalanobis': array([0.5])}
+```
+
+#### Values from Popular Papers
+*N/A*
+
+### Example
+
+```python
+>>> mahalanobis_metric = evaluate.load("mahalanobis")
+>>> results = mahalanobis_metric.compute(reference_distribution=[[0, 1], [1, 0]], X=[[0, 1]])
+>>> print(results)
+{'mahalanobis': array([0.5])}
+```
+
+## Limitations and Bias
+
+The Mahalanobis distance is only able to capture linear relationships between the variables, which means it cannot capture all types of outliers. Mahalanobis distance also fails to faithfully represent data that is highly skewed or multimodal.
+
+## Citation
+```bibtex
+@inproceedings{mahalanobis1936generalized,
+  title={On the generalized distance in statistics},
+  author={Mahalanobis, Prasanta Chandra},
+  year={1936},
+  organization={National Institute of Science of India}
+}
+```
+
+```bibtex
+@article{de2000mahalanobis,
+  title={The Mahalanobis distance},
+  author={De Maesschalck, Roy and Jouan-Rimbaud, Delphine and Massart, D{\'e}sir{\'e} L},
+  journal={Chemometrics and intelligent laboratory systems},
+  volume={50},
+  number={1},
+  pages={1--18},
+  year={2000},
+  publisher={Elsevier}
+}
+```
+
+## Further References
+-[Wikipedia -- Mahalanobis Distance](https://en.wikipedia.org/wiki/Mahalanobis_distance)
+
+-[Machine Learning Plus -- Mahalanobis Distance](https://www.machinelearningplus.com/statistics/mahalanobis-distance/)

app.py

@@ -0,0 +1,6 @@
+import evaluate
+from evaluate.utils import launch_gradio_widget
+
+
+module = evaluate.load("mahalanobis")
+launch_gradio_widget(module)

mahalanobis.py

@@ -0,0 +1,100 @@
+# Copyright 2021 The HuggingFace Datasets Authors and the current dataset script contributor.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Mahalanobis metric."""
+
+import datasets
+import numpy as np
+
+import evaluate
+
+
+_DESCRIPTION = """
+Compute the Mahalanobis Distance
+
+Mahalonobis distance is the distance between a point and a distribution.
+And not between two distinct points. It is effectively a multivariate equivalent of the Euclidean distance.
+It was introduced by Prof. P. C. Mahalanobis in 1936
+and has been used in various statistical applications ever since
+[source: https://www.machinelearningplus.com/statistics/mahalanobis-distance/]
+"""
+
+_CITATION = """\
+@article{de2000mahalanobis,
+  title={The mahalanobis distance},
+  author={De Maesschalck, Roy and Jouan-Rimbaud, Delphine and Massart, D{\'e}sir{\'e} L},
+  journal={Chemometrics and intelligent laboratory systems},
+  volume={50},
+  number={1},
+  pages={1--18},
+  year={2000},
+  publisher={Elsevier}
+}
+"""
+
+_KWARGS_DESCRIPTION = """
+Args:
+    X: List of datapoints to be compared with the `reference_distribution`.
+    reference_distribution: List of datapoints from the reference distribution we want to compare to.
+Returns:
+    mahalanobis: The Mahalonobis distance for each datapoint in `X`.
+Examples:
+
+    >>> mahalanobis_metric = evaluate.load("mahalanobis")
+    >>> results = mahalanobis_metric.compute(reference_distribution=[[0, 1], [1, 0]], X=[[0, 1]])
+    >>> print(results)
+    {'mahalanobis': array([0.5])}
+"""
+
+
+@evaluate.utils.file_utils.add_start_docstrings(_DESCRIPTION, _KWARGS_DESCRIPTION)
+class Mahalanobis(evaluate.EvaluationModule):
+    def _info(self):
+        return evaluate.EvaluationModuleInfo(
+            description=_DESCRIPTION,
+            citation=_CITATION,
+            inputs_description=_KWARGS_DESCRIPTION,
+            features=datasets.Features(
+                {
+                    "X": datasets.Sequence(datasets.Value("float", id="sequence"), id="X"),
+                }
+            ),
+        )
+
+    def _compute(self, X, reference_distribution):
+
+        # convert to numpy arrays
+        X = np.array(X)
+        reference_distribution = np.array(reference_distribution)
+
+        # Assert that arrays are 2D
+        if len(X.shape) != 2:
+            raise ValueError("Expected `X` to be a 2D vector")
+        if len(reference_distribution.shape) != 2:
+            raise ValueError("Expected `reference_distribution` to be a 2D vector")
+        if reference_distribution.shape[0] < 2:
+            raise ValueError(
+                "Expected `reference_distribution` to be a 2D vector with more than one element in the first dimension"
+            )
+
+        # Get mahalanobis distance for each prediction
+        X_minus_mu = X - np.mean(reference_distribution)
+        cov = np.cov(reference_distribution.T)
+        try:
+            inv_covmat = np.linalg.inv(cov)
+        except np.linalg.LinAlgError:
+            inv_covmat = np.linalg.pinv(cov)
+        left_term = np.dot(X_minus_mu, inv_covmat)
+        mahal_dist = np.dot(left_term, X_minus_mu.T).diagonal()
+
+        return {"mahalanobis": mahal_dist}

requirements.txt

@@ -0,0 +1,3 @@
+# TODO: fix github to release
+git+https://github.com/huggingface/evaluate.git@b6e6ed7f3e6844b297bff1b43a1b4be0709b9671
+datasets~=2.0