README

👁 Latest Version on Packagist
👁 Build Status
👁 Quality Score
👁 Total Downloads

K-mean clustering algorithm implementation in PHP.

Please also see the FAQ

Installation

You can install the package via composer:

composer require bdelespierre/php-kmeans

Usage

require "vendor/autoload.php";

// prepare 50 points of 2D space to be clustered
$points = [
 [80,55],[86,59],[19,85],[41,47],[57,58],
 [76,22],[94,60],[13,93],[90,48],[52,54],
 [62,46],[88,44],[85,24],[63,14],[51,40],
 [75,31],[86,62],[81,95],[47,22],[43,95],
 [71,19],[17,65],[69,21],[59,60],[59,12],
 [15,22],[49,93],[56,35],[18,20],[39,59],
 [50,15],[81,36],[67,62],[32,15],[75,65],
 [10,47],[75,18],[13,45],[30,62],[95,79],
 [64,11],[92,14],[94,49],[39,13],[60,68],
 [62,10],[74,44],[37,42],[97,60],[47,73],
];

// create a 2-dimentions space
$space = new KMeans\Space(2);

// add points to space
foreach ($points as $i => $coordinates) {
 $space->addPoint($coordinates);
}

// cluster these 50 points in 3 clusters
$clusters = $space->solve(3);

// display the cluster centers and attached points
foreach ($clusters as $num => $cluster) {
 $coordinates = $cluster->getCoordinates();
 printf(
 "Cluster %s [%d,%d]: %d points\n",
 $num,
 $coordinates[0],
 $coordinates[1],
 count($cluster)
 );
}

Note: the example is given with points of a 2D space but it will work with any dimention >1.

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email benjamin.delespierre@gmail.com instead of using the issue tracker.

Credits

• Benjamin Delespierre
• Ron Cemer
• All Contributors

License

Lesser General Public License (LGPL). Please see License File for more information.

FAQ

How to get coordinates of a point/cluster:

$x = $point[0];
$y = $point[1];

// or

list($x,$y) = $point->getCoordinates();

List all points of a space/cluster:

foreach ($cluster as $point) {
 printf('[%d,%d]', $point[0], $point[1]);
}

Attach data to a point:

$point = $space->addPoint([$x, $y, $z], "user #123");

Retrieve point data:

$data = $space[$point]; // e.g. "user #123"

Watch the algorithm run

Each iteration step can be monitored using a callback function passed to Kmeans\Space::solve:

$clusters = $space->solve(3, function($space, $clusters) {
 static $iterations = 0;

 printf("Iteration: %d\n", ++$iterations);

 foreach ($clusters as $i => $cluster) {
 printf("Cluster %d [%d,%d]: %d points\n", $i, $cluster[0], $cluster[1], count($cluster));
 }
});