Calculate contribution metrics of sites and species
Source:R/site_species_metrics.R
site_species_metrics.RdThis function calculates metrics to assess the contribution of a given species or site to its bioregion.
Usage
site_species_metrics(
bioregionalization,
comat,
indices = c("rho"),
net = NULL,
site_col = 1,
species_col = 2
)Arguments
- bioregionalization
A
bioregion.clustersobject.- comat
A co-occurrence
matrixwith sites as rows and species as columns.- indices
A
characterspecifying the contribution metric to compute. Available options arerho,affinity,fidelity,indicator_valueandCz.- net
NULLby default. Required forCzindices. Adata.framewhere each row represents an interaction between two nodes and an optional third column indicating the interaction's weight.- site_col
A number indicating the position of the column containing the sites in
net. 1 by default.- species_col
A number indicating the position of the column containing the species in
net. 2 by default.
Value
A named list of class bioregion.site.species.metrics containing one element
per bioregionalization. Each element is a list with:
name: Character, the bioregionalization namemetrics: Adata.framewith columnsBioregion,Species, and the requested contribution metrics (e.g.,rho,affinity,fidelity,indicator_value)indices: Character vector of computed indicescz_metrics: (IfCzrequested) Adata.framewith Cz metrics for nodesargs: List of input arguments
For a single bioregionalization, the list contains one element accessible via
result[[1]] or result$bioregionalization_name.
For multiple bioregionalizations, access individual results via
result$bioregionalization_name or result[[i]].
Details
When multiple bioregionalizations are provided (i.e., the clusters arg has more
than 2 columns), the function computes metrics for each bioregionalization
separately. The output is always returned as a named list of class
bioregion.site.species.metrics, regardless of the number of
bioregionalizations.
The \(\rho\) metric is derived from Lenormand et al. (2019) with the following formula:
\(\rho_{ij} = \frac{n_{ij} - \frac{n_i n_j}{n}}{\sqrt{\left(\frac{n - n_j}{ n-1}\right) \left(1-\frac{n_j}{n}\right) \frac{n_i n_j}{n}}}\)
where \(n\) is the number of sites, \(n_i\) is the number of sites in which species \(i\) is present, \(n_j\) is the number of sites in bioregion \(j\), and \(n_{ij}\) is the number of occurrences of species \(i\) in sites of bioregion \(j\).
Affinity \(A\), fidelity \(F\), and individual contributions \(IndVal\) describe how species are linked to their bioregions. These metrics are described in Bernardo-Madrid et al. (2019):
Affinity of species to their region: \(A_i = \frac{R_i}{Z}\), where \(R_i\) is the occurrence/range size of species \(i\) in its associated bioregion, and \(Z\) is the total size (number of sites) of the bioregion. High affinity indicates that the species occupies most sites in its bioregion.
Fidelity of species to their region: \(F_i = \frac{R_i}{D_i}\), where \(R_i\) is the occurrence/range size of species \(i\) in its bioregion, and \(D_i\) is its total range size. High fidelity indicates that the species is not present in other regions.
Indicator Value of species: \(IndVal = F_i \cdot A_i\).
Cz metrics are derived from Guimerà & Amaral (2005):
Participation coefficient: \(C_i = 1 - \sum_{s=1}^{N_M}{\left(\frac{k_{is}}{k_i}\right)^2}\), where \(k_{is}\) is the number of links of node \(i\) to nodes in bioregion \(s\), and \(k_i\) is the total degree of node \(i\). A high value means links are uniformly distributed; a low value means links are within the node's bioregion.
Within-bioregion degree z-score: \(z_i = \frac{k_i - \overline{k_{si}}}{\sigma_{k_{si}}}\), where \(k_i\) is the number of links of node \(i\) to nodes in its bioregion \(s_i\), \(\overline{k_{si}}\) is the average degree of nodes in \(s_i\), and \(\sigma_{k_{si}}\) is the standard deviation of degrees in \(s_i\).
References
Bernardo-Madrid R, Calatayud J, González‐Suárez M, Rosvall M, Lucas P, Antonelli A & Revilla E (2019) Human activity is altering the world’s zoogeographical regions. Ecology Letters 22, 1297–1305.
Guimerà R & Amaral LAN (2005) Functional cartography of complex metabolic networks. Nature 433, 895–900.
Lenormand M, Papuga G, Argagnon O, Soubeyrand M, Alleaume S & Luque S (2019) Biogeographical network analysis of plant species distribution in the Mediterranean region. Ecology and Evolution 9, 237–250.
See also
For more details illustrated with a practical example, see the vignette: https://biorgeo.github.io/bioregion/articles/a5_3_summary_metrics.html.
Associated functions: bioregion_metrics bioregionalization_metrics
Author
Pierre Denelle (pierre.denelle@gmail.com)
Boris Leroy (leroy.boris@gmail.com)
Maxime Lenormand (maxime.lenormand@inrae.fr)
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)
# Single bioregionalization
dissim <- dissimilarity(comat, metric = "Simpson")
clust1 <- nhclu_kmeans(dissim, n_clust = 3, index = "Simpson")
metrics <- site_species_metrics(bioregionalization = clust1,
comat = comat,
indices = "rho")
# Print shows summary
print(metrics)
#> Site and species contribution metrics:
#> - Number of bioregionalizations: 1
#> - Bioregionalizations: K_3
#> - Computed indices: rho
#>
#> Bioregionalization 'K_3':
#> - Metrics: 75 rows
#> - Unique species: 25
#> - Bioregions: 3
#> - Columns: Bioregion, Species, rho
#>
#> Access individual results with:
#> your_object[[1]]$metrics # Contribution metrics
#> Or see the full list structure with str(your_object)
# Access the data
metrics[[1]]$metrics # The contribution metrics data.frame
#> Bioregion Species rho
#> 1 1 Species1 -0.35355339
#> 2 1 Species2 0.00000000
#> 3 1 Species3 1.32637071
#> 4 1 Species4 1.02740233
#> 5 1 Species5 0.48432210
#> 6 1 Species6 0.48432210
#> 7 1 Species7 -0.12108053
#> 8 1 Species8 0.66318535
#> 9 1 Species9 0.00000000
#> 10 1 Species10 0.23570226
#> 11 1 Species11 -0.12108053
#> 12 1 Species12 -0.12108053
#> 13 1 Species13 0.38527588
#> 14 1 Species14 0.48432210
#> 15 1 Species15 -0.35355339
#> 16 1 Species16 0.23570226
#> 17 1 Species17 -0.12108053
#> 18 1 Species18 0.48432210
#> 19 1 Species19 1.02740233
#> 20 1 Species20 0.12459083
#> 21 1 Species21 -0.12108053
#> 22 1 Species22 -1.54110350
#> 23 1 Species23 -1.98955606
#> 24 1 Species24 0.00000000
#> 25 1 Species25 -0.12108053
#> 26 2 Species1 0.27272727
#> 27 2 Species2 0.00000000
#> 28 2 Species3 -1.87577145
#> 29 2 Species4 -0.79252708
#> 30 2 Species5 -0.68493489
#> 31 2 Species6 -0.68493489
#> 32 2 Species7 -0.06226681
#> 33 2 Species8 -1.19367274
#> 34 2 Species9 0.00000000
#> 35 2 Species10 -0.33333333
#> 36 2 Species11 -0.06226681
#> 37 2 Species12 -0.06226681
#> 38 2 Species13 1.18879062
#> 39 2 Species14 -0.68493489
#> 40 2 Species15 0.27272727
#> 41 2 Species16 -0.33333333
#> 42 2 Species17 -0.06226681
#> 43 2 Species18 -0.68493489
#> 44 2 Species19 -1.45296631
#> 45 2 Species20 -0.41646811
#> 46 2 Species21 -0.06226681
#> 47 2 Species22 1.18879062
#> 48 2 Species23 1.53472209
#> 49 2 Species24 -0.51157403
#> 50 2 Species25 -0.06226681
#> 51 3 Species1 0.10188534
#> 52 3 Species2 0.00000000
#> 53 3 Species3 0.57334084
#> 54 3 Species4 -0.29607194
#> 55 3 Species5 0.20935448
#> 56 3 Species6 0.20935448
#> 57 3 Species7 0.20935448
#> 58 3 Species8 0.57334084
#> 59 3 Species9 0.00000000
#> 60 3 Species10 0.10188534
#> 61 3 Species11 0.20935448
#> 62 3 Species12 0.20935448
#> 63 3 Species13 -1.77643163
#> 64 3 Species14 0.20935448
#> 65 3 Species15 0.10188534
#> 66 3 Species16 0.10188534
#> 67 3 Species17 0.20935448
#> 68 3 Species18 0.20935448
#> 69 3 Species19 0.44410791
#> 70 3 Species20 0.32313597
#> 71 3 Species21 0.20935448
#> 72 3 Species22 0.44410791
#> 73 3 Species23 0.57334084
#> 74 3 Species24 0.57334084
#> 75 3 Species25 0.20935448
head(metrics[[1]]$metrics)
#> Bioregion Species rho
#> 1 1 Species1 -0.3535534
#> 2 1 Species2 0.0000000
#> 3 1 Species3 1.3263707
#> 4 1 Species4 1.0274023
#> 5 1 Species5 0.4843221
#> 6 1 Species6 0.4843221
# Multiple contribution metrics
net <- similarity(comat, metric = "Simpson")
com <- netclu_greedy(net)
metrics_all <- site_species_metrics(bioregionalization = com,
comat = comat,
indices = c("rho", "affinity",
"fidelity", "indicator_value"))
head(metrics_all[[1]]$metrics)
#> Bioregion Species rho affinity fidelity indval
#> 1 1 Species1 4.3588989 1.0000000 1.0000000 1.0000000
#> 2 1 Species2 0.0000000 1.0000000 0.9500000 0.9500000
#> 3 1 Species3 -1.2909944 0.7368421 0.9333333 0.6877193
#> 4 1 Species4 -1.0000000 0.7894737 0.9375000 0.7401316
#> 5 1 Species5 -0.4714045 0.8947368 0.9444444 0.8450292
#> 6 1 Species6 -0.4714045 0.8947368 0.9444444 0.8450292
# Multiple bioregionalizations
# Create two different clustering solutions
clust_k3 <- nhclu_kmeans(dissim, n_clust = 3, index = "Simpson")
clust_k4 <- nhclu_kmeans(dissim, n_clust = 4, index = "Simpson")
# Combine them into one bioregion.clusters object
clust_multi <- clust_k3
clust_multi$clusters <- cbind(clust_k3$clusters, K_4 = clust_k4$clusters[, 2])
metrics_multi <- site_species_metrics(bioregionalization = clust_multi,
comat = comat,
indices = "rho")
#> Multiple bioregionalizations detected (2 columns). Computing metrics for each...
# Pretty print of results
print(metrics_multi)
#> Site and species contribution metrics:
#> - Number of bioregionalizations: 2
#> - Bioregionalizations: K_3, K_4
#> - Computed indices: rho
#>
#> Bioregionalization 'K_3':
#> - Metrics: 75 rows
#> - Unique species: 25
#> - Bioregions: 3
#> - Columns: Bioregion, Species, rho
#>
#> Bioregionalization 'K_4':
#> - Metrics: 100 rows
#> - Unique species: 25
#> - Bioregions: 4
#> - Columns: Bioregion, Species, rho
#>
#> Access individual results with:
#> your_object$bioregionalization_name$metrics
#> your_object[[1]]$metrics # First bioregionalization
#> Or see the full list structure with str(your_object)
# Access individual bioregionalization by name
metrics_multi$K_3$metrics
#> Bioregion Species rho
#> 1 2 Species1 -0.4472136
#> 2 2 Species2 0.0000000
#> 3 2 Species3 0.8388705
#> 4 2 Species4 0.6497863
#> 5 2 Species5 0.3063122
#> 6 2 Species6 0.3063122
#> 7 2 Species7 -0.3063122
#> 8 2 Species8 0.1677741
#> 9 2 Species9 0.0000000
#> 10 2 Species10 0.1490712
#> 11 2 Species11 -0.3063122
#> 12 2 Species12 0.3063122
#> 13 2 Species13 0.0000000
#> 14 2 Species14 0.3063122
#> 15 2 Species15 -0.4472136
#> 16 2 Species16 0.1490712
#> 17 2 Species17 0.3063122
#> 18 2 Species18 0.3063122
#> 19 2 Species19 0.6497863
#> 20 2 Species20 0.4727890
#> 21 2 Species21 0.3063122
#> 22 2 Species22 -0.6497863
#> 23 2 Species23 -2.5166115
#> 24 2 Species24 -0.5033223
#> 25 2 Species25 0.3063122
#> 26 3 Species1 0.1490712
#> 27 3 Species2 0.0000000
#> 28 3 Species3 0.8388705
#> 29 3 Species4 0.0000000
#> 30 3 Species5 0.3063122
#> 31 3 Species6 0.3063122
#> 32 3 Species7 0.3063122
#> 33 3 Species8 0.8388705
#> 34 3 Species9 0.0000000
#> 35 3 Species10 0.1490712
#> 36 3 Species11 0.3063122
#> 37 3 Species12 -0.3063122
#> 38 3 Species13 -1.2995726
#> 39 3 Species14 0.3063122
#> 40 3 Species15 0.1490712
#> 41 3 Species16 0.1490712
#> 42 3 Species17 0.3063122
#> 43 3 Species18 0.3063122
#> 44 3 Species19 0.6497863
#> 45 3 Species20 0.4727890
#> 46 3 Species21 -0.3063122
#> 47 3 Species22 0.0000000
#> 48 3 Species23 0.8388705
#> 49 3 Species24 0.8388705
#> 50 3 Species25 -0.3063122
#> 51 1 Species1 0.3162278
#> 52 1 Species2 0.0000000
#> 53 1 Species3 -1.7795130
#> 54 1 Species4 -0.6892024
#> 55 1 Species5 -0.6497863
#> 56 1 Species6 -0.6497863
#> 57 1 Species7 0.0000000
#> 58 1 Species8 -1.0677078
#> 59 1 Species9 0.0000000
#> 60 1 Species10 -0.3162278
#> 61 1 Species11 0.0000000
#> 62 1 Species12 0.0000000
#> 63 1 Species13 1.3784049
#> 64 1 Species14 -0.6497863
#> 65 1 Species15 0.3162278
#> 66 1 Species16 -0.3162278
#> 67 1 Species17 -0.6497863
#> 68 1 Species18 -0.6497863
#> 69 1 Species19 -1.3784049
#> 70 1 Species20 -1.0029369
#> 71 1 Species21 0.0000000
#> 72 1 Species22 0.6892024
#> 73 1 Species23 1.7795130
#> 74 1 Species24 -0.3559026
#> 75 1 Species25 0.0000000
# Or by index
metrics_multi[[1]]$metrics
#> Bioregion Species rho
#> 1 2 Species1 -0.4472136
#> 2 2 Species2 0.0000000
#> 3 2 Species3 0.8388705
#> 4 2 Species4 0.6497863
#> 5 2 Species5 0.3063122
#> 6 2 Species6 0.3063122
#> 7 2 Species7 -0.3063122
#> 8 2 Species8 0.1677741
#> 9 2 Species9 0.0000000
#> 10 2 Species10 0.1490712
#> 11 2 Species11 -0.3063122
#> 12 2 Species12 0.3063122
#> 13 2 Species13 0.0000000
#> 14 2 Species14 0.3063122
#> 15 2 Species15 -0.4472136
#> 16 2 Species16 0.1490712
#> 17 2 Species17 0.3063122
#> 18 2 Species18 0.3063122
#> 19 2 Species19 0.6497863
#> 20 2 Species20 0.4727890
#> 21 2 Species21 0.3063122
#> 22 2 Species22 -0.6497863
#> 23 2 Species23 -2.5166115
#> 24 2 Species24 -0.5033223
#> 25 2 Species25 0.3063122
#> 26 3 Species1 0.1490712
#> 27 3 Species2 0.0000000
#> 28 3 Species3 0.8388705
#> 29 3 Species4 0.0000000
#> 30 3 Species5 0.3063122
#> 31 3 Species6 0.3063122
#> 32 3 Species7 0.3063122
#> 33 3 Species8 0.8388705
#> 34 3 Species9 0.0000000
#> 35 3 Species10 0.1490712
#> 36 3 Species11 0.3063122
#> 37 3 Species12 -0.3063122
#> 38 3 Species13 -1.2995726
#> 39 3 Species14 0.3063122
#> 40 3 Species15 0.1490712
#> 41 3 Species16 0.1490712
#> 42 3 Species17 0.3063122
#> 43 3 Species18 0.3063122
#> 44 3 Species19 0.6497863
#> 45 3 Species20 0.4727890
#> 46 3 Species21 -0.3063122
#> 47 3 Species22 0.0000000
#> 48 3 Species23 0.8388705
#> 49 3 Species24 0.8388705
#> 50 3 Species25 -0.3063122
#> 51 1 Species1 0.3162278
#> 52 1 Species2 0.0000000
#> 53 1 Species3 -1.7795130
#> 54 1 Species4 -0.6892024
#> 55 1 Species5 -0.6497863
#> 56 1 Species6 -0.6497863
#> 57 1 Species7 0.0000000
#> 58 1 Species8 -1.0677078
#> 59 1 Species9 0.0000000
#> 60 1 Species10 -0.3162278
#> 61 1 Species11 0.0000000
#> 62 1 Species12 0.0000000
#> 63 1 Species13 1.3784049
#> 64 1 Species14 -0.6497863
#> 65 1 Species15 0.3162278
#> 66 1 Species16 -0.3162278
#> 67 1 Species17 -0.6497863
#> 68 1 Species18 -0.6497863
#> 69 1 Species19 -1.3784049
#> 70 1 Species20 -1.0029369
#> 71 1 Species21 0.0000000
#> 72 1 Species22 0.6892024
#> 73 1 Species23 1.7795130
#> 74 1 Species24 -0.3559026
#> 75 1 Species25 0.0000000
# See structure
str(metrics_multi)
#> List of 2 bioregionalization(s)
#> - Class: bioregion.site.species.metrics
#> - Indices: rho
#> - Number of bioregionalizations: 2
#>
#> List of 2
#> $ K_3:List of 4
#> ..$ name : chr "K_3"
#> ..$ metrics:'data.frame': 75 obs. of 3 variables:
#> ..$ indices: chr "rho"
#> ..$ args :List of 2
#> $ K_4:List of 4
#> ..$ name : chr "K_4"
#> ..$ metrics:'data.frame': 100 obs. of 3 variables:
#> ..$ indices: chr "rho"
#> ..$ args :List of 2
#> - attr(*, "class")= chr [1:2] "bioregion.site.species.metrics" "list"
#> - attr(*, "indices")= chr "rho"
#> - attr(*, "n_bioregionalizations")= int 2
# Cz indices (bipartite only)
net_bip <- mat_to_net(comat, weight = TRUE)
clust_bip <- netclu_greedy(net_bip, bipartite = TRUE)
metrics_cz <- site_species_metrics(bioregionalization = clust_bip,
comat = comat,
net = net_bip,
indices = "Cz")
metrics_cz[[1]]$cz_metrics
#> Node Bioregion Category C z
#> 1 Site1 4 site 0.8140496 NaN
#> 2 Site2 2 site 0.8015123 1.2613124
#> 3 Site3 5 site 0.7922438 0.5400617
#> 4 Site4 3 site 0.8016529 -0.2070197
#> 5 Site5 6 site 0.8223140 0.0000000
#> 6 Site6 5 site 0.7981859 0.5400617
#> 7 Site7 1 site 0.8055556 1.5021914
#> 8 Site8 2 site 0.8052930 1.2613124
#> 9 Site9 3 site 0.7981859 1.2421180
#> 10 Site10 4 site 0.7933884 NaN
#> 11 Site11 2 site 0.8015123 1.2613124
#> 12 Site12 4 site 0.7768595 NaN
#> 13 Site13 6 site 0.7777778 -1.4142136
#> 14 Site14 5 site 0.8057851 0.5400617
#> 15 Site15 6 site 0.8140496 0.0000000
#> 16 Site16 2 site 0.8016529 1.2613124
#> 17 Site17 1 site 0.8016529 -0.2145988
#> 18 Site18 5 site 0.8055556 -1.6201852
#> 19 Site19 1 site 0.7981859 1.5021914
#> 20 Site20 3 site 0.7851240 1.2421180
#> 21 Species1 1 species 0.8310249 -0.2145988
#> 22 Species2 2 species 0.8300000 -0.7207500
#> 23 Species3 6 species 0.8177778 0.0000000
#> 24 Species4 3 species 0.8281250 -0.2070197
#> 25 Species5 5 species 0.8209877 0.5400617
#> 26 Species6 2 species 0.8271605 -0.7207500
#> 27 Species7 2 species 0.8148148 -0.7207500
#> 28 Species8 1 species 0.8088889 -1.0729938
#> 29 Species9 2 species 0.8300000 -0.7207500
#> 30 Species10 1 species 0.8254848 -1.0729938
#> 31 Species11 3 species 0.8209877 -1.6561573
#> 32 Species12 5 species 0.8271605 0.5400617
#> 33 Species13 5 species 0.8281250 -1.6201852
#> 34 Species14 6 species 0.8148148 1.4142136
#> 35 Species15 2 species 0.8254848 -0.7207500
#> 36 Species16 3 species 0.8310249 -0.2070197
#> 37 Species17 4 species 0.8209877 NaN
#> 38 Species18 2 species 0.8271605 -0.7207500
#> 39 Species19 4 species 0.8203125 NaN
#> 40 Species20 4 species 0.8166090 NaN
#> 41 Species21 3 species 0.8271605 -0.2070197
#> 42 Species25 1 species 0.8271605 -0.2145988
#> 43 Species23 1 species 0.8088889 -0.2145988
#> 44 Species24 2 species 0.8088889 -0.7207500
#> 45 Species22 5 species 0.8203125 0.5400617