Skip to contents

This function performs non hierarchical clustering on the basis of dissimilarity with a k-means analysis.


  index = names(dissimilarity)[3],
  seed = NULL,
  n_clust = c(1, 2, 3),
  iter_max = 10,
  nstart = 10,
  algorithm = "Hartigan-Wong",
  algorithm_in_output = TRUE



the output object from dissimilarity() or similarity_to_dissimilarity(), or a dist object. If a data.frame is used, the first two columns represent pairs of sites (or any pair of nodes), and the next column(s) are the dissimilarity indices.


name or number of the dissimilarity column to use. By default, the third column name of dissimilarity is used.


for the random number generator (NULL for random by default).


an integer or an integer vector specifying the requested number(s) of clusters


an integer specifying the maximum number of iterations for the kmeans method (see kmeans)


an integer specifying how many random sets of n_clust should be selected as starting points for the kmeans analysis (see kmeans)


a character specifying the algorithm to use for kmean (see kmeans). Available options are Hartigan-Wong, Lloyd, Forgy and MacQueen.


a boolean indicating if the original output of kmeans should be returned in the output (TRUE by default, see Value).


A list of class bioregion.clusters with five slots:

  1. name: character containing the name of the algorithm

  2. args: list of input arguments as provided by the user

  3. inputs: list of characteristics of the clustering process

  4. algorithm: list of all objects associated with the clustering procedure, such as original cluster objects

  5. clusters: data.frame containing the clustering results

In the algorithm slot, if algorithm_in_output = TRUE, users can find the output of kmeans.


This method partitions the data into k groups such that that the sum of squares of euclidean distances from points to the assigned cluster centers is minimized. k-means cannot be applied directly on dissimilarity/beta-diversity metrics, because these distances are not euclidean. Therefore, it requires first to transform the dissimilarity matrix with a Principal Coordinate Analysis (using the function pcoa), and then applying k-means on the coordinates of points in the PCoA. Because this makes an additional transformation of the initial matrix of dissimilarity, the partitioning around medoids method should be preferred (nhclu_pam)

See also


Boris Leroy (, Pierre Denelle ( and Maxime Lenormand (


comat <- matrix(sample(0:1000, size = 500, replace = TRUE, prob = 1/1:1001),
20, 25)
rownames(comat) <- paste0("Site",1:20)
colnames(comat) <- paste0("Species",1:25)

comnet <- mat_to_net(comat)

dissim <- dissimilarity(comat, metric = "all")

clust1 <- nhclu_kmeans(dissim, n_clust = 2:10, index = "Simpson")
clust2 <- nhclu_kmeans(dissim, n_clust = 2:15, index = "Simpson")
partition_metrics(clust2, dissimilarity = dissim,
                  eval_metric = "pc_distance")
#> Computing similarity-based metrics...
#>   - pc_distance OK
#> Partition metrics:
#>  - 14  partition(s) evaluated
#>  - Range of clusters explored: from  2  to  15 
#>  - Requested metric(s):  pc_distance 
#>  - Metric summary:
#>      pc_distance
#> Min    0.4539020
#> Mean   0.8601235
#> Max    0.9784093
#> Access the data.frame of metrics with your_object$evaluation_df

partition_metrics(clust2, net = comnet, species_col = "Node2",
                  site_col = "Node1", eval_metric = "avg_endemism")
#> Computing composition-based metrics...
#>   - avg_endemism OK
#> Partition metrics:
#>  - 14  partition(s) evaluated
#>  - Range of clusters explored: from  2  to  15 
#>  - Requested metric(s):  avg_endemism 
#>  - Metric summary:
#>      avg_endemism
#> Min             0
#> Mean            0
#> Max             0
#> Access the data.frame of metrics with your_object$evaluation_df
#> Details of endemism % for each partition are available in 
#>         your_object$endemism_results