### ----------------------------------------------------
### -- ML::Clustering
### -- Licenses: Artistic-2.0
### -- Authors: Anton Antonov
### -- File: doc/K-means-function-page.md
### ----------------------------------------------------
### -- Chunk 2 of 3
 => 4278.43875 | Sheep           => 1  |
# | Median => 137        | Median => 53.83      | Human           => 1  |
# | 3rd-Qu => 421        | 3rd-Qu => 493        | AfricanElephant => 1  |
# | Max    => 5712       | Max    => 87000      | AsianElephant   => 1  |
# |                      |                      | Giraffe         => 1  |
# |                      |                      | (Other)         => 21 |
# +----------------------+----------------------+-----------------------+
```

Cluster by body weight only:

```perl6
my %awRes1 = find-clusters(@data2D2.map({ [$_<BodyWeight>,] }), 4, prop => 'All');
.say for %awRes1<IndexClusters>.map({ to-pretty-table(@data2D2[|$_], field-names => <Species BodyWeight BodyWeight>, align => { :Species<l> }, float-format =>  '10.3f') });
```
```
# +--------------+------------+------------+
# | Species      | BodyWeight | BodyWeight |
# +--------------+------------+------------+
# | GreyWolf     |     36.330 |     36.330 |
# | Goat         |     27.660 |     27.660 |
# | PotarMonkey  |     10     |     10     |
# | RhesusMonkey |      6.800 |      6.800 |
# | Kangaroo     |     35     |     35     |
# +--------------+------------+------------+
# +------------+------------+------------+
# | Species    | BodyWeight | BodyWeight |
# +------------+------------+------------+
# | Cow        |    465     |    465     |
# | Donkey     |    187.100 |    187.100 |
# | Horse      |    521     |    521     |
# | Giraffe    |    529     |    529     |
# | Gorilla    |    207     |    207     |
# | Human      |     62     |     62     |
# | Sheep      |     55.500 |     55.500 |
# | Jaguar     |    100     |    100     |
# | Chimpanzee |     52.160 |     52.160 |
# | Pig        |    192     |    192     |
# +------------+------------+------------+
# +----------------+------------+------------+
# | Species        | BodyWeight | BodyWeight |
# +----------------+------------+------------+
# | MountainBeaver |      1.350 |      1.350 |
# | GuineaPig      |      1.040 |      1.040 |
# | Cat            |      3.300 |      3.300 |
# | GoldenHamster  |      0.120 |      0.120 |
# | Mouse          |      0.023 |      0.023 |
# | Rabbit         |      2.500 |      2.500 |
# | Rat            |      0.280 |      0.280 |
# | Mole           |      0.122 |      0.122 |
# +----------------+------------+------------+
# +-----------------+------------+------------+
# | Species         | BodyWeight | BodyWeight |
# +-----------------+------------+------------+
# | Diplodocus      |   11700    |   11700    |
# | AsianElephant   |    2547    |    2547    |
# | AfricanElephant |    6654    |    6654    |
# | Triceratops     |    9400    |    9400    |
# | Brachiosaurus   |   87000    |   87000    |
# +-----------------+------------+------------+
```

Note that obtained clusters seem well separated by weight:

```perl6
text-list-plot(((%awRes1<ClusterLabels>.Array >>+>> 1) Z @data2D2.map({ $_<BodyWeight> }))>>.log10.List)
```
```
# +---+-------+--------+-------+--------+--------+-------+---+      
# |                                                          |      
# |                            *                             |      
# +                            *                             +  4.00
# |                            *                             |      
# |                                            *             |      
# +                                            *             +  2.00
# |                                            *         *   |      
# |                                                      *   |      
# |   *                                                      |      
# +   *                                                      +  0.00
# |   *                                                      |      
# |   *                                                      |      
# +                                                          + -2.00
# +---+-------+--------+-------+--------+--------+-------+---+      
#     0.00    0.10     0.20    0.30     0.40     0.50    0.60
```

Here we cluster using both body weight and brain weight -- for that combination of weights it makes sense to cluster
with Cosine distance:

```perl6
my %awRes2 = find-clusters(@data2D2.map({ $_<BodyWeight BrainWeight> }), 4, distance-function => 'Cosine', prop => 'All');
.say for %awRes2<IndexClusters>.map({ to-pretty-table(@data2D2[|$_], field-names => <Species BodyWeight BodyWeight>, align => { :Species<l> }, float-format =>  '10.3f') });
```
```
# +---------------+------------+------------+
# | Species       | BodyWeight | BodyWeight |
# +---------------+------------+------------+
# | Diplodocus    |   11700    |   11700    |
# | Triceratops   |    9400    |    9400    |
# | Brachiosaurus |   87000    |   87000    |
# +---------------+------------+------------+
# +-----------------+------------+------------+
# | Species         | BodyWeight | BodyWeight |
# +-----------------+------------+------------+
# | Cow             |    465     |    465     |
# | Horse           |    521     |    521     |
# | Giraffe         |    529     |    529     |
# | AfricanElephant |    6654    |    6654    |
# | Pig             |    192     |    192     |
# +-----------------+------------+------------+
# +---------------+------------+------------+
# | Species       | BodyWeight | BodyWeight |
# +---------------+------------+------------+
# | GreyWolf      |     36.330 |     36.330 |
# | AsianElephant |    2547    |    2547    |
# | Donkey        |    187.100 |    187.100 |
# | Gorilla       |    207     |    207     |
# | Kangaroo      |     35     |     35     |
# | Sheep         |     55.500 |     55.500 |
# | Jaguar        |    100     |    100     |
# +---------------+------------+------------+
# +----------------+------------+------------+
# | Species        | BodyWeight | BodyWeight |
# +----------------+------------+------------+
# | MountainBeaver |      1.350 |      1.350 |
# | Goat           |     27.660 |     27.660 |
# | GuineaPig      |      1.040 |      1.040 |
# | PotarMonkey    |     10     |     10     |
# | Cat            |      3.300 |      3.300 |
# | Human          |     62     |     62     |
# | RhesusMonkey   |      6.800 |      6.800 |
# | GoldenHamster  |      0.120 |      0.120 |
# | Mouse          |      0.023 |      0.023 |
# | Rabbit         |      2.500 |      2.500 |
# | Chimpanzee     |     52.160 |     52.160 |
# | Rat            |      0.280 |      0.280 |
# | Mole           |      0.122 |      0.122 |
# +----------------+------------+------------+
```

Note that obtained clusters seem well separated by body-brain weights directions:

```perl6
text-list-plot(%awRes2<Clusters>>>.log10);
```
```
# +-------+-------+--------+-------+-------+--------+-------++      
# +                                            *  ▽          +  4.00
# |                                                          |      
# +                              ❍                           +  3.00
# |                              ❍   **  ▽                   |      
# |                      ❍       * * ▽                      □|      
# +                        ❍  ❍*                   □         +  2.00
# |                            *                    □        |      
# |                   ❍❍                                     |      
# +               ❍❍                                         +  1.00
# |        ❍                                                 |      
# +       ❍   ❍                                              +  0.00
# |                                                          |      
# | ❍                                                        |      
# +-------+-------+--------+-------+-------+--------+-------++      
#         -1.00   0.00     1.00    2.00    3.00     4.00    5.00
```

------

## Properties and Relations

Often it is good idea to run `k-means` a few times:

```perl6
for 1 ... 3 {
    say text-list-plot(k-means(@data2D5, 5), point-char => (1 .. 5)>>.Str, title => "run: { $_ }"), "\n";
}
```
```
# run: 1                           
# +---------------+-----------------+----------------+-------+        
# +                                                 33       +  120.00
# |                                           3333333333333  |        
# +                                             333333333311 +  100.00
# |                                          3  11111111  11 |        
# +                    2222 22                               +   80.00
# |                   22222222                               |        
# +               2 22222222222                              +   60.00
# +                  2222222 22                              +   40.00
# |                 5555                                     |        
# +               55555555   55555555                        +   20.00
# |   44444        55555 5 55555555555 5                     |        
# +444444444               5 5555555  5                      +    0.00
# |  444444                     5                            |        
# +---------------+-----------------+----------------+-------+        
#                 0.00              50.00            100.00           
# 
#                            run: 2                           
# +---------------+-----------------+----------------+-------+        
# +                                                2 2       +  120.00
# |                                           2222222222222  |        
# +                                             222222222222 +  100.00
# |                                          2  22222222 222 |        
# +                    3333 3                       2        +   80.00
# |                   33333333                               |        
# +               3 33333333333                              +   60.00
# +                  33333 3 33                              +   40.00
# |                 1 11                                     |        
# +              111111111   11111111                        +   20.00
# |   55555        11111 1 1111111111  1                     |        
# +444555555               1 1111111  1                      +    0.00
# | 4 44445                     1                            |        
# +---------------+-----------------+----------------+-------+        
#                 0.00              50.00            100.00           
# 
#                            run: 3                           
# +---------------+-----------------+----------------+-------+        
# +                                                4 4       +  120.00
# |                                           4444444444444  |        
# +                                             444444444444 +  100.00
# |                                          4  44444444 444 |        
# +                    3333 3                       4        +   80.00
# |                   33333333                               |        
# +               3 33333333333                              +   60.00
# +                  3333333 33                              +   40.00
# |                 3 33                                     |        
# +               33333335   55555555                        +   20.00
# |   22222        33555 5 5555555555  5                     |        
# +111222222               5 5555555  5                      +    0.00
# | 1 11111                     5                            |        
# +---------------+-----------------+----------------+-------+        
#                 0.00              50.00            100.00
```

-------

## Possible Issues

The initial mean points of the clusters are chosen at random. Hence, to reproduce clustering results `srand` has to be
used.

-------

## Neat Examples

Extracted point-vectors from a rasterized formula `x^2 + y^2 == 1`:

```perl6
my @blackPoints = [[11, 15], [40, 15], [9, 14], [10, 14], [11, 14], [12, 14], [13, 14], [38, 14], [39, 14], [40, 14], [41, 14], [42, 14], [9, 13], [10, 13], [12, 13], [13, 13], [38, 13], [39, 13], [41, 13], [42, 13], [12, 12], [13, 12], [41, 12], [42, 12], [11, 11], [12, 11], [40, 11], [41, 11], [64, 11], [65, 11], [66, 11], [67, 11], [10, 10], [11, 10], [12, 10], [39, 10], [40, 10], [41, 10], [64, 10], [65, 10], [66, 10], [67, 10], [2, 9], [3, 9], [6, 9], [7, 9], [9, 9], [10, 9], [11, 9], [12, 9], [13, 9], [30, 9], [31, 9], [35, 9], [36, 9], [37, 9], [38, 9], [39, 9], [40, 9], [41, 9], [42, 9], [66, 9], [67, 9], [2, 8], [3, 8], [4, 8], [5, 8], [6, 8], [7, 8], [22, 8], [23, 8], [31, 8], [32, 8], [35, 8], [36, 8], [66, 8], [67, 8], [3, 7], [4, 7], [5, 7], [6, 7], [22, 7], [23, 7], [31, 7], [32, 7], [35, 7], [36, 7], [50, 7], [51, 7], [52, 7], [53, 7], [54, 7], [55, 7], [56, 7], [57, 7], [58, 7], [66, 7], [67, 7], [3, 6], [4, 6], [5, 6], [20, 6], [21, 6], [22, 6], [23, 6], [24, 6], [25, 6], [31, 6], [32, 6], [33, 6], [34, 6], [35, 6], [36, 6], [50, 6], [51, 6], [52, 6], [53, 6], [54, 6], [55, 6], [56, 6], [57, 6], [66, 6], [67, 6], [3, 5], [4, 5], [5, 5], [6, 5], [20, 5], [21, 5], [22, 5], [23, 5], [24, 5], [25, 5], [32, 5], [33, 5], [34, 5], [35, 5], [50, 5], [51, 5], [52, 5], [53, 5], [55, 5], [56, 5], [57, 5], [66, 5], [67, 5], [2, 4], [3, 4], [4, 4], [5, 4], [6, 4], [7, 4], [22, 4], [23, 4], [32, 4], [33, 4], [34, 4], [35, 4], [50, 4], [51, 4], [52, 4], [53, 4], [54, 4], [55, 4], [56, 4], [57, 4], [58, 4], [64, 4], [65, 4], [66, 4], [67, 4], [68, 4], [69, 4], [1, 3], [2, 3], [3, 3], [6, 3], [7, 3], [22, 3], [23, 3], [33, 3], [34, 3], [64, 3], [65, 3], [66, 3], [67, 3], [68, 3], [69, 3], [33, 2], [34, 2], [31, 1], [32, 1], [33, 1], [34, 1], [30, 0], [31, 0], [32, 0], [33, 0]];
```
```
# [[11 15] [40 15] [9 14] [10 14] [11 14] [12 14] [13 14] [38 14] [39 14] [40 14] [41 14] [42 14] [9 13] [10 13] [12 13] [13 13] [38 13] [39 13] [41 13] [42 13] [12 12] [13 12] [41 12] [42 12] [11 11] [12 11] [40 11] [41 11] [64 11] [65 11] [66 11] [67 11] [10 10] [11 10] [12 10] [39 10] [40 10] [41 10] [64 10] [65 10] [66 10] [67 10] [2 9] [3 9] [6 9] [7 9] [9 9] [10 9] [11 9] [12 9] [13 9] [30 9] [31 9] [35 9] [36 9] [37 9] [38 9] [39 9] [40 9] [41 9] [42 9] [66 9] [67 9] [2 8] [3 8] [4 8] [5 8] [6 8] [7 8] [22 8] [23 8] [31 8] [32 8] [35 8] [36 8] [66 8] [67 8] [3 7] [4 7] [5 7] [6 7] [22 7] [23 7] [31 7] [32 7] [35 7] [36 7] [50 7] [51 7] [52 7] [53 7] [54 7] [55 7] [56 7] [57 7] [58 7] [66 7] [67 7] [3 6] [4 6] ...]
```

Plot the extracted point-vectors:

```perl6
text-list-plot(@blackPoints, width => 76, height => 18)
```
```
# +--+-------------------+------------------+-------------------+------------+       
# |                                                                          |       
# +             *                           *                                +  15.00
# |           *****                       *****                              |       
# |           ** **                       ** **                              |       
# |             **                          **                      ****     |       
# +            ***                         ***                      ****     +  10.00
# |    **  ** *****                **  ********                       **     |       
# |    ******              **       *  **                             **     |       
# |     ****               **       *  **             *********       **     |       
# |     ***              ******     *****             ********        **     |       
# +     ****             ******     ****              **** ***        **     +   5.00
# |    ******              **       ****              *********     ******   |       
# |   ***  **              **        **                             ******   |       
# |                                 ***                                      |       
# +                                ***                                       +   0.00
# |                                                                          |       
# +--+-------------------+------------------+-------------------+------------+       
#    0.00                20.00              40.00               60.00
```

Cluster and plot the clusters using different distance functions:

```perl6
<Euclidean Cosine Chessboard Manhattan BrayCurtis Canberra>.map({
    say text-list-plot(
            k-means(@blackPoints, 7, distance-function => $_), 
            point-char => (1 .. 7)>>.Str, 
            title => $_, 
            width => 76, height => 18), "\n"
})
```
```
# Euclidean                                  
# +----------+---------+----------+----------+---------+----------+---------++       
# |                                                                          |       
# +         33333                         66 666                             +  15.00
# |         33 33                         66  66                             |       
# |            33                             66                             |       
# |           33                             66                       4444   |       
# +          333                           6 66                       4444   +  10.00
# | 2 2  22 23333                 77   77776 666                        44   |       
# | 2 22222               11       77  77                               44   |       
# |   2222                11       77  77              666444444        44   |       
# |   222              11 1155     777777              66644444         44   |       
# +   2222             11 1155      7777               6644 444         44   +   5.00
# | 2 22222               15        7777               664444444      444444 |       
# |22 2  22               55         77                               444444 |       
# |                                  77                                      |       
# |                                7777                                      |       
# +                               5777                                       +   0.00
# +----------+---------+----------+----------+---------+----------+---------++       
#            10.00     20.00      30.00      40.00     50.00      60.00     70.00    
# 
#                                    Cosine                                   
# ++-------------------+--------------------+--------------------+-----------+       
# |                                                                          |       
# +           3                             2                                +  15.00
# |         33337                         22222                              |       
# |            77                            11                              |       
# |           77                            11                       5544    |       
# +          777                           111                       4444    +  10.00
# |  33  33 77777                 11   11115555                        44    |       
# |  333333              22        11  55                              44    |       
# |   3333               21        55  55             44444444 4       44    |       
# |   333              111111      555554             44444444         66    |       
# +   3377             115555       4444              6666 666         66    +   5.00
# |  337777              55         4444              66666666 6     666666  |       
# | 337  22              44          66                              666666  |       
# |                                  66                                      |       
# |                                6666                                      |       
# +                               6666                                       +   0.00
# ++-------------------+--------------------+--------------------+-----------+       
#  0.00                20.00                40.00                60.00               
# 
#                                  Chessboard                                 
# +----------+---------+----------+---------+----------+---------+----------++       
# +           6                             7                                +  15.00
# |         66666                         7777 7                             |       
# |         66 66                         77 7 7                             |       
# |            66                            7 7                             |       
# |           55                            77                        2222   |       
# +          555                           777                        2222   +  10.00
# | 33   33 55555                 11   7777777 7                        22   |       
# | 333 333              44        11  77                               22   |       
# |  33 33               44        11  77              222222222        22   |       
# |  33 3              4444 44     111111              22222222         22   |       
# +  33 33             4444 44      1111               2222 222         22   +   5.00
# | 333 333              44         1111               222222222      222222 |       
# |333   33              44          11                               222222 |       
# |                                  11                                      |       
# |                                1111                                      |       
# +                               1111                                       +   0.00
# +----------+---------+----------+---------+----------+---------+----------++       
#            10.00     20.00      30.00     40.00      50.00     60.00      70.00    
# 
#                                  Manhattan                                  
# +----------+---------+----------+---------+----------+---------+----------++       
# +           2                             6                                +  15.00
# |         22222                         6666 6                             |       
# |         22 22                         66 6 6                             |       
# |            22                            6 6                             |       
# |           22                            66                        1111   |       
# +          222                           666                        1111   +  10.00
# | 77   77 22222                 33   6666666 6                        11   |       
# | 777 777              33        33  66                               11   |       
# |  77 77               33        33  66              111111111        11   |       
# |  77 7              3333 33     334446              11111111         11   |       
# +  77 77             3333 33      4444               1111 111         11   +   5.00
# | 777 777              33         4444               111111111      111111 |       
# |777   77              33          44                               111111 |       
# |                                  44                                      |       
# |                                5555                                      |       
# +                               5555                                       +   0.00
# +----------+---------+----------+---------+----------+---------+----------++       
#            10.00     20.00      30.00     40.00      50.00     60.00      70.00    
# 
#                                  BrayCurtis                                 
# +----------+---------+----------+---------+----------+---------+----------++       
# +           7                             1                                +  15.00
# |         77777                         11111                              |       
# |         77 77                         11 11                              |       
# |