pyEllipse

Hotelling’s T-squared statistic and confidence ellipses for multivariate data

pyEllipse computes Hotelling’s T-squared statistic, its control limits, and the confidence ellipses and ellipsoids drawn from them, for outlier detection and score plots of PCA, PLS and other multivariate models. Its Hotelling functions are the Python counterpart of the HotellingEllipse R package and give the same results (see Validation).

Function	Purpose
hotelling_parameters	T-squared of each observation, cutoffs, and the semi-axes and rotation of the ellipse
hotelling_coordinates	Points of the T-squared ellipse (2D) or ellipsoid (3D), for plotting
confidence_ellipse	Confidence ellipses and ellipsoids of raw data, optionally by group and with robust estimates

The Theory page gives the formulas behind each function and states when each limit is exact.

Installation

pip install pyEllipse

Quick start

Compute T-squared on the first two principal components of the wine data, and flag the samples above the 99% limit:

import numpy as np
from sklearn.datasets import load_wine
from sklearn.decomposition import PCA
from sklearn.preprocessing import StandardScaler

from pyEllipse import hotelling_coordinates, hotelling_parameters

X = StandardScaler().fit_transform(load_wine().data)
scores = PCA().fit_transform(X)

res = hotelling_parameters(scores, pcx=1, pcy=2, method="beta")
t2 = res["Tsquared"]["value"]
print(f"99% limit: {res['cutoff_99pct']:.2f}")
print("Samples above it:", np.flatnonzero(t2 > res["cutoff_99pct"]).tolist())

99% limit: 9.02
Samples above it: []

hotelling_coordinates(scores, pcx=1, pcy=2, conf_limit=0.99, method="beta") returns the points of the matching ellipse, for plotting. The PCA example goes through a complete analysis.

Validation

The test suite runs on every change, on Python 3.9 to 3.14. For hotelling_parameters and hotelling_coordinates, it checks the formulas of the Theory page directly (T-squared against the squared Mahalanobis distance, the ellipse points against the limit, the semi-axes and rotation against the ellipse points), checks that about 5% of simulated observations exceed the 95% Beta limit, and compares both functions with the HotellingEllipse 1.3.0 R package on a reference data set, to within a relative \(10^{-10}\). The examples in the reference pages are run as tests too; for confidence_ellipse, this example is so far the only test.

How to cite

@software{goueguel_pyellipse,
  author  = {Goueguel, Christian L.},
  title   = {{pyEllipse: Statistical confidence ellipses and Hotelling's T-squared ellipses}},
  version = {0.2.1},
  url     = {https://github.com/ChristianGoueguel/pyEllipse},
  license = {MIT}
}

Please cite the version you used, as shown in the footer of this page.