fair-kmeans 0.1.0__tar.gz

fair_kmeans-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Algorithms and Data Structures Group of the Heinrich Heine University Düsseldorf
+
+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.

fair_kmeans-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.1
+Name: fair-kmeans
+Version: 0.1.0
+Summary: Fair K-Means produces a fair clustering assignment according to the fairness definition of Chierichetti et al. Each point has a binary color, and the goal is to assign the points to clusters such that the number of points with different colors in each cluster is the same and the cost of the clusters is minimized.
+License: LICENSE
+Author: Melanie Schmidt
+Author-email: mschmidt@hhu.de
+Requires-Python: >=3.9,<4.0
+Classifier: License :: Other/Proprietary License
+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
+Requires-Dist: numpy (>=1.26.4,<2.0.0)
+Requires-Dist: scikit-learn (>=1.4.2,<2.0.0)
+Description-Content-Type: text/markdown
+
+[![Build Status](https://github.com/algo-hhu/fair-kmeans/actions/workflows/mypy-flake-test.yml/badge.svg)](https://github.com/algo-hhu/fair-kmeans/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Supported Python version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/release/python-390/)
+[![Stable Version](https://img.shields.io/pypi/v/fair-kmeans?label=stable)](https://pypi.org/project/fair-kmeans/)
+
+# Fair K-Means
+
+Fair K-Means produces a fair clustering assignment according to the fairness definition of Chierichetti et al. [1]. Each point has a binary color assigned to it. The goal is to assign the points to clusters such that the number of points with different colors in each cluster is the same. The algorithm also works with weights, so each point can participate with a different weight in the coloring.
+
+The algorithm works as follows, assuming that the binary colors are red and blue:
+1. A matching between the red and blue points is computed such that the cost (the point distances) of the matching is minimized.
+2. The mean of each matched pair is computed.
+3. A K-Means++ clustering of all the means is computed, and the point pairs are assigned to the clusters of their means.
+
+The matching between the red and blue points is computed using the [Lemon C++ Library](https://lemon.cs.elte.hu/trac/lemon). The library is included in the package and does not need to be installed separately. Only the needed files were included, and a complete version of the library can be found [here](https://lemon.cs.elte.hu/trac/lemon). A copyright notice is included [here](fair_kmeans/lemon/LICENSE).
+
+### References
+
+[1] Flavio Chierichetti, Ravi Kumar, Silvio Lattanzi, and Sergei Vassilvitskii, Fair clustering through fairlets, Proceedings of the 30th Annual Conference on Neural Information Processing Systems (NIPS), 2017, pp. 5036–5044.
+
+## Installation
+
+```bash
+pip install fair-kmeans
+```
+
+## Example
+
+```python
+from fair_kmeans import FairKMeans
+
+example_data = [
+    [1.0, 1.0, 1.0],
+    [1.1, 1.1, 1.1],
+    [1.2, 1.2, 1.2],
+    [2.0, 2.0, 2.0],
+    [2.1, 2.1, 2.1],
+    [2.2, 2.2, 2.2],
+]
+
+example_colors = [1, 1, 1, 0, 0, 0]
+
+km = FairKMeans(n_clusters=2, random_state=0)
+km.fit(example_data, color=example_colors)
+labels = km.labels_
+centers = km.cluster_centers_
+
+print(labels) # [1, 0, 0, 1, 0, 0]
+print(centers) # [[1.65, 1.65, 1.65], [1.5, 1.5, 1.5]]
+```
+
+## Example with Weights
+
+```python
+from fair_kmeans import FairKMeans
+
+example_data = [
+    [1.0, 1.0, 1.0],
+    [1.1, 1.1, 1.1],
+    [1.2, 1.2, 1.2],
+    [2.0, 2.0, 2.0],
+    [2.1, 2.1, 2.1],
+    [2.2, 2.2, 2.2],
+]
+
+example_colors = [1, 1, 1, 0, 0, 0]
+example_weights = [2, 2, 1, 1, 1, 3]
+
+km = FairKMeans(n_clusters=2, random_state=0)
+km.fit(example_data, color=example_colors, sample_weight=example_weights)
+labels = km.labels_
+centers = km.cluster_centers_
+
+print(labels) # [1, 1, 0, 1, 1, 0]
+print(centers) # [[0.85, 0.85, 0.85], [1.28, 1.28, 1.28]]
+```
+
+## Development
+
+Install [poetry](https://python-poetry.org/docs/#installation)
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+Install clang
+```bash
+sudo apt-get install clang
+```
+
+Set clang variables
+```bash
+export CXX=/usr/bin/clang++
+export CC=/usr/bin/clang
+```
+
+Install the package
+```bash
+poetry install
+```
+
+If the installation does not work and you do not see the C++ output, you can build the package to see the stack trace
+```bash
+poetry build
+```
+
+Run the tests
+```bash
+poetry run python -m unittest discover tests -v
+```
+
+## Citation
+
+If you use this code, please cite [the following paper](https://arxiv.org/abs/2406.02739v1):
+
+```
+Melanie Schmidt, Chris Schwiegelshohn and Christian Sohler.
+"Fair Coresets and Streaming Algorithms for Fair k-Means Clustering" (2020).
+Approximation and Online Algorithms. WAOA 2019.
+Lecture Notes in Computer Science, vol 11926. Springer.
+```
+

fair_kmeans-0.1.0/README.md

@@ -0,0 +1,120 @@
+[![Build Status](https://github.com/algo-hhu/fair-kmeans/actions/workflows/mypy-flake-test.yml/badge.svg)](https://github.com/algo-hhu/fair-kmeans/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Supported Python version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/release/python-390/)
+[![Stable Version](https://img.shields.io/pypi/v/fair-kmeans?label=stable)](https://pypi.org/project/fair-kmeans/)
+
+# Fair K-Means
+
+Fair K-Means produces a fair clustering assignment according to the fairness definition of Chierichetti et al. [1]. Each point has a binary color assigned to it. The goal is to assign the points to clusters such that the number of points with different colors in each cluster is the same. The algorithm also works with weights, so each point can participate with a different weight in the coloring.
+
+The algorithm works as follows, assuming that the binary colors are red and blue:
+1. A matching between the red and blue points is computed such that the cost (the point distances) of the matching is minimized.
+2. The mean of each matched pair is computed.
+3. A K-Means++ clustering of all the means is computed, and the point pairs are assigned to the clusters of their means.
+
+The matching between the red and blue points is computed using the [Lemon C++ Library](https://lemon.cs.elte.hu/trac/lemon). The library is included in the package and does not need to be installed separately. Only the needed files were included, and a complete version of the library can be found [here](https://lemon.cs.elte.hu/trac/lemon). A copyright notice is included [here](fair_kmeans/lemon/LICENSE).
+
+### References
+
+[1] Flavio Chierichetti, Ravi Kumar, Silvio Lattanzi, and Sergei Vassilvitskii, Fair clustering through fairlets, Proceedings of the 30th Annual Conference on Neural Information Processing Systems (NIPS), 2017, pp. 5036–5044.
+
+## Installation
+
+```bash
+pip install fair-kmeans
+```
+
+## Example
+
+```python
+from fair_kmeans import FairKMeans
+
+example_data = [
+    [1.0, 1.0, 1.0],
+    [1.1, 1.1, 1.1],
+    [1.2, 1.2, 1.2],
+    [2.0, 2.0, 2.0],
+    [2.1, 2.1, 2.1],
+    [2.2, 2.2, 2.2],
+]
+
+example_colors = [1, 1, 1, 0, 0, 0]
+
+km = FairKMeans(n_clusters=2, random_state=0)
+km.fit(example_data, color=example_colors)
+labels = km.labels_
+centers = km.cluster_centers_
+
+print(labels) # [1, 0, 0, 1, 0, 0]
+print(centers) # [[1.65, 1.65, 1.65], [1.5, 1.5, 1.5]]
+```
+
+## Example with Weights
+
+```python
+from fair_kmeans import FairKMeans
+
+example_data = [
+    [1.0, 1.0, 1.0],
+    [1.1, 1.1, 1.1],
+    [1.2, 1.2, 1.2],
+    [2.0, 2.0, 2.0],
+    [2.1, 2.1, 2.1],
+    [2.2, 2.2, 2.2],
+]
+
+example_colors = [1, 1, 1, 0, 0, 0]
+example_weights = [2, 2, 1, 1, 1, 3]
+
+km = FairKMeans(n_clusters=2, random_state=0)
+km.fit(example_data, color=example_colors, sample_weight=example_weights)
+labels = km.labels_
+centers = km.cluster_centers_
+
+print(labels) # [1, 1, 0, 1, 1, 0]
+print(centers) # [[0.85, 0.85, 0.85], [1.28, 1.28, 1.28]]
+```
+
+## Development
+
+Install [poetry](https://python-poetry.org/docs/#installation)
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+Install clang
+```bash
+sudo apt-get install clang
+```
+
+Set clang variables
+```bash
+export CXX=/usr/bin/clang++
+export CC=/usr/bin/clang
+```
+
+Install the package
+```bash
+poetry install
+```
+
+If the installation does not work and you do not see the C++ output, you can build the package to see the stack trace
+```bash
+poetry build
+```
+
+Run the tests
+```bash
+poetry run python -m unittest discover tests -v
+```
+
+## Citation
+
+If you use this code, please cite [the following paper](https://arxiv.org/abs/2406.02739v1):
+
+```
+Melanie Schmidt, Chris Schwiegelshohn and Christian Sohler.
+"Fair Coresets and Streaming Algorithms for Fair k-Means Clustering" (2020).
+Approximation and Online Algorithms. WAOA 2019.
+Lecture Notes in Computer Science, vol 11926. Springer.
+```

fair_kmeans-0.1.0/build_extension.py

@@ -0,0 +1,44 @@
+from typing import Any, Dict
+
+from setuptools import Extension
+from setuptools.command.build_ext import build_ext
+from setuptools.errors import CompileError
+
+extension = Extension(
+    name="fair_kmeans._core",
+    sources=[
+        "fair_kmeans/_core.cpp",
+        "fair_kmeans/fair_clustering_tools.cpp",
+        "fair_kmeans/point.cpp",
+    ],
+    include_dirs=["fair_kmeans"],
+)
+
+# Thank you https://github.com/dstein64/kmeans1d!
+
+
+class BuildExt(build_ext):
+    """A custom build extension for adding -stdlib arguments for clang++."""
+
+    def build_extensions(self) -> None:
+        # '-std=c++11' is added to `extra_compile_args` so the code can compile
+        # with clang++. This works across compilers (ignored by MSVC).
+        for extension in self.extensions:
+            extension.extra_compile_args.append("-std=c++11")
+
+        try:
+            build_ext.build_extensions(self)
+        except CompileError:
+            # Workaround Issue #2.
+            # '-stdlib=libc++' is added to `extra_compile_args` and `extra_link_args`
+            # so the code can compile on macOS with Anaconda.
+            for extension in self.extensions:
+                extension.extra_compile_args.append("-stdlib=libc++")
+                extension.extra_link_args.append("-stdlib=libc++")
+            build_ext.build_extensions(self)
+
+
+def build(setup_kwargs: Dict[str, Any]) -> None:
+    setup_kwargs.update(
+        {"ext_modules": [extension], "cmdclass": {"build_ext": BuildExt}}
+    )

fair_kmeans-0.1.0/fair_kmeans/__init__.py

@@ -0,0 +1,3 @@
+from fair_kmeans.core import FairKMeans
+
+__all__ = ["FairKMeans"]

fair_kmeans-0.1.0/fair_kmeans/_core.cpp

@@ -0,0 +1,218 @@
+#include <Python.h>
+#include <iostream>
+#include <cstdint>
+
+#include "fair_clustering_tools.h"
+
+typedef unsigned int uint;
+
+
+
+bool checkWeightValidity(std::vector<int> &weightsum)
+{
+    int first_sum = weightsum[0];
+
+    for (size_t i = 1; i < weightsum.size(); ++i)
+    {
+        if (weightsum[i] != first_sum)
+        {
+            std::cout << "Total weight sum of color 0 is " << first_sum << ", but weight sum of color " << i << " is " << weightsum[1] << ". All weights must be the same." << std::endl;
+            return false;
+        }
+    }
+    return true;
+}
+
+// Splits points into weight, color and coordinates.
+// Processes the data into a n-color-dim array points,
+// where each index is one color.
+// Number and weightsum give the number
+// and total weight of points in either array.
+void postprocessData(double *array, double *sampleWeights, int *colors, uint n, uint d, std::vector<std::vector<Point>> &points, std::vector<int> &number, std::vector<int> &weightsum)
+{
+    int j = 0;
+    for (uint i = 0; i < n * d; i += d)
+    {
+        double w = sampleWeights[j];
+        int c = colors[j];
+        number[c] += 1;
+        weightsum[c] += w;
+        std::vector<double> coords(&array[i], &array[i] + d);
+        // Add j as the position of the point in the array
+        points[c].push_back(Point(w, c, j, coords));
+        j++;
+    }
+}
+
+// Convert the array of centers to a vector of points
+// Postprocess the center data into a vector of Point objects
+// centers have weight 1 and no color (-1).
+void postprocessCenters(double *centers, std::vector<Point> &centersVector, uint k, uint d)
+{
+    // Create center vector with points objects by copying from centerdata
+    int j = 0;
+    for (uint i = 0; i < k * d; i += d)
+    {
+        std::vector<double> coords(&centers[i], &centers[i] + d);
+        // Centers have weight 1 and no color (-1)
+        centersVector[j] = Point(1, -1, coords);
+        j++;
+    }
+}
+
+// Copy the centers back to the centers array to return to Python
+void copyBackCenters(double *centers, std::vector<Point> &centersVector)
+{
+    for (size_t i = 0; i < centersVector.size(); ++i)
+    {
+        size_t d = centersVector[i].getDimension();
+        for (size_t j = 0; j < d; ++j)
+        {
+            centers[i * d + j] = centersVector[i].getCoordinatePointer()[j];
+        }
+    }
+}
+
+void assignLabels(std::vector<std::vector<Point>> &points, int *labels)
+{
+    for (size_t c = 0; c < points.size(); ++c)
+    {
+        for (size_t j = 0; j < points[c].size(); ++j)
+        {
+            labels[points[c][j].getPosition()] = points[c][j].getLabel();
+        }
+    }
+}
+
+
+// Thank you https://github.com/dstein64/kmeans1d!
+
+extern "C"
+{
+// "__declspec(dllexport)" causes the function to be exported when compiling on Windows.
+// Otherwise, the function is not exported and the code raises
+//   "AttributeError: function 'cluster' not found".
+// Exporting is a Windows platform requirement, not just a Visual Studio requirement
+// (https://stackoverflow.com/a/22288874/1509433). The _WIN32 macro covers the Visual
+// Studio compiler (MSVC) and MinGW. The __CYGWIN__ macro covers gcc and clang under
+// Cygwin.
+#if defined(_WIN32) || defined(__CYGWIN__)
+    __declspec(dllexport)
+#endif
+    double
+    fairKMeans(double *array,
+               double *sampleWeights,
+               int *colors,
+               uint n,
+               uint d,
+               uint k,
+               uint nc,
+               uint maxIterations,
+               double tolerance,
+               std::uint64_t seed,
+               int *labels,
+               double *centers,
+               bool updateCenters,
+               uint *iterations)
+    {
+
+        std::vector<int> weightsum(nc, 0);
+        std::vector<int> number(nc, 0);
+        // One vector of points per color
+        std::vector<std::vector<Point>> points(nc);
+
+        postprocessData(array, sampleWeights, colors, n, d, points, number, weightsum);
+
+        // std::cout << "Points:" << std::endl;
+        // for (size_t c = 0; c < nc; ++c)
+        // {
+        //     for (size_t i = 0; i < points[c].size(); ++i)
+        //     {
+        //         std::cout << points[c][i].print() << std::endl;
+        //     }
+        // }
+
+        std::vector<Point> centersVector(k);
+        postprocessCenters(centers, centersVector, k, d);
+
+        if (!checkWeightValidity(weightsum))
+        {
+            return -1;
+        }
+
+        // std::cout << "Initial Centers:" << std::endl;
+        // for (size_t i = 0; i < centersVector.size(); ++i)
+        // {
+        //     std::cout << centersVector[i].print() << std::endl;
+        // }
+
+        double cost = std::numeric_limits<double>::max();
+        double previousCost = cost;
+        bool change = true;
+
+        while (*iterations < maxIterations && change)
+        {
+
+            // Computing the fair assignment and better centers
+            // If we don't want to update the centers, then we shoudn't fill all clusters
+            CentersValueChange result = compute_fair_assignment(points, centersVector, number, weightsum, updateCenters, seed);
+
+            // If the returned cost is negative, the CapacityScaling algorithm failed
+            if (std::get<1>(result) < 0.0)
+            {
+                return std::get<1>(result);
+            }
+
+            std::vector<Point> &newCenters = std::get<0>(result);
+
+            // std::cout << std::endl;
+            // std::cout << "New Centers:" << std::endl;
+            // for (size_t i = 0; i < newCenters.size(); ++i)
+            // {
+            //     std::cout << "Center " << i << ": " << newCenters[i].print() << std::endl;
+            // }
+
+            centersVector = newCenters;
+            cost = std::get<1>(result);
+
+
+            // std::cout << "Cost: " << cost << std::endl;
+            // std::cout << "Previous Cost: " << previousCost << std::endl;
+
+            ++*iterations;
+            change = false;
+
+            // If we don't see any improvement anymore, we stop
+            if (cost < (1 - tolerance) * previousCost)
+            {
+                previousCost = cost;
+                change = true;
+            }
+        }
+
+        if (cost >= 0)
+        {
+            if (updateCenters) copyBackCenters(centers, centersVector);
+
+            assignLabels(points, labels);
+        }
+
+        return cost;
+    }
+} // extern "C"
+
+static PyMethodDef module_methods[] = {
+    {NULL, NULL, 0, NULL}};
+
+static struct PyModuleDef _coremodule = {
+    PyModuleDef_HEAD_INIT,
+    "fair_kmeans._core",
+    NULL,
+    -1,
+    module_methods,
+};
+
+PyMODINIT_FUNC PyInit__core(void)
+{
+    return PyModule_Create(&_coremodule);
+}