Skip to main content

Ensemble Outlier Sample Detection

python_badge license_badge Total_Downloads_badge

Ensemble-based outlier sample detection for regression data.

EnsembleOutlierSampleDetector flags the samples whose target values do not agree with an ensemble of PLS or SVR models fitted on bootstrap samples, following the method of Kaneko (see Reference below).

This README describes version 1.0.0. Version 1.0.0 has breaking changes from 0.x; see Upgrading from 0.x below.

Installation

pip install ensemble-outlier-sample-detection
  • Python 3.10 or later is required. The package is tested on Python 3.10 to 3.14.
  • The runtime dependencies are NumPy (>= 1.23), scikit-learn (>= 1.6), Optuna (>= 3.0) and tqdm (>= 4.40). pip installs them automatically.
  • pandas is optional. You need it only to pass pandas DataFrames or Series, or to run the example notebook.

Usage

import numpy as np

from ensemble_outlier_sample_detection import EnsembleOutlierSampleDetector

rng = np.random.RandomState(0)
X = rng.normal(size=(100, 5))
y = X @ rng.normal(size=5) + 0.1 * rng.normal(size=100)
y[:3] += 10.0  # make the first three samples outliers

elo = EnsembleOutlierSampleDetector(random_state=334, n_jobs=-1).fit(X, y)
elo.outlier_support_  # boolean ndarray of shape (n_samples,), True = outlier
elo.inlier_support_  # boolean ndarray, the complement of outlier_support_
elo.n_iter_  # number of iterations that fit ran
print(np.flatnonzero(elo.outlier_support_))  # indices of the outliers

fit returns the detector itself, so the call can be chained. X can be a NumPy array or a pandas DataFrame, and y is a 1-D numeric target. To use the result, select the inliers with X[elo.inlier_support_] (or df[elo.inlier_support_] for a DataFrame).

Parameters

Parameter Default Description
method "pls" Submodel: "pls" (PLS regression) or "svr" (SVR with an RBF kernel). "PLS" and "SVR" are also accepted.
metric "r2" Score of the out-of-fold predictions that tunes each submodel: "r2" (maximized), "mse", "mae" or "rmse" (minimized).
n_estimators 100 Number of submodels in each iteration.
max_iter 30 Maximum number of iterations.
cv 5 Number of cross-validation folds for the out-of-fold predictions.
max_components 30 Maximum number of PLS components. Must be a positive integer. It is validated but otherwise ignored for SVR.
n_jobs 1 Number of jobs for the cross-validation. -1 uses all processors.
random_state None Seed of the bootstraps and the Optuna samplers. Pass an int for reproducible results.
progress_bar True Whether to show a progress bar during fit (a widget in Jupyter, text elsewhere).

fit raises ValueError for an unsupported method or metric, for max_iter, n_estimators or max_components that is not a positive integer, and for invalid inputs (missing y, mismatched lengths, NaN or infinity).

Fitted attributes

Attribute Description
outlier_support_ Boolean mask of shape (n_samples,), True for an outlier. Also returned by get_outlier_support().
inlier_support_ Boolean mask of shape (n_samples,), ~outlier_support_. Also returned by get_inlier_support().
n_iter_ Number of iterations run, between 1 and max_iter.
n_features_in_ Number of features seen during fit.
feature_names_in_ Column names of X. Set only when X has column names that are all strings, such as a DataFrame.

If the outlier mask still changes after max_iter iterations, fit emits a sklearn.exceptions.ConvergenceWarning, and the attributes hold the judgment of the last iteration.

How it works

Each iteration of fit runs these steps.

  1. Take the samples that the previous iteration judged as inliers (all samples in the first iteration).
  2. Fit n_estimators submodels, each on a bootstrap sample of those samples, after dropping constant features and standardizing X and y. The hyperparameters of each submodel (n_components for PLS; C, epsilon and gamma for SVR) are tuned with the TPE sampler of Optuna, which optimizes metric on the out-of-fold predictions of cv-fold cross-validation. The tuned submodel then predicts every sample.
  3. Take the median of the ensemble predictions of each sample. A sample is an outlier when |y - median| > 3 * 1.4826 * MAD, a robust counterpart of the 3-sigma rule, where the MAD is computed from the ensemble predictions of the previous inliers.

The iterations stop when the outlier mask is the same as in the previous iteration, or when every sample is an outlier. Optuna's per-trial logs are hidden during fit, and Optuna's logging configuration is restored afterwards. See help(EnsembleOutlierSampleDetector) for the details.

Example

The example notebook runs the detector on the bundled example data. It also needs pandas, matplotlib and seaborn, which the example extra installs:

pip install "ensemble-outlier-sample-detection[example]"

Upgrading from 0.x

Version 1.0.0 changes the API in a few incompatible ways: fit returns the detector, n_iter_ is the number of iterations (the old n_iter_finished is gone), unsupported values raise ValueError, Python 3.9 and earlier are no longer supported, and results with metric="r2" can differ. See the CHANGELOG for the full list and migration examples.

Reference

Paper

Sites

LICENSE

Copyright © 2021 yu9824

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.

Metadata

Release files for ensemble-outlier-sample-detection 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ensemble-outlier-sample-detection 1.0.0
File Size Uploaded Provenance Actions
ensemble_outlier_sample_detection-1.0.0.tar.gz 85.2 kB With provenance Details for ensemble_outlier_sample_detection-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ensemble-outlier-sample-detection 1.0.0
File Interpreter ABI Platform Actions
ensemble_outlier_sample_detection-1.0.0-py3-none-any.whl Python 3 none any Details for ensemble_outlier_sample_detection-1.0.0-py3-none-any.whl

Total release size: 104.7 kB

Release files / ensemble_outlier_sample_detection-1.0.0.tar.gz

Download URL ensemble_outlier_sample_detection-1.0.0.tar.gz
Size 85.2 kB
Tags Source
SHA-256 checksum
How to use checksums
8f1b0d5101445b547fb1071c7385640f1bb63822ab97de0e57993230143e8f78
BLAKE2b-256 checksum
How to use checksums
0018f9d44afed85f1e1f33a7119366ea85fd21e015c46f114a8b7320830f4b08
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / ensemble_outlier_sample_detection-1.0.0-py3-none-any.whl

Download URL ensemble_outlier_sample_detection-1.0.0-py3-none-any.whl
Size 19.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5a06162f66d9c701b6791ea832f3f0e301d8f77e68907f88bbe3a447131e15f5
BLAKE2b-256 checksum
How to use checksums
5b4237dbfe734665155f15be8ce9f4bf9bf679ad719f6c41a13867180cf8308e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Security for ensemble-outlier-sample-detection 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ensemble_outlier_sample_detection-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page