Skip to contents

This function calculates metrics that assess the contribution of a given species or site to its bioregion.

Usage

site_species_metrics(
  cluster_object,
  comat,
  indices = c("rho"),
  bipartite_link = NULL
)

Arguments

cluster_object

a bioregion.clusters object or a data.frame or a list of data.frame containing multiple partitions. At least two partitions are required. If a list of data.frame is provided, they should all have the same number of rows (i.e., same items in the clustering for all partitions).

comat

a co-occurrence matrix with sites as rows and species as columns.

indices

a character specifying the contribution metric to compute. Available options are rho and Cz.

NULL by default. Needed for Cz indices. A data.frame where each row represents the interaction between two nodes and an optional third column indicating the weight of the interaction.

Value

A data.frame with the columns Bioregion, Species, and the desired summary statistics, or a list of data.frames if Cz and other indices are selected.

Details

The \(\rho\) metric is derived from Lenormand et al. (2019). Its formula is the following:

\(\rho_{ij} = (n_ij - ((n_i n_j)/n))/(sqrt(((n - n_j)/(n-1)) (1-(n_j/n)) ((n_i n_j)/n)))\)

with \(n\) the number of sites, \(n_i\) the number of sites in which species \(i\) is present, \(n_j\) the number of sites belonging to the bioregion \(j\), \(n_ij\) the number of occurrences of species \(i\) in sites belonging to the bioregion \(j\).

Affinity, fidelity and individual contributions 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 = R_i / Z\) where \(R_i\) is the occurrence/range size of species \(i\) in its associated bioregion, and \(Z\) the total size (number of sites) of the bioregion.

A high affinity means that the species is occupying most sites of its associated bioregion.

Fidelity of species to their region, \(F_i = R_i / D_i\) where \(R_i\) is the occurrence/range size of species \(i\) in its associated bioregion, and \(D_i\) is its total occurrence/range size.

A high fidelity means that the species is not present in other bioregions than their associated one.

Indicator Value of species, \(IndVal = F_i * A_i\)

Cz metrics are derived from Guimerà & Amaral (2005). Their respective formula are: \(C_i = 1 - \sum_{s=1}^{N_M}{{(\frac{k_is}{k_i}})^2}\)

where \(k_{is}\) is the number of links of node (species or site) \(i\) to nodes in bioregion \(s\), and \(k_i\) is the total degree of node \(i\). The participation coefficient of a node is therefore close to 1 if its links are uniformly distributed among all the bioregions and 0 if all its links are within its own bioregion.

And: \(z_i = \frac{k_i - \overline{k_{si}}}{\sigma_{k_{si}}}\)

where \(k_i\) is the number of links of node (species or site) \(i\) to other nodes in its bioregion \(s_i\), \(\overline{k_{si}}\) is the average of \(k\) over all the nodes in \(s_i\), and \(\sigma_{k_{si}}\) is the standard deviation of \(k\) in \(s_i\). The within-bioregion degree z-score measures how well-connected node \(i\) is to other nodes in the bioregion.

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.

Author

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

Examples

comat <- matrix(sample(1000, 50), 5, 10)
rownames(comat) <- paste0("Site", 1:5)
colnames(comat) <- paste0("Species", 1:10)

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)

dissim <- dissimilarity(comat, metric = "Simpson")
clust1 <- nhclu_kmeans(dissim, n_clust = 3, index = "Simpson")

net <- similarity(comat, metric = "Simpson")
com <- netclu_greedy(net)

