1# PHP Kmean
2
3[![Latest Version on Packagist](https://img.shields.io/packagist/v/bdelespierre/php-kmeans.svg?style=flat-square)](https://packagist.org/packages/bdelespierre/php-kmeans)
4[![Build Status](https://img.shields.io/travis/bdelespierre/php-kmeans/master.svg?style=flat-square)](https://travis-ci.org/bdelespierre/php-kmeans)
5[![Quality Score](https://img.shields.io/scrutinizer/g/bdelespierre/php-kmeans.svg?style=flat-square)](https://scrutinizer-ci.com/g/bdelespierre/php-kmeans)
6[![Total Downloads](https://img.shields.io/packagist/dt/bdelespierre/php-kmeans.svg?style=flat-square)](https://packagist.org/packages/bdelespierre/php-kmean)
7
8[K-mean](http://en.wikipedia.org/wiki/K-means_clustering) clustering algorithm implementation in PHP.
9
10Please also see the [FAQ](#faq)
11
12## Installation
13
14You can install the package via composer:
15
16```bash
17composer require bdelespierre/php-kmeans
18```
19
20## Usage
21
22```PHP
23require "vendor/autoload.php";
24
25// prepare 50 points of 2D space to be clustered
26$points = [
27    [80,55],[86,59],[19,85],[41,47],[57,58],
28    [76,22],[94,60],[13,93],[90,48],[52,54],
29    [62,46],[88,44],[85,24],[63,14],[51,40],
30    [75,31],[86,62],[81,95],[47,22],[43,95],
31    [71,19],[17,65],[69,21],[59,60],[59,12],
32    [15,22],[49,93],[56,35],[18,20],[39,59],
33    [50,15],[81,36],[67,62],[32,15],[75,65],
34    [10,47],[75,18],[13,45],[30,62],[95,79],
35    [64,11],[92,14],[94,49],[39,13],[60,68],
36    [62,10],[74,44],[37,42],[97,60],[47,73],
37];
38
39// create a 2-dimentions space
40$space = new KMeans\Space(2);
41
42// add points to space
43foreach ($points as $i => $coordinates) {
44    $space->addPoint($coordinates);
45}
46
47// cluster these 50 points in 3 clusters
48$clusters = $space->solve(3);
49
50// display the cluster centers and attached points
51foreach ($clusters as $num => $cluster) {
52    $coordinates = $cluster->getCoordinates();
53    printf(
54        "Cluster %s [%d,%d]: %d points\n",
55        $num,
56        $coordinates[0],
57        $coordinates[1],
58        count($cluster)
59    );
60}
61```
62
63**Note:** the example is given with points of a 2D space but it will work with any dimention >1.
64
65### Testing
66
67``` bash
68composer test
69```
70
71### Changelog
72
73Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
74
75## Contributing
76
77Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
78
79### Security
80
81If you discover any security related issues, please email benjamin.delespierre@gmail.com instead of using the issue tracker.
82
83## Credits
84
85- [Benjamin Delespierre](https://github.com/bdelespierre)
86- [Ron Cemer](https://github.com/roncemer)
87- [All Contributors](../../contributors)
88
89## License
90
91Lesser General Public License (LGPL). Please see [License File](LICENSE.md) for more information.
92
93## FAQ
94
95### How to get coordinates of a point/cluster:
96```PHP
97$x = $point[0];
98$y = $point[1];
99
100// or
101
102list($x,$y) = $point->getCoordinates();
103```
104
105### List all points of a space/cluster:
106
107```PHP
108foreach ($cluster as $point) {
109    printf('[%d,%d]', $point[0], $point[1]);
110}
111```
112
113### Attach data to a point:
114
115```PHP
116$point = $space->addPoint([$x, $y, $z], "user #123");
117```
118
119### Retrieve point data:
120
121```PHP
122$data = $space[$point]; // e.g. "user #123"
123```
124
125### Watch the algorithm run
126
127Each iteration step can be monitored using a callback function passed to `Kmeans\Space::solve`:
128
129```PHP
130$clusters = $space->solve(3, function($space, $clusters) {
131    static $iterations = 0;
132
133    printf("Iteration: %d\n", ++$iterations);
134
135    foreach ($clusters as $i => $cluster) {
136        printf("Cluster %d [%d,%d]: %d points\n", $i, $cluster[0], $cluster[1], count($cluster));
137    }
138});
139```
140