MDOD - Multi-Dimensional Outlier Detection

MDOD is a Python library for outlier detection in multi-dimensional data using vector cosine similarity with an added virtual dimension.

• v3.0.6.2 (High-Performance & Large-Scale) Features: Fully backward compatible. Supports >500k samples without OOM (batch + float32 + incremental). Preserves high AUC by only down-sampling when absolutely necessary. MemoryError auto-fallback (rarely triggered).

• The code implementation was developed with significant optimization assistance from Grok (xAI).

This software is licensed under the BSD 3-Clause License.

Disclaimer
This library is provided "AS IS", WITHOUT ANY WARRANTY of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.

Users are strongly advised to thoroughly test and validate the library for their specific use case, especially in production environments or critical applications.

Installation

pip install mdod

Quick Start

from mdod import MDOD
import numpy as np

# Example data (replace with your own dataset)
X = np.random.randn(1000, 10)  # 1000 samples, 10 features

model = MDOD(
    norm_distance=1.0,
    top_n=5,
    contamination=0.1,
    sampling_rate=0.1,  # Use lower values for faster computation on large data
    random_state=42
)
model.fit(X)

# Predict outliers
labels = model.predict()                  # 1 = outlier, 0 = normal
scores = model.decision_function(X)       # indicate outlier probability

Parameters

• norm_distance: Distance of the virtual dimension (default: 1.0) — affects similarity sensitivity.
• top_n: Number of top similar points to consider (default: 5).
• contamination: Expected proportion of outliers (default: 0.1) — used for threshold.
• sampling_rate: Sampling ratio (0–1, default: 1.0) — lower values speed up computation.
• random_state: Random seed for reproducibility.

Performance

On standard test datasets, MDOD consistently achieves perfect or near-perfect detection (AUC ≈ 1.0) while being significantly faster than scikit-learn's Local Outlier Factor (LOF). Example Performance (Synthetic Dataset: 1000 samples, 2D, 150 outliers, sampling_rate=0.05)

• MDOD AUC: 1.0
• MDOD Runtime: ~0.009 seconds (significantly faster than LOF)
• Spearman correlation with LOF scores: 0.9192

Examples

More detailed examples and test scripts are included in the examples/ directory of the installed package.

License

See the full BSD 3-Clause License in the LICENSE file.