site_species_metrics(cluster_object = clust1, comat = comat,
indices = "rho")
#>    Bioregion   Species          rho
#> 1          1  Species1  374.9216546
#> 2          1  Species2  393.6970352
#> 3          1  Species3  518.4183810
#> 4          1  Species4  888.1110005
#> 5          1  Species5  291.1744494
#> 6          1  Species6  354.4032090
#> 7          1  Species7  744.4999396
#> 8          1  Species8   56.0551316
#> 9          1  Species9  144.2525563
#> 10         1 Species10  364.2051045
#> 11         1 Species11    0.8388705
#> 12         1 Species12   50.5415121
#> 13         1 Species13  511.1651397
#> 14         1 Species14  541.2719793
#> 15         1 Species15  323.7208949
#> 16         1 Species16  241.0481280
#> 17         1 Species17  362.9799505
#> 18         1 Species18  433.5474871
#> 19         1 Species19   -1.0419761
#> 20         1 Species20  181.2903748
#> 21         1 Species21  218.2741022
#> 22         1 Species22  274.6903926
#> 23         1 Species23  600.6078588
#> 24         1 Species24  218.3281933
#> 25         1 Species25   86.6863510
#> 26         2  Species1  135.9285995
#> 27         2  Species2  216.4925262
#> 28         2  Species3  468.0833222
#> 29         2  Species4  121.0919072
#> 30         2  Species5  908.5985469
#> 31         2  Species6  400.0500586
#> 32         2  Species7 1003.3638821
#> 33         2  Species8  375.2285507
#> 34         2  Species9  842.8551896
#> 35         2 Species10  583.8326462
#> 36         2 Species11 1336.3184899
#> 37         2 Species12  420.6337481
#> 38         2 Species13  680.8259792
#> 39         2 Species14 1048.3356564
#> 40         2 Species15  778.2244191
#> 41         2 Species16  794.5523198
#> 42         2 Species17  219.0346719
#> 43         2 Species18  742.6859591
#> 44         2 Species19  989.4664121
#> 45         2 Species20  405.5670713
#> 46         2 Species21 1258.0626180
#> 47         2 Species22 1094.0321098
#> 48         2 Species23 1017.8802115
#> 49         2 Species24  487.1171315
#> 50         2 Species25  715.4648294
#> 51         3  Species1 1375.1993367
#> 52         3  Species2  186.8598206
#> 53         3  Species3  250.5080552
#> 54         3  Species4  350.9651533
#> 55         3  Species5 1071.1769781
#> 56         3  Species6   62.5496455
#> 57         3  Species7 1212.8670545
#> 58         3  Species8  999.8982019
#> 59         3  Species9  106.0742296
#> 60         3 Species10  114.3719794
#> 61         3 Species11  347.3431969
#> 62         3 Species12  857.1153434
#> 63         3 Species13 1271.3271163
#> 64         3 Species14  232.8056867
#> 65         3 Species15  760.5923305
#> 66         3 Species16 1978.4114227
#> 67         3 Species17 1024.3923325
#> 68         3 Species18  436.4946197
#> 69         3 Species19 1314.2395173
#> 70         3 Species20  118.7473753
#> 71         3 Species21  166.7181901
#> 72         3 Species22   91.0119406
#> 73         3 Species23 1509.7354762
#> 74         3 Species24  891.1756062
#> 75         3 Species25  211.9041000

# Contribution metrics
site_species_metrics(cluster_object = com, comat = comat,
indices = c("rho", "affinity", "fidelity", "indicator_value"))
#>    Bioregion   Species           rho  affinity     fidelity       indval
#> 1          1  Species1 12155.1579199 132.73684 148.35294118 1.969190e+04
#> 2          1  Species2  6193.9953988  72.00000  72.00000000 5.184000e+03
#> 3          1  Species3  9360.1805538 111.15789 105.60000000 1.173827e+04
#> 4          1  Species4 10549.8702633 104.57895 141.92857143 1.484274e+04
#> 5          1  Species5 17016.4773088 201.26316 191.20000000 3.848152e+04
#> 6          1  Species6  6335.2053549  71.63158  75.61111111 5.416143e+03
#> 7          1  Species7 20969.8454930 247.78947 235.40000000 5.832964e+04
#> 8          1  Species8  8621.5172807  97.15789 102.55555556 9.964082e+03
#> 9          1  Species9  8494.0000000  90.21053 107.12500000 9.663803e+03
#> 10         1 Species10  8240.6329319  90.26316 100.88235294 9.105960e+03
#> 11         1 Species11 13156.5244271 134.84211 170.80000000 2.303103e+04
#> 12         1 Species12  9201.3448413 103.63158 109.38888889 1.133614e+04
#> 13         1 Species13 19087.1596423 219.89474 219.89473684 4.835370e+04
#> 14         1 Species14 14169.0000000 149.94737 178.06250000 2.670000e+04
#> 15         1 Species15 10983.5659055 130.26316 123.75000000 1.612007e+04
#> 16         1 Species16 19119.2778450 220.26316 220.26315789 4.851586e+04
#> 17         1 Species17 11676.2185755 131.26316 138.55555556 1.818724e+04
#> 18         1 Species18 10598.0792072 115.84211 129.47058824 1.499815e+04
#> 19         1 Species19 13329.3871791 131.94737 179.07142857 2.362800e+04
#> 20         1 Species20  4859.0000000  51.94737  61.68750000 3.204503e+03
#> 21         1 Species21 12795.0459814 131.15789 166.13333333 2.178970e+04
#> 22         1 Species22 11272.3282448 123.15789 137.64705882 1.695232e+04
#> 23         1 Species23 24437.1345562 281.26316 281.26315789 7.910896e+04
#> 24         1 Species24 12504.0000000 132.42105 157.25000000 2.082321e+04
#> 25         1 Species25  7791.8453242  87.89474  92.77777778 8.154678e+03
#> 26         2  Species1   605.5463183 545.00000  32.05882353 1.747206e+04
#> 27         2  Species2    -1.0000000   0.00000   0.00000000 0.000000e+00
#> 28         2  Species3    57.4547877  57.00000   2.85000000 1.624500e+02
#> 29         2  Species4    -0.8583951   0.00000   0.00000000 0.000000e+00
#> 30         2  Species5   172.3643632 169.00000   8.45000000 1.428050e+03
#> 31         2  Species6     0.1081476   1.00000   0.05555556 5.555556e-02
#> 32         2  Species7   491.4436306 480.00000  24.00000000 1.152000e+04
#> 33         2  Species8   601.4088819 557.00000  30.94444444 1.723606e+04
#> 34         2  Species9     3.6706517   4.00000   0.25000000 1.000000e+00
#> 35         2 Species10     2.3925840   3.00000   0.17647059 5.294118e-01
#> 36         2 Species11    -0.8885233   0.00000   0.00000000 0.000000e+00
#> 37         2 Species12   281.2919442 261.00000  14.50000000 3.784500e+03
#> 38         2 Species13    41.1052632  40.00000   2.10526316 8.421053e+01
#> 39         2 Species14    -0.9176629   0.00000   0.00000000 0.000000e+00
#> 40         2 Species15   818.7307250 799.00000  39.95000000 3.192005e+04
#> 41         2 Species16  1040.0526316 989.00000  52.05263158 5.148005e+04
#> 42         2 Species17   207.7515667 193.00000  10.72222222 2.069389e+03
#> 43         2 Species18   450.8629806 406.00000  23.88235294 9.696235e+03
#> 44         2 Species19  1086.8507932 887.00000  63.35714286 5.619779e+04
#> 45         2 Species20   144.7613281 127.00000   7.93750000 1.008062e+03
#> 46         2 Species21    -0.8885233   0.00000   0.00000000 0.000000e+00
#> 47         2 Species22    17.9722008  17.00000   1.00000000 1.700000e+01
#> 48         2 Species23     5.3157895   6.00000   0.31578947 1.894737e+00
#> 49         2 Species24     0.2294157   1.00000   0.06250000 6.250000e-02
#> 50         2 Species25    27.1450511  26.00000   1.44444444 3.755556e+01

