# Other functions of interest

    library(funrar)

In addition to single index functions `funrar` proposes several functions to help you compute functional rarity indices. The aim of this vignette is to provide detailed examples of how to use each of them.

In this vignette we will use the dataset `aravo` (you can learn more about it through `help("aravo", package = "ade4")`) from the `ade4` package as for the “Getting Started” vignette:

    data("aravo", package = "ade4")

    # Extract the traits of all species of `aravo`
    traits = aravo$traits

    head(traits)
    #>           Height Spread Angle  Area Thick  SLA N_mass Seed
    #> Agro.rupe      6     10    80  60.0  0.12  8.1 218.70 0.08
    #> Alop.alpi      5     20    20 190.9  0.20 15.1 203.85 0.21
    #> Anth.nipp     15      5    50 280.0  0.08 18.0 219.60 0.54
    #> Heli.sede      0     30    80 600.0  0.20 10.6 233.20 1.72
    #> Aven.vers     12     30    60 420.0  0.14 12.5 156.25 1.17
    #> Care.rosa     30     20    80 180.0  0.40  6.5 208.65 1.68

## Compute Distinctiveness from Global Pool - `distinctiveness_global()`

While functional distinctiveness has been envisioned initially at local scale, that’s what the `distinctiveness()` function computes, it can be useful to compute it at regional scales. This functions provides exactly that based on a provided functional dissimilarity matrix.

Using the `aravo` dataset we can compute the global distinctiveness of all species across the dataset in the following way:

    # Compute a Euclidean distance matrix (because all traits are quantitative)
    dist_matrix = compute_dist_matrix(traits, metric = "euclidean")

    # Compute global distinctiveness
    global_di = distinctiveness_global(dist_matrix)

    head(global_di)
    #>     species global_di
    #> 1 Agro.rupe  248.7796
    #> 2 Alop.alpi  231.9763
    #> 3 Anth.nipp  248.7366
    #> 4 Heli.sede  444.0815
    #> 5 Aven.vers  330.0033
    #> 6 Care.rosa  233.4236

The global distinctiveness is available in column `global_di`. You can rename this column using the second argument of `distinctiveness_global()`:

    aravo_di = distinctiveness_global(dist_matrix, di_name = "aravo_di")

    head(aravo_di)
    #>     species aravo_di
    #> 1 Agro.rupe 248.7796
    #> 2 Alop.alpi 231.9763
    #> 3 Anth.nipp 248.7366
    #> 4 Heli.sede 444.0815
    #> 5 Aven.vers 330.0033
    #> 6 Care.rosa 233.4236

NB: `distinctiveness_global()` assumes that all species in the provided trait dataset are present at global/regional scale. It also assumes only a presence-absence matrix.

## Compute functional rarity indices across combinations of traits

Distinctiveness is generally computed through a dissimilarity matrix that itself comes from aggregating differences across multiple traits. Sometimes it can be useful to compare it to distinctiveness computed on each trait separately. This way, it is possible that some species appear distinct on certain traits and not others. The two functions below let you do exactly that for distinctiveness and uniqueness.

### Compare Distinctiveness computed on all traits and each trait - `distinctiveness_dimensions()`

The function `distinctiveness_dimensions()` computes species local distinctiveness values from a site-species matrix and a trait data.frame. It will return a data frame with distinctiveness computed from all traits taken together and each trait taken separately.

Let’s do this with the traits from the `aravo` dataset. The first argument of `distinctiveness_dimensions()` is supposed to be site-species matrix while the second should be a traits table:

    di_dim = distinctiveness_dimensions(as.matrix(aravo$spe), traits, metric = "euclidean")

    str(di_dim, max.level = 1)
    #> List of 9
    #>  $ di_Height: num [1:75, 1:82] NA NA 5.6 NA NA ...
    #>   ..- attr(*, "dimnames")=List of 2
    #>  $ di_Spread: num [1:75, 1:82] NA NA 9.35 NA NA ...
    #>   ..- attr(*, "dimnames")=List of 2
    #>  $ di_Angle : num [1:75, 1:82] NA NA 31.5 NA NA ...
    #>   ..- attr(*, "dimnames")=List of 2
    #>  $ di_Area  : num [1:75, 1:82] NA NA 218 NA NA ...
    #>   ..- attr(*, "dimnames")=List of 2
    #>  $ di_Thick : num [1:75, 1:82] NA NA 0.16 NA NA ...
    #>   ..- attr(*, "dimnames")=List of 2
    #>  $ di_SLA   : num [1:75, 1:82] NA NA 4.44 NA NA ...
    #>   ..- attr(*, "dimnames")=List of 2
    #>  $ di_N_mass: num [1:75, 1:82] NA NA 39.5 NA NA ...
    #>   ..- attr(*, "dimnames")=List of 2
    #>  $ di_Seed  : num [1:75, 1:82] NA NA 0.755 NA NA ...
    #>   ..- attr(*, "dimnames")=List of 2
    #>  $ di_all   : num [1:75, 1:82] NA NA 240 NA NA ...
    #>   ..- attr(*, "dimnames")=List of 2

