SLEP005: Outlier Rejection API

Author: glemaitre

index.rst

@@ -26,6 +26,7 @@
     slep002/proposal
     slep003/proposal
     slep004/proposal
+    slep005/proposal
 
 .. toctree::
     :maxdepth: 1

slep005/proposal.rst

@@ -0,0 +1,98 @@
+.. _slep_005:
+
+=====================
+Outlier rejection API
+=====================
+
+:Author: Oliver Raush ([email protected]), Guillaume Lemaitre ([email protected])
+:Status: Draft
+:Type: Standards Track
+:Created: created on, in 2019-03-01
+:Resolution: <url>
+
+Abstract
+--------
+
+We propose a new mixin ``OutlierRejectionMixin`` implementing a
+``fit_resample(X, y)`` method. This method will remove samples from
+``X`` and ``y`` to get a outlier-free dataset. This method is also
+handle in ``Pipeline``.
+
+Detailed description
+--------------------
+
+Fitting a machine learning model on an outlier-free dataset can be
+beneficial.  Currently, the family of outlier detection algorithms
+allows to detect outliers using `estimator.fit_predict(X, y)`. However,
+there is no mechanism to remove outliers without any manual step. It
+is even impossible when a ``Pipeline`` is used.
+
+We propose the following changes:
+
+* implement an ``OutlierRejectionMixin``;
+* this mixin add a method ``fit_resample(X, y)`` removing outliers
+  from ``X`` and ``y``;
+* ``fit_resample`` should be handled in ``Pipeline``.
+
+Implementation
+--------------
+
+API changes are implemented in
+https://github.com/scikit-learn/scikit-learn/pull/13269
+
+Estimator implementation
+........................
+
+The new mixin is implemented as::
+  
+  class OutlierRejectionMixin:
+    _estimator_type = "outlier_rejector"
+    def fit_resample(self, X, y):
+        inliers = self.fit_predict(X) == 1
+        return safe_mask(X, inliers), safe_mask(y, inliers)
+
+This will be used as follows for the outlier detection algorithms::
+  
+  class IsolationForest(BaseBagging, OutlierMixin, OutlierRejectionMixin):
+      ...
+      
+One can use the new algorithm with::
+  
+  from sklearn.ensemble import IsolationForest
+  estimator = IsolationForest()
+  X_free, y_free = estimator.fit_resample(X, y)
+
+Pipeline implementation
+.......................
+
+To handle outlier rejector in ``Pipeline``, we enforce the following:
+
+* an estimator cannot implement both ``fit_resample(X, y)`` and
+  ``fit_transform(X)`` / ``transform(X)``.
+* ``fit_predict(X)`` (i.e., clustering methods) should not be called if an
+  outlier rejector is in the pipeline.
+
+Backward compatibility
+----------------------
+
+There is no backward incompatibilities with the current API.
+
+Discussion
+----------
+
+* https://github.com/scikit-learn/scikit-learn/pull/13269
+
+References and Footnotes
+------------------------
+
+.. [1] Each SLEP must either be explicitly labeled as placed in the public
+   domain (see this SLEP as an example) or licensed under the `Open
+   Publication License`_.
+
+.. _Open Publication License: https://www.opencontent.org/openpub/
+
+
+Copyright
+---------
+
+This document has been placed in the public domain. [1]_