Metadata-Version: 2.1
Name: radius-clustering
Version: 1.0.0
Summary: A Clustering under radius constraints algorithm using minimum dominating sets
Maintainer-email: Haenn Quentin <quentin.haenn@ensma.fr>
License: MIT License
        
        Copyright (c) 2024 Lias Laboratory
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT 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.
        
Keywords: Unsupervised learning,clustering,minimum dominating sets,clustering under radius constraint
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: C
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib >=3.6.2
Requires-Dist: numpy >=1.23
Requires-Dist: scikit-learn >=1.2.2
Requires-Dist: scipy >=1.12.0
Provides-Extra: dev
Requires-Dist: pytest >=8.3.3 ; extra == 'dev'
Requires-Dist: cython >=3.0 ; extra == 'dev'
Requires-Dist: setuptools >=61.0 ; extra == 'dev'
Requires-Dist: black >=24.3.0 ; extra == 'dev'
Requires-Dist: ruff >=0.4.8 ; extra == 'dev'
Requires-Dist: sphinx >=8.1.3 ; extra == 'dev'
Requires-Dist: sphinx-gallery >=0.18.0 ; extra == 'dev'
Requires-Dist: sphinx-copybutton >=0.5.2 ; extra == 'dev'
Requires-Dist: pydata-sphinx-theme >=0.15.3 ; extra == 'dev'
Requires-Dist: sphinxcontrib-email >=0.3.6 ; extra == 'dev'
Requires-Dist: sphinx-remove-toctrees >=1.0.0 ; extra == 'dev'
Requires-Dist: sphinx-prompt >=1.9.0 ; extra == 'dev'
Requires-Dist: sphinx-design >=0.6.1 ; extra == 'dev'
Provides-Extra: doc
Requires-Dist: sphinx >=8.1.3 ; extra == 'doc'
Requires-Dist: sphinx-gallery >=0.18.0 ; extra == 'doc'
Requires-Dist: sphinx-copybutton >=0.5.2 ; extra == 'doc'
Requires-Dist: pydata-sphinx-theme >=0.15.3 ; extra == 'doc'
Requires-Dist: sphinxcontrib-email >=0.3.6 ; extra == 'doc'
Requires-Dist: sphinx-remove-toctrees >=1.0.0 ; extra == 'doc'
Requires-Dist: sphinx-prompt >=1.9.0 ; extra == 'doc'
Requires-Dist: sphinx-design >=0.6.1 ; extra == 'doc'

# Radius Clustering

Radius clustering is a Python package that implements clustering under radius constraint based on the Minimum Dominating Set (MDS) problem. This problem is NP-Hard but has been studied in the literature and proven to be linked to the clustering under radius constraint problem (see [references](#references) for more details).

## Features

- Implements both exact and approximate MDS-based clustering algorithms
- Compatible with scikit-learn's API for clustering algorithms
- Supports radius-constrained clustering
- Provides options for exact and approximate solutions

## Installation

You can install Radius Clustering using pip:

```bash
pip install radius-clustering
```

> Note: This package is not yet available on PyPI. You may need to install it from the source.

## Usage

Here's a basic example of how to use Radius Clustering:

```python
import numpy as np
from radius_clustering import RadiusClustering

# Example usage
X = np.random.rand(100, 2)  # Generate random data

# Create an instance of MdsClustering
rad_clustering = RadiusClustering(manner="approx", threshold=0.5)

# Fit the model to the data
rad_clustering.fit(X)

# Get cluster labels
labels = rad_clustering.labels_

print(labels)
```

## Documentation

To build the documentation, you can run the following command, assuming you have Sphinx installed:

```bash
cd docs
make html
```

Then you can open the `index.html` file in the `build` directory to view the full documentation.

## More information

For more information please refer to the official documentation.

If you want insights on how the algorithm works, please refer to the [presentation](PRESENTATION.md).

If you want to know more about the experiments conducted with the package, please refer to the [experiments](EXPERIMENTS.md).


## Contributing

Contributions to MDS Clustering are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.


## Acknowledgments

### MDS Algorithms

The two MDS algorithms implemented are forked and modified (or rewritten) from the following authors:

- [Alejandra Casado](https://github.com/AlejandraCasado) for the minimum dominating set heuristic code [[1](https://www.sciencedirect.com/science/article/pii/S0378475422005055)]. We rewrote the code in C++ to adapt to the need of python interfacing.
- [Hua Jiang](https://github.com/huajiang-ynu) for the minimum dominating set exact algorithm code [[2](https://dl.acm.org/doi/abs/10.24963/ijcai.2023/622)]. The code has been adapted to the need of python interfacing.

### Funders

The Radius Clustering work has been funded by:

- [LIAS, ISAE-ENSMA](https://www.lias-lab.fr/)
- [LabCom @lienor](https://labcom-alienor.ensma.fr/) and the [French National Research Agency](https://anr.fr/)

### Contributors

- [Quentin Haenn (core developer)](https://www.lias-lab.fr/members/quentinhaenn/), LIAS, ISAE-ENSMA
- [Brice Chardin](https://www.lias-lab.fr/members/bricechardin/), LIAS, ISAE-ENSMA
- [Mickaël Baron](https://www.lias-lab.fr/members/mickaelbaron/), LIAS, ISAE-ENSMA


## References

- [1] [An iterated greedy algorithm for finding the minimum dominating set in graphs](https://www.sciencedirect.com/science/article/pii/S0378475422005055)
- [2] [An exact algorithm for the minimum dominating set problem](https://dl.acm.org/doi/abs/10.24963/ijcai.2023/622)


