| |
| |
|
|
| from numbers import Real |
|
|
| import numpy as np |
|
|
| from ..base import OutlierMixin, _fit_context |
| from ..metrics import accuracy_score |
| from ..utils._param_validation import Interval |
| from ..utils.validation import check_is_fitted |
| from ._robust_covariance import MinCovDet |
|
|
|
|
| class EllipticEnvelope(OutlierMixin, MinCovDet): |
| """An object for detecting outliers in a Gaussian distributed dataset. |
| |
| Read more in the :ref:`User Guide <outlier_detection>`. |
| |
| Parameters |
| ---------- |
| store_precision : bool, default=True |
| Specify if the estimated precision is stored. |
| |
| assume_centered : bool, default=False |
| If True, the support of robust location and covariance estimates |
| is computed, and a covariance estimate is recomputed from it, |
| without centering the data. |
| Useful to work with data whose mean is significantly equal to |
| zero but is not exactly zero. |
| If False, the robust location and covariance are directly computed |
| with the FastMCD algorithm without additional treatment. |
| |
| support_fraction : float, default=None |
| The proportion of points to be included in the support of the raw |
| MCD estimate. If None, the minimum value of support_fraction will |
| be used within the algorithm: `(n_samples + n_features + 1) / 2 * n_samples`. |
| Range is (0, 1). |
| |
| contamination : float, default=0.1 |
| The amount of contamination of the data set, i.e. the proportion |
| of outliers in the data set. Range is (0, 0.5]. |
| |
| random_state : int, RandomState instance or None, default=None |
| Determines the pseudo random number generator for shuffling |
| the data. Pass an int for reproducible results across multiple function |
| calls. See :term:`Glossary <random_state>`. |
| |
| Attributes |
| ---------- |
| location_ : ndarray of shape (n_features,) |
| Estimated robust location. |
| |
| covariance_ : ndarray of shape (n_features, n_features) |
| Estimated robust covariance matrix. |
| |
| precision_ : ndarray of shape (n_features, n_features) |
| Estimated pseudo inverse matrix. |
| (stored only if store_precision is True) |
| |
| support_ : ndarray of shape (n_samples,) |
| A mask of the observations that have been used to compute the |
| robust estimates of location and shape. |
| |
| offset_ : float |
| Offset used to define the decision function from the raw scores. |
| We have the relation: ``decision_function = score_samples - offset_``. |
| The offset depends on the contamination parameter and is defined in |
| such a way we obtain the expected number of outliers (samples with |
| decision function < 0) in training. |
| |
| .. versionadded:: 0.20 |
| |
| raw_location_ : ndarray of shape (n_features,) |
| The raw robust estimated location before correction and re-weighting. |
| |
| raw_covariance_ : ndarray of shape (n_features, n_features) |
| The raw robust estimated covariance before correction and re-weighting. |
| |
| raw_support_ : ndarray of shape (n_samples,) |
| A mask of the observations that have been used to compute |
| the raw robust estimates of location and shape, before correction |
| and re-weighting. |
| |
| dist_ : ndarray of shape (n_samples,) |
| Mahalanobis distances of the training set (on which :meth:`fit` is |
| called) observations. |
| |
| n_features_in_ : int |
| Number of features seen during :term:`fit`. |
| |
| .. versionadded:: 0.24 |
| |
| feature_names_in_ : ndarray of shape (`n_features_in_`,) |
| Names of features seen during :term:`fit`. Defined only when `X` |
| has feature names that are all strings. |
| |
| .. versionadded:: 1.0 |
| |
| See Also |
| -------- |
| EmpiricalCovariance : Maximum likelihood covariance estimator. |
| GraphicalLasso : Sparse inverse covariance estimation |
| with an l1-penalized estimator. |
| LedoitWolf : LedoitWolf Estimator. |
| MinCovDet : Minimum Covariance Determinant |
| (robust estimator of covariance). |
| OAS : Oracle Approximating Shrinkage Estimator. |
| ShrunkCovariance : Covariance estimator with shrinkage. |
| |
| Notes |
| ----- |
| Outlier detection from covariance estimation may break or not |
| perform well in high-dimensional settings. In particular, one will |
| always take care to work with ``n_samples > n_features ** 2``. |
| |
| References |
| ---------- |
| .. [1] Rousseeuw, P.J., Van Driessen, K. "A fast algorithm for the |
| minimum covariance determinant estimator" Technometrics 41(3), 212 |
| (1999) |
| |
| Examples |
| -------- |
| >>> import numpy as np |
| >>> from sklearn.covariance import EllipticEnvelope |
| >>> true_cov = np.array([[.8, .3], |
| ... [.3, .4]]) |
| >>> X = np.random.RandomState(0).multivariate_normal(mean=[0, 0], |
| ... cov=true_cov, |
| ... size=500) |
| >>> cov = EllipticEnvelope(random_state=0).fit(X) |
| >>> # predict returns 1 for an inlier and -1 for an outlier |
| >>> cov.predict([[0, 0], |
| ... [3, 3]]) |
| array([ 1, -1]) |
| >>> cov.covariance_ |
| array([[0.7411..., 0.2535...], |
| [0.2535..., 0.3053...]]) |
| >>> cov.location_ |
| array([0.0813... , 0.0427...]) |
| """ |
|
|
| _parameter_constraints: dict = { |
| **MinCovDet._parameter_constraints, |
| "contamination": [Interval(Real, 0, 0.5, closed="right")], |
| } |
|
|
| def __init__( |
| self, |
| *, |
| store_precision=True, |
| assume_centered=False, |
| support_fraction=None, |
| contamination=0.1, |
| random_state=None, |
| ): |
| super().__init__( |
| store_precision=store_precision, |
| assume_centered=assume_centered, |
| support_fraction=support_fraction, |
| random_state=random_state, |
| ) |
| self.contamination = contamination |
|
|
| @_fit_context(prefer_skip_nested_validation=True) |
| def fit(self, X, y=None): |
| """Fit the EllipticEnvelope model. |
| |
| Parameters |
| ---------- |
| X : array-like of shape (n_samples, n_features) |
| Training data. |
| |
| y : Ignored |
| Not used, present for API consistency by convention. |
| |
| Returns |
| ------- |
| self : object |
| Returns the instance itself. |
| """ |
| super().fit(X) |
| self.offset_ = np.percentile(-self.dist_, 100.0 * self.contamination) |
| return self |
|
|
| def decision_function(self, X): |
| """Compute the decision function of the given observations. |
| |
| Parameters |
| ---------- |
| X : array-like of shape (n_samples, n_features) |
| The data matrix. |
| |
| Returns |
| ------- |
| decision : ndarray of shape (n_samples,) |
| Decision function of the samples. |
| It is equal to the shifted Mahalanobis distances. |
| The threshold for being an outlier is 0, which ensures a |
| compatibility with other outlier detection algorithms. |
| """ |
| check_is_fitted(self) |
| negative_mahal_dist = self.score_samples(X) |
| return negative_mahal_dist - self.offset_ |
|
|
| def score_samples(self, X): |
| """Compute the negative Mahalanobis distances. |
| |
| Parameters |
| ---------- |
| X : array-like of shape (n_samples, n_features) |
| The data matrix. |
| |
| Returns |
| ------- |
| negative_mahal_distances : array-like of shape (n_samples,) |
| Opposite of the Mahalanobis distances. |
| """ |
| check_is_fitted(self) |
| return -self.mahalanobis(X) |
|
|
| def predict(self, X): |
| """ |
| Predict labels (1 inlier, -1 outlier) of X according to fitted model. |
| |
| Parameters |
| ---------- |
| X : array-like of shape (n_samples, n_features) |
| The data matrix. |
| |
| Returns |
| ------- |
| is_inlier : ndarray of shape (n_samples,) |
| Returns -1 for anomalies/outliers and +1 for inliers. |
| """ |
| values = self.decision_function(X) |
| is_inlier = np.full(values.shape[0], -1, dtype=int) |
| is_inlier[values >= 0] = 1 |
|
|
| return is_inlier |
|
|
| def score(self, X, y, sample_weight=None): |
| """Return the mean accuracy on the given test data and labels. |
| |
| In multi-label classification, this is the subset accuracy |
| which is a harsh metric since you require for each sample that |
| each label set be correctly predicted. |
| |
| Parameters |
| ---------- |
| X : array-like of shape (n_samples, n_features) |
| Test samples. |
| |
| y : array-like of shape (n_samples,) or (n_samples, n_outputs) |
| True labels for X. |
| |
| sample_weight : array-like of shape (n_samples,), default=None |
| Sample weights. |
| |
| Returns |
| ------- |
| score : float |
| Mean accuracy of self.predict(X) w.r.t. y. |
| """ |
| return accuracy_score(y, self.predict(X), sample_weight=sample_weight) |
|
|