We see that it returns a list of 9 local distinctiveness matrices: one for each trait and one for all traits taken together (named `di_all`).

### Compare Uniqueness computed on all traits and each trait - `uniqueness_dimensions()`

The function `uniqueness_dimensions()` computes species regional uniqueness values from a site-species matrix and a trait data.frame. It will return a data frame with uniqueness computed from all traits taken together and each trait taken separately.

Let’s do this with the traits from the `aravo` dataset. The first argument of `uniqueness_dimensions()` is supposed to be site-species matrix while the second should be a traits table:

    ui_dim = uniqueness_dimensions(as.matrix(aravo$spe), traits, metric = "euclidean")

    str(ui_dim, max.level = 1)
    #> 'data.frame':    82 obs. of  10 variables:
    #>  $ species  : chr  "Agro.rupe" "Alch.glau" "Alch.pent" "Alch.vulg" ...
    #>  $ Ui_Height: num  1 0 0 0 0 0 0 0 0 0 ...
    #>  $ Ui_Spread: num  0 0 0 0 0 0 0 0 0 0 ...
    #>  $ Ui_Angle : num  0 0 0 0 0 0 0 0 0 0 ...
    #>  $ Ui_Area  : num  0 9.8 2.4 170.7 7.9 ...
    #>  $ Ui_Thick : num  0 0 0 0 0 0 0 0 0 0 ...
    #>  $ Ui_SLA   : num  0 0.1 0.5 0.5 0.1 ...
    #>  $ Ui_N_mass: num  0.3 0.34 2.52 8.41 0.52 ...
    #>  $ Ui_Seed  : num  0 0 0 0 0 ...
    #>  $ Ui_all   : num  14.1 23.1 56.9 180 28.7 ...

We see that it returns a data frame with 10 columns: one for species names, one for each trait separately, and one for all traits taken together (named `Ui_all`).

## Compute Relative Abundances - `make_relative()`

This function, probably largest source of citations of `funrar`, transforms a matrix of absolute abundances to relative abundances. It takes an abundance matrix and returns the same matrix with relative abundances.

We can check that with `aravo` site-species matrix:

    aravo_site_sp = as.matrix(aravo$spe)

    # There are clearly abundances and not only presence-absence in this table
    aravo_site_sp[1:5, 1:5]
    #>      Agro.rupe Alop.alpi Anth.nipp Heli.sede Aven.vers
    #> AR07         0         0         0         0         0
    #> AR71         0         0         0         0         0
    #> AR26         3         0         1         0         1
    #> AR54         0         0         0         2         0
    #> AR60         0         0         0         0         0

    # Compute total abundance per site
    site_abundance = rowSums(aravo_site_sp)

    head(site_abundance)
    #> AR07 AR71 AR26 AR54 AR60 AR70
    #>   15   23   37   23   13   32

    # Compute a relative abundance matrix
    relative_site_sp = make_relative(aravo_site_sp)

    relative_site_sp[1:5, 1:5]
    #>       Agro.rupe Alop.alpi  Anth.nipp  Heli.sede  Aven.vers
    #> AR07 0.00000000         0 0.00000000 0.00000000 0.00000000
    #> AR71 0.00000000         0 0.00000000 0.00000000 0.00000000
    #> AR26 0.08108108         0 0.02702703 0.00000000 0.02702703
    #> AR54 0.00000000         0 0.00000000 0.08695652 0.00000000
    #> AR60 0.00000000         0 0.00000000 0.00000000 0.00000000

    rel_site_abundance = rowSums(relative_site_sp)

    head(rel_site_abundance)
    #> AR07 AR71 AR26 AR54 AR60 AR70
    #>    1    1    1    1    1    1

We see, through `rel_site_abundance`, that `make_relative()` transformed the abundances in each site so that they all sum to one. It divides the abundance of each species by the total abundance of the site.