# Cz indices
net_bip <- mat_to_net(comat, weight = TRUE)
clust_bip <- netclu_greedy(net_bip, bipartite = TRUE)
site_species_metrics(cluster_object = clust_bip, comat = comat, 
bipartite_link = net_bip, indices = "Cz")
#> Warning: Column 'Node1' has been renamed 'Sites'. If this column does not
#>             correspond to sites, rename it before running the function.
#> Warning: Column 'Node2' has been renamed 'Species'. If this column does not
#>             correspond to species, rename it before running the function.
#>         Node Bioregion Category         C          z
#> 1      Site1         1     site 0.8200000  1.0540926
#> 2      Site2         3     site 0.8181818  1.3333333
#> 3      Site3         5     site 0.8310249  1.0954451
#> 4      Site4         3     site 0.8194444  1.3333333
#> 5      Site5         3     site 0.8125000  1.3333333
#> 6      Site6         6     site 0.8099174 -1.2909944
#> 7      Site7         1     site 0.8015123  1.0540926
#> 8      Site8         4     site 0.8194444        NaN
#> 9      Site9         2     site 0.8050000  0.7745967
#> 10    Site10         2     site 0.7981859  0.7745967
#> 11    Site11         6     site 0.7936508  0.6454972
#> 12    Site12         5     site 0.8166352  1.0954451
#> 13    Site13         2     site 0.8208617 -1.1618950
#> 14    Site14         1     site 0.8057851  1.0540926
#> 15    Site15         2     site 0.8128544 -1.1618950
#> 16    Site16         4     site 0.8250000        NaN
#> 17    Site17         4     site 0.8241966        NaN
#> 18    Site18         6     site 0.8208617  0.6454972
#> 19    Site19         2     site 0.8099174  0.7745967
#> 20    Site20         1     site 0.7755102  1.0540926
#> 21  Species1         2  species 0.8166090 -1.1618950
#> 22  Species2         3  species 0.8254848 -0.6666667
#> 23  Species3         3  species 0.8200000 -0.6666667
#> 24  Species4         5  species 0.8163265 -0.7302967
#> 25  Species5         1  species 0.8200000 -0.8432740
#> 26  Species6         1  species 0.8086420 -0.8432740
#> 27  Species7         1  species 0.8200000 -0.8432740
#> 28  Species8         2  species 0.8086420  0.7745967
#> 29  Species9         4  species 0.8125000        NaN
#> 30 Species10         5  species 0.8235294 -0.7302967
#> 31 Species11         3  species 0.8088889 -0.6666667
#> 32 Species13         6  species 0.8254848  0.6454972
#> 33 Species14         5  species 0.8203125 -0.7302967
#> 34 Species15         4  species 0.8200000        NaN
#> 35 Species16         2  species 0.8088643  0.7745967
#> 36 Species17         1  species 0.8024691 -0.8432740
#> 37 Species20         3  species 0.8046875 -0.6666667
#> 38 Species22         4  species 0.8235294        NaN
#> 39 Species23         6  species 0.8254848  0.6454972
#> 40 Species25         1  species 0.8148148 -0.8432740
#> 41 Species12         3  species 0.8148148 -0.6666667
#> 42 Species18         2  species 0.8027682  0.7745967
#> 43 Species21         3  species 0.8177778 -0.6666667
#> 44 Species24         6  species 0.8046875 -1.2909944
#> 45 Species19         2  species 0.7857143 -1.1618950