Metadata-Version: 2.4
Name: pt_loop
Version: 0.1.0
Summary: Local Outlier Probabilities (LoOP) implementation in PyTorch
Author: Ofer Hasson
License-Expression: Apache-2.0
Project-URL: Homepage, https://gitlab.com/hassonofer/pt_loop
Project-URL: Issues, https://gitlab.com/hassonofer/pt_loop/-/issues
Keywords: pytorch,loop,outlier-detection,anomaly-detection,machine-learning,unsupervised-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.4.0
Dynamic: license-file

# PyTorch LoOP

## Introduction

`pt_loop` is a pure PyTorch implementation of the Local Outlier Probabilities (LoOP) algorithm, designed for seamless integration into PyTorch-based machine learning pipelines.
It offers high performance on both CPU and GPU (CUDA), leveraging PyTorch's tensor capabilities throughout the entire computation.

Unlike traditional implementations that might require data transfers to other libraries, `pt_loop` keeps your data on the PyTorch device (CPU or GPU) from start to finish, minimizing overhead and maximizing efficiency for large-scale anomaly detection tasks.

The original paper can be found here: <https://www.dbs.ifi.lmu.de/Publikationen/Papers/LoOP1649.pdf>

## Installation

`pt_loop` requires PyTorch.

First, ensure you have PyTorch installed (refer to the [official PyTorch website](https://pytorch.org/get-started/locally/) for installation instructions specific to your system and CUDA version).

Then, install `pt_loop` directly from PyPI:

```bash
pip install pt_loop
```

## Quick Start & Usage Examples

Here's how to get started with `pt_loop`.

```python
import torch
import matplotlib.pyplot as plt

from pt_loop import loop
```

### Basic LoOP Usage

```python
# 1. Generate some synthetic data with an obvious outlier
data = torch.cat([
    torch.randn(100, 2) * 0.5 + torch.tensor([0.0, 0.0]), # Cluster 1
    torch.randn(100, 2) * 0.5 + torch.tensor([5.0, 5.0]), # Cluster 2
    torch.tensor([[2.5, 2.5]]),                           # Clear outlier
])

# Move data to GPU if available
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
data = data.to(device)

# 2. Run LoOP
print(f"Running LoOP on {device}...")
loop_scores = loop(
    data,
    k=10,                      # Number of nearest neighbors
    lambda_=3.0,               # Scaling factor
    distance_metric="l2",      # or "cosine"
)

print("\nLoOP Results:")
print(f"Scores Shape: {loop_scores.shape}")
print(f"First 5 Scores: {loop_scores[:5].tolist()}")
print(f"Last score (outlier candidate): {loop_scores[-1].item()}")

# 3. (Optional) Visualize the scores
plt.figure(figsize=(8, 6))
scatter = plt.scatter(data[:, 0].cpu(), data[:, 1].cpu(), c=loop_scores.cpu(), cmap="plasma", s=50, alpha=0.8)
plt.colorbar(scatter, label="LoOP Score (Outlier Probability)")
plt.title("Local Outlier Probabilities (LoOP)")
plt.xlabel("Feature 1")
plt.ylabel("Feature 2")
plt.grid(True)
plt.show()
```

## Contributing

Contributions are very welcome! If you find a bug, have a feature request, or want to contribute code, please feel free to:

1. Open an issue on the [GitLab Issues page](https://gitlab.com/hassonofer/pt_loop/-/issues).
1. Submit a Pull Request.

Please ensure your code adheres to the existing style (Black, isort) and passes all tests.

## License

This project is licensed under the Apache-2.0 License - see the [LICENSE](https://gitlab.com/hassonofer/pt_loop/blob/main/LICENSE) file for details.
