Metadata-Version: 2.4
Name: labelfree
Version: 1.0.0
Summary: Label-free metrics for unsupervised anomaly detector evaluation
Project-URL: Documentation, https://oliverhennhoefer.github.io/label-free/
Project-URL: Issues, https://github.com/OliverHennhoefer/label-free/issues
Project-URL: Repository, https://github.com/OliverHennhoefer/label-free
Author-email: Oliver Hennhoefer <oliver.hennhoefer@mail.de>
License-Expression: MIT
License-File: LICENSE
Keywords: anomaly-detection,model-selection,unsupervised-learning
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: numpy>=1.24
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.10
Provides-Extra: dev
Requires-Dist: pre-commit>=4.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Provides-Extra: docs
Requires-Dist: zensical==0.0.47; extra == 'docs'
Provides-Extra: examples
Requires-Dist: numba>=0.66; extra == 'examples'
Requires-Dist: oddball>=1.4; extra == 'examples'
Requires-Dist: optuna>=4; extra == 'examples'
Requires-Dist: pandas>=2.2; extra == 'examples'
Requires-Dist: pyod>=1.1; extra == 'examples'
Description-Content-Type: text/markdown

# labelfree

[![Tests](https://github.com/OliverHennhoefer/label-free/actions/workflows/tests.yml/badge.svg)](https://github.com/OliverHennhoefer/label-free/actions/workflows/tests.yml)
[![Documentation](https://github.com/OliverHennhoefer/label-free/actions/workflows/docs.yml/badge.svg)](https://oliverhennhoefer.github.io/label-free/)
[![PyPI](https://img.shields.io/pypi/v/labelfree.svg)](https://pypi.org/project/labelfree/)

Label-free metrics for comparing unsupervised anomaly detectors and
hyperparameters when labeled anomalies are unavailable.

## Install

```bash
pip install labelfree
```

## Quick start

```python
from labelfree.metrics import score_cluster_metrics

scores = [0.1, 0.2, 0.3, 3.8, 4.1]
metrics = score_cluster_metrics(scores, n_outliers=2)
print(metrics["silhouette"])  # higher is better
```

The package includes score-cluster, ASI/ASOI, AutoUAD, Laplacian,
consensus, ranking-stability, IREOS, SIREOS, and Excess-Mass/Mass-Volume metrics.
Every raw-score API requires an explicit score polarity when larger values
mean more normal.

Label-free metrics are model-selection signals, not substitutes for labeled
evaluation. Check each metric's assumptions and direction before comparing
results.

See the [documentation](https://oliverhennhoefer.github.io/label-free/) for
metric selection, API details, and examples.

## Development

```bash
python -m pip install -e ".[dev]"
pytest
```

Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Released
under the [MIT License](LICENSE).
