partition_metrics {bioregion} | R Documentation |

## Calculate metrics for one or several partitions

### Description

This function aims at calculating metrics for one or several partitions,
usually on outputs from `netclu_`

, `hclu_`

or `nhclu_`

functions. Metrics
may require the users to provide either a similarity or dissimilarity
matrix, or to provide the initial species-site table.

### Usage

```
partition_metrics(
cluster_object,
dissimilarity = NULL,
dissimilarity_index = NULL,
net = NULL,
site_col = 1,
species_col = 2,
eval_metric = c("pc_distance", "anosim", "avg_endemism", "tot_endemism")
)
```

### Arguments

`cluster_object` |
a |

`dissimilarity` |
a |

`dissimilarity_index` |
a character string indicating the dissimilarity
(beta-diversity) index to be used in case |

`net` |
the species-site network (i.e., bipartite network). Should be
provided if |

`site_col` |
name or number for the column of site nodes (i.e. primary
nodes). Should be provided if |

`species_col` |
name or number for the column of species nodes (i.e.
feature nodes). Should be provided if |

`eval_metric` |
character string or vector of character strings indicating
metric(s) to be calculated to investigate the effect of different number
of clusters. Available options: |

### Details

**Evaluation metrics:**

`pc_distance`

: this metric is the method used by (Holt et al. 2013). It is a ratio of the between-cluster sum of dissimilarity (beta-diversity) versus the total sum of dissimilarity (beta-diversity) for the full dissimilarity matrix. In other words, it is calculated on the basis of two elements. First, the total sum of dissimilarity is calculated by summing the entire dissimilarity matrix (`dist`

). Second, the between-cluster sum of dissimilarity is calculated as follows: for a given number of cluster, the dissimilarity is only summed between clusters, not within clusters. To do that efficiently, all pairs of sites within the same clusters have their dissimilarity set to zero in the dissimilarity matrix, and then the dissimilarity matrix is summed. The`pc_distance`

ratio is obtained by dividing the between-cluster sum of dissimilarity by the total sum of dissimilarity.`anosim`

: This metric is the statistic used in Analysis of Similarities, as suggested in (Castro-Insua et al. 2018) (see vegan::anosim()). It compares the between-cluster dissimilarities to the within-cluster dissimilarities. It is based based on the difference of mean ranks between groups and within groups with the following formula: \(R = (r_B - r_W)/(N (N-1) / 4)\), where \(r_B\) and \(r_W\) are the average ranks between and within clusters respectively, and \(N\) is the total number of sites. Note that the function does not estimate the significance here, it only computes the statistic - for significance testing see vegan::anosim().`avg_endemism`

: this metric is the average percentage of endemism in clusters as recommended by (Kreft and Jetz 2010). Calculated as follows: \(End_{mean} = \frac{\sum_{i=1}^K E_i / S_i}{K}\) where \(E_i\) is the number of endemic species in cluster i, \(S_i\) is the number of species in cluster i, and K the maximum number of clusters.`tot_endemism`

: this metric is the total endemism across all clusters, as recommended by (Kreft and Jetz 2010). Calculated as follows: \(End_{tot} = \frac{E}{C}\)where \(E\) is total the number of endemics (i.e., species found in only one cluster) and \(C\) is the number of non-endemic species.

### Value

a `list`

of class `bioregion.partition.metrics`

with two to three elements:

`args`

: input arguments`evaluation_df`

: the data.frame containing`eval_metric`

for all explored numbers of clusters`endemism_results`

: if endemism calculations were requested, a list with the endemism results for each partition

### Author(s)

Boris Leroy (leroy.boris@gmail.com), Maxime Lenormand (maxime.lenormand@inrae.fr) and Pierre Denelle (pierre.denelle@gmail.com)

### References

Castro-Insua A, Gómez-Rodríguez C, Baselga A (2018).
“Dissimilarity measures affected by richness differences yield biased delimitations of biogeographic realms.”
*Nature Communications*, **9**(1), 9–11.

Ficetola GF, Mazel F, Thuiller W (2017).
“Global determinants of zoogeographical boundaries.”
*Nature Ecology & Evolution*, **1**, 0089.

Holt BG, Lessard J, Borregaard MK, Fritz SA, Araújo MB, Dimitrov D, Fabre P, Graham CH, Graves GR, Jønsson Ka, Nogués-Bravo D, Wang Z, Whittaker RJ, Fjeldså J, Rahbek C (2013).
“An update of Wallace's zoogeographic regions of the world.”
*Science*, **339**(6115), 74–78.

Kreft H, Jetz W (2010).
“A framework for delineating biogeographical regions based on species distributions.”
*Journal of Biogeography*, **37**, 2029–2053.

Langfelder P, Zhang B, Horvath S (2008).
“Defining clusters from a hierarchical cluster tree: the Dynamic Tree Cut package for R.”
*BIOINFORMATICS*, **24**(5), 719–720.

### See Also

### Examples

```
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")
# User-defined number of clusters
tree1 <- hclu_hierarclust(dissim, n_clust = 2:20, index = "Simpson")
tree1
a <- partition_metrics(tree1, dissimilarity = dissim, net = comnet,
site_col = "Node1", species_col = "Node2",
eval_metric = c("tot_endemism", "avg_endemism",
"pc_distance", "anosim"))
a
```

*bioregion*version 1.1.1 Index]