API Reference / algorithms / anomaly /

elliptic_envelope.py

Elliptic Envelope anomaly detection algorithm.

Classes

EllipticEnvelopeDetector

class algorithms.anomaly.elliptic_envelope.EllipticEnvelopeDetector(Classifier)

Elliptic Envelope for Gaussian-distributed anomaly detection.

The Elliptic Envelope algorithm detects anomalies by fitting a robust covariance estimate to the data and computing the Mahalanobis distance of each sample. It assumes the underlying data follows a multivariate Gaussian distribution and identifies outliers as points lying far from the distribution center.
Constructor 
__init__(
    self,
    contamination: float = 0.1,
    support_fraction: float | None = None,
    random_state: int | None = None,
)

Overview

The algorithm typically follows these steps:

  1. Estimate the robust location (mean) and covariance of the data
  2. Compute the Mahalanobis distance for each sample
  3. Define a threshold based on the expected contamination rate
  4. Points with distances exceeding the threshold are labeled as anomalies
The intuition: Most observations are concentrated around a central point, forming an elliptical shape in feature space. Points outside this "envelope" are likely anomalies.

Theory

Assuming data follows a Gaussian distribution, the Mahalanobis distance D_M(x) of a sample x is computed as:

D_M(x) = \sqrt{(x - \mu)^T \Sigma^{-1} (x - \mu)}
where:
  • \mu: Estimated location (mean vector)
  • \Sigma: Estimated covariance matrix
  • \Sigma^{-1}: Precision matrix (inverse covariance)
Squared Mahalanobis distances D_M(x)^2 for Gaussian data follow a chi-square distribution with p degrees of freedom (where p is the number of features).

Score interpretation:

  • Low distance → Normal point (close to distribution center)
  • High distance → Anomaly (far from distribution center)

Parameters

contamination
float = 0.1
The proportion of outliers in the dataset. Must be in the range (0, 0.5]. Used to set the decision threshold.
support_fraction
float or None = None

Proportion of points to include in the support of the raw MCD estimate:

  • •None: Uses min(n_samples, n_features + 1) / 2
  • •float: Between 0 and 1, specifies the fraction of samples
random_state
int or None = None
Random seed for reproducibility. Set for consistent results when performing random sampling for robust estimation.

Attributes

location_
np.ndarray of shape (n_features,)
Estimated robust location (mean) of the Gaussian distribution.
covariance_
np.ndarray of shape (n_features, n_features)
Estimated robust covariance matrix.
precision_
np.ndarray of shape (n_features, n_features)
Inverse of the covariance matrix (precision matrix).
support_
np.ndarray of shape (n_support,)
Indices of samples used in the robust estimate.
threshold_
float
Mahalanobis distance threshold used for anomaly detection.
n_features_in_
int
Number of features observed during fit().

Notes

Complexity:

  • Training: O(n \cdot p^2) where n = samples, p = features
  • Prediction: O(p^2) per sample
When to use Elliptic Envelope:
  • Data follows a unimodal Gaussian (elliptical) distribution
  • Low-dimensional datasets where n > p
  • When robust statistics (mean and covariance) are needed
  • When you need a clear statistical threshold for anomalies
Limitations:
  • Highly sensitive to violations of the Gaussian assumption
  • Performance degrades in very high dimensions (p > n)
  • Computationally expensive for large numbers of features
  • Fails on multi-modal datasets (data with multiple clusters)

References

Rousseeuw1999
Rousseeuw, P.J. and Van Driessen, K. (1999). A fast algorithm for the minimum covariance determinant estimator. Technometrics, 41(3), pp. 212-223. DOI: 10.1080/00401706.1999.10485670

See Also

OneClassSVMDetector

Support vector based novelty/anomaly detection.
IsolationForestDetector

Tree-based ensemble anomaly detection.

Basic usage for anomaly detection:

python 
>>> from tuiml.algorithms.anomaly import EllipticEnvelopeDetector
>>> import numpy as np
>>> 
>>> # Create Gaussian distributed data with one outlier
>>> X = np.array([[1, 1], [1.1, 1.2], [0.9, 0.8], [1.2, 1.1], [10, 10]])
>>> 
>>> # Fit the model
>>> clf = EllipticEnvelopeDetector(contamination=0.2, random_state=42)
>>> clf.fit(X)
>>> 
>>> # Predict: -1 for anomalies, 1 for normal points
>>> predictions = clf.predict(X)
>>> print(predictions)
[ 1  1  1  1 -1]
>>> 
>>> # Get Mahalanobis distances
>>> distances = clf.mahalanobis(X)
>>> print(distances.round(2))
[ 1.35  1.21  1.67  1.84 14.28]

Methods

get_parameter_schema (cls) -> Dict[str, Dict[str, Any]]

Return JSON Schema for algorithm parameters.

get_capabilities (cls) -> List[str]

Return supported capabilities.

get_complexity (cls) -> str

Return complexity analysis.

get_references (cls) -> List[str]

Return academic citations.

fit (self, X: np.ndarray, y: Optional[np.ndarray]=None) -> 'EllipticEnvelopeDetector'

Fit the Elliptic Envelope model.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Training data.
y
np.ndarray or None = None
Ignored. Present for API consistency.
Returns
self
EllipticEnvelopeDetector
Fitted estimator.
decision_function (self, X: np.ndarray) -> np.ndarray

Compute anomaly scores for samples.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
Returns
scores
np.ndarray of shape (n_samples,)
Anomaly scores. Lower scores indicate anomalies.
predict (self, X: np.ndarray) -> np.ndarray

Predict if samples are anomalies or not.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
Returns
predictions
np.ndarray of shape (n_samples,)
-1 for anomalies, 1 for normal instances.
score_samples (self, X: np.ndarray) -> np.ndarray

Alias for decision_function for compatibility.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
Returns
scores
np.ndarray of shape (n_samples,)
Anomaly scores.
mahalanobis (self, X: np.ndarray) -> np.ndarray

Compute Mahalanobis distances.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
Returns
distances
np.ndarray of shape (n_samples,)
Mahalanobis distances.