Metadata-Version: 2.4
Name: fn-dbscan
Version: 0.2.0
Summary: Fuzzy Neighborhood DBSCAN clustering algorithm
Author: Onur Mert
License: MIT
Project-URL: Homepage, https://github.com/onurceldir123/fn-dbscan
Project-URL: Repository, https://github.com/onurceldir123/fn-dbscan
Project-URL: Issues, https://github.com/onurceldir123/fn-dbscan/issues
Keywords: clustering,dbscan,fuzzy,machine-learning,scikit-learn
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: <4.0,>=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0.0,>=1.19.0
Requires-Dist: scikit-learn<2.0.0,>=1.0.0
Requires-Dist: scipy<2.0.0,>=1.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5.0; extra == "viz"
Dynamic: license-file

# FN-DBSCAN: Fuzzy Neighborhood DBSCAN

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17726044.svg)](https://doi.org/10.5281/zenodo.17726044)

Implementation of **Fuzzy Neighborhood DBSCAN (FN-DBSCAN)**, a density-based clustering algorithm that extends classic DBSCAN using fuzzy theory.

## Installation

```bash
pip install fn-dbscan
```

For development:
```bash
git clone https://github.com/onurceldir123/fn-dbscan.git
cd fn-dbscan
pip install -e .
```

**Requirements:** Python ≥3.8, NumPy, scikit-learn, scipy

## Quick Start

```python
from sklearn.datasets import make_moons
from fn_dbscan import FN_DBSCAN

X, _ = make_moons(n_samples=200, noise=0.05, random_state=42)

model = FN_DBSCAN(
    eps=0.1,
    min_fuzzy_neighbors=5.0,
    min_membership=0.0,
    fuzzy_function='exponential',
    normalize=False
)

labels = model.fit_predict(X)

print(f"Found {model.n_clusters_} clusters")
```

## Why FN-DBSCAN?

While classic DBSCAN is powerful, it relies on a "crisp" boundary—a point is either a neighbor or it isn't. FN-DBSCAN improves upon this by introducing fuzzy set theory:

* **Robustness to Density Variations:** It is more robust than DBSCAN when handling datasets with varying densities and shapes.
* **Soft Boundaries:** Instead of an all-or-nothing approach, it calculates a "fuzzy cardinality" (sum of membership degrees). This handles border points and noise more naturally.
* **Scale Adaptability:** The implementation includes an optional normalization technique (set `normalize=True`) to make the `eps` parameter adaptable to the data scale.
* **Best of Both Worlds:** Combines the speed of DBSCAN with the robustness of fuzzy clustering methods like NRFJP.

## Parameters

### Core Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `eps` | float | 0.1 | Maximum neighborhood radius (0-1 when normalize=True). |
| `min_fuzzy_neighbors` | float | 5.0 | Minimum fuzzy cardinality to be a core point (analogous to `min_samples` in DBSCAN). |
| `min_membership` | float | 0.0 | Minimum membership threshold ($\epsilon_1$). Points with membership below this are ignored. |
| `fuzzy_function` | str | 'linear' | Membership function: `'linear'`, `'exponential'`, or `'trapezoidal'`. |
| `normalize` | bool | False | Normalize data to make `eps` scale-independent. |
| `k` | float | None | **Steepness parameter.** Controls how fast membership drops. Higher `k` implies a stricter neighborhood. Auto-calculated as `d_max / eps` if None. |
| `metric` | str | 'euclidean' | Distance metric (any scikit-learn compatible metric). |

### Fuzzy Functions

- **`'exponential'`** - Recommended for most cases, especially non-convex clusters
- **`'linear'`** - Simple linear decay, good for well-separated clusters
- **`'trapezoidal'`** - Maintains full membership for very close points


## Model Attributes

After fitting, the model provides:

- **`labels_`** - Cluster labels for each sample (-1 for noise)
- **`core_sample_indices_`** - Indices of core points
- **`n_clusters_`** - Number of clusters found

## Algorithm Overview

FN-DBSCAN extends DBSCAN by computing fuzzy cardinality instead of discrete point counts:

```
Traditional DBSCAN:  cardinality = count(neighbors)
FN-DBSCAN:          cardinality = Σ membership(distance(p, q))
```

A point is a **core point** if its fuzzy cardinality ≥ `min_fuzzy_neighbors`.

## Citation

If you use `fn-dbscan` in your research, please consider citing the original paper along with this software implementation to ensure reproducibility:

**1. Original Algorithm:**

```bibtex
@article{nasibov2009robustness,
  title={Robustness of density-based clustering methods with various neighborhood relations},
  author={Nasibov, Efendi N and Ulutagay, G{\"o}zde},
  journal={Fuzzy Sets and Systems},
  volume={160},
  number={24},
  pages={3601--3615},
  year={2009},
  publisher={Elsevier}
}
```

**2. Software Implementation:**

```bibtex
@software{celdir2025fndbscan,
  author       = {Çeldir, Onur Mert},
  title        = {FN-DBSCAN: Python Implementation of Fuzzy Neighborhood DBSCAN},
  year         = 2025,
  publisher    = {Zenodo},
  version      = {v1.0.1},
  doi          = {10.5281/zenodo.17726044},
  url          = {[https://github.com/onurceldir123/fn-dbscan](https://github.com/onurceldir123/fn-dbscan)}
}
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/onurceldir123/fn-dbscan).

---

**Reference:** Nasibov, E. N., & Ulutagay, G. (2009). Robustness of density-based clustering methods with various neighborhood relations. *Fuzzy Sets and Systems*, 160(24), 3601-3615.
