Time series metrics

library(ggplot2)
library(dplyr)

Background

Here we will use the same data processed in the article xXXXX.

Loading data and packages

data("df_TS_TE_faurby")
data("df_TS_TE_mass")
data("df_occ_faurby")

Clade level analysis

Calculating time series at clade level

regional_richness <- 
  regional_clade_richness(df.TS.TE = df_TS_TE_faurby,
                          time.slice = 0.1,
                          round.digits = 1,
                          species = "species",
                          TS = "TS",
                          TE = "TE")

Plotting the results

regional_richness |> 
  mutate(time.slice = as.numeric(time.slice)) |> 
  ggplot(aes(x = time.slice, y = richness)) +
  geom_smooth(se = TRUE, method = "loess", size = 1) +  # Line thickness for better visibility
  geom_point(aes(x = time.slice, y = richness)) +
  labs(title = "",
       x = "Tempo",
       y = "Riqueza") +
  scale_x_continuous(breaks = seq(max(as.numeric(regional_richness$time.slice)), 0, by = -10)) +
  scale_x_reverse() +
  theme_minimal() +
  theme(legend.position = "none")# Use a clean theme

regional clade trait distances

Here we calculate the mean distances using a general function that allows to set up the group comparison in which the mean will be calculate. It can be between to calculate mean distances between a focal and a target group or within to calculate the mean trait distance only within the focal group

This function is also a general solution to calculate the mean trait distance using different number of species/genus that are close to each other. This is set up in the argument nearest.taxon. 1 is equivalent of mnnd.

Calculating comparing mpd between and within groups using a distance matrix and a distance threshold (1 = mnnd)

dist_body_mass <- dist(df_TS_TE_mass$mean.size)

# distances between groups using as focal group Caniformia
regional_mnd_between <- 
  clade_regional_distance(df.TS.TE = df_TS_TE_mass, 
                          time.slice = 0.1,
                          dist.trait = dist_body_mass,
                          nearest.taxon = 1, 
                          round.digits = 1, 
                          species = "species", 
                          TS = "TS", 
                          TE = "TE", 
                          group = "group", 
                          group.focal.compare = c("Caniformia", "Feliformia"), 
                          type.comparison = "between")

# distance within the focal group, in this case is Caniformia
regional_mnd_within <- 
  clade_regional_distance(df.TS.TE = df_TS_TE_mass, 
                          time.slice = 0.1,
                          dist.trait = dist_body_mass,
                          nearest.taxon = 1, 
                          round.digits = 1, 
                          species = "species", 
                          TS = "TS", 
                          TE = "TE", 
                          group = "group", 
                          group.focal.compare = c("Caniformia", "Feliformia"), 
                          type.comparison = "within")

Joining all results to plot in one graphic

all_mnd_regional <- rbind(regional_mnd_between, regional_mnd_within)
all_mnd_regional2 <- data.frame(all_mnd_regional, group_res = rep(c("Between", "Within"), each = nrow(regional_mnd_within)))

Plotting mpd results

all_mnd_regional2 |> 
  mutate(time.slice.numeric = as.numeric(unlist(lapply(strsplit(time.slice, "_"), function(x) x[2])))) |> 
  ggplot(aes(x = time.slice.numeric, y = mean.distance, color = group_res)) +
  geom_point(aes(x = time.slice.numeric, y = mean.distance)) +
  geom_smooth(se = TRUE, method = "loess", size = 1) +  # Line thickness for better visibility
  labs(title = "",
       x = "Time",
       y = "Mean Distance") +
  scale_x_continuous(breaks = seq(40, 0, by = -10)) +
  xlim(40, 0) +
  theme_minimal() +
  theme(legend.position = "bottom")# Use a clean theme

Clade site richness

site_richness <- 
  clade_site_richness(df.TS.TE = df_TS_TE_faurby, 
                      df.occ = df_occ_faurby, 
                      time.slice = 0.1, 
                      round.digits = 1,
                      species = "species",
                      TS = "TS",
                      TE = "TE")

Plotting the results

site_richness |> 
  ggplot(aes(x = as.numeric(time.slice), y = mean.richness.site)) +
  geom_point(aes(x = as.numeric(time.slice), y = mean.richness.site)) +
  geom_smooth(se = TRUE, method = "loess", size = 1) +  # Line thickness for better visibility
  labs(title = "",
       x = "Time",
       y = "Mean site richness") +
  scale_x_continuous(breaks = seq(max(as.numeric(site_richness$time.slice)), 0, by = -10)) +
  scale_x_reverse() +
  theme_minimal() +
  theme(legend.position = "none")# Use a clean theme

Individual species analysis

In individual species analyses the focus is on the “perception” of each individual species with other co-occurring species. There are two main components in this module. The first computes the number of species in which a given species co-occur. The other is the mean distance between a focal individual and its co-occurring species.

As the other modules there are four spatial levels in which we compute the metrics. The regional level, that calculates the number of co-occurrence by each focal species and all other species with occurrence data in the specified time-slice. The site level, that compute the taxonomic and trait metrics considering as co-existing species only those that present occurrence in the same site (usually defined accordingly to the PBDB definition of a site, or another definition provided by the user). The reach level, that considers a proxy of species dispersal capacity to infer the species that potentially co-occurr. Finally, the assemblage level, that considers as species co-occurring only those with an occurrence record in the same assemblage, this last being defined as a grid of customized size.

Individual species regional coexistence - taxonomic

indiv_species_coex <- 
  IndivSpecies_regional_richness(df.TS.TE = df_TS_TE_faurby, 
                                 time.slice = 0.1,
                                 round.digits = 1,
                                 species = "species",
                                 TS = "TS",
                                 TE = "TE")

This output contain two data frames, one with all individual coexistences per species in all time slices, and another containing the mean species coexistence considering all time slices

df_mean_individual_species <- indiv_species_coex$mean_species_coexistence
df_indiv_species_long <- indiv_species_coex$df_IndivSpp_coexist

We can plot the results of all time mean species coexistence for three species

df_indiv_species_long |> 
  filter(species == "Canis" | species == "Ursus" | species == "Ursavus") |> 
  ggplot(aes(x = species, y = n.coexistence, fill = species)) +
  geom_violin(trim = FALSE) +  # Line thickness for better visibility
  geom_point(aes(x = species, y = n.coexistence, fill = species), shape = 21) +
  labs(title = "",
       x = "Espécies",
       y = "Coexistência média") +
  theme_minimal() +
  theme(legend.position = "none", 
        panel.grid.major = element_line(linetype = "dashed"))# Use a clean theme

We can also plot the time series for each species

df_indiv_species_long |> 
  filter(species == "Canis" | species == "Ursavus" | species == "Ursus" | species == "Panthera") |> 
  ggplot(aes(x = time.slice, y = n.coexistence, color = species, group = species)) +  # Line thickness for better visibility
  geom_smooth(se = TRUE, method = "loess", size = 1) +
  geom_point(aes(x = time.slice, y = n.coexistence, color = species), shape = 21) +
  facet_wrap(~species) +
  labs(title = "",
       x = "Time",
       y = "number of coexistences by species") +
  theme_minimal()  +
  scale_x_continuous(breaks = seq(max(df_indiv_species_long$time.slice), 0, by = -10)) +
  scale_x_reverse() +
  theme(legend.position = "none")# Use a clean theme

Individual species regional mpd

We can also plot individual species mpd for all species coexisting in regional context. For this we will also use data on body mass for all species. There are different ways in which mpd can be calculated. We can calculate it using a single trait or a combination of traits. The later require a distance trait matrix (passed to dist argument) containing the pairwise distances among species.

Here we show how to calculate mpd using a single trait, in this case body mass.


df_TS_TE_mass2 <- 
  df_TS_TE_mass |> 
  filter(across(c(TS, TE), ~ !is.na(.)))

indiv_regional_species_mpd <-
  IndivSpecies_regional_mpd(df.TS.TE = df_TS_TE_mass, 
                            time.slice = 0.1, 
                            trait = "mean.size",
                            round.digits = 1, 
                            species = "species",
                            TS = "TS",
                            TE = "TE")

df_indiv_species_mpd_long <- indiv_regional_species_mpd

Plotting the results for individual species mpd

df_indiv_species_mpd_long |> 
  filter(species == "Canis" | species == "Ursavus" | species == "Ursus" | species == "Panthera") |> 
  ggplot(aes(x = time.slice, y = mpd, color = species, group = species)) +  # Line thickness for better visibility
  geom_point(aes(x = time.slice, y = mpd, color = species), shape = 21) +
  geom_smooth(se = TRUE, method = "loess", size = 1) +
  facet_wrap(~species) +
  labs(title = "",
       x = "Tempo",
       y = "Distância média (mpd)") +
  theme_minimal()  +
  scale_x_continuous(breaks = seq(max(df_indiv_species_mpd_long$time.slice), 0, by = -10)) +
  scale_x_reverse() +
  theme(legend.position = "none")# Use a clean theme

Individual species regional mpd with varying distances and multiple traits

In order to calculate the mpd for multiple traits the user must inform an object of class dist containing all pairwise distances among species. The function can handle distances in different ways. It can use all pairwise distances to obtain the mpd, or the user can inform throught the argument nearest.taxon the number of nearest species that will be used to calculate the mpd. The default is all which is the same as calculating the mpd considering all species co-occurring in a time slice.

IndivSpecies_regional_mpd(df.TS.TE = df_TS_TE_mass, 
                            time.slice = 0.1, 
                            trait = "mean.size",
                            round.digits = 1, 
                            species = "species",
                            TS = "TS",
                            TE = "TE")

Individual species site coexistence

Here we will perform the same calculations but using site criteria for individual species coexistence

indiv_species_site_coex <- 
  IndivSpec_site_richness(df.TS.TE = df_TS_TE_faurby,
                          df.occ = df_occ_faurby, 
                          time.slice = 0.1,
                          round.digits = 1,
                          species = "species",
                          TS = "TS",
                          TE = "TE",
                          Max.age = "Max.age",
                          Min.age = "Min.age",
                          site = "site")

indiv_species_site_coex2 <- 
  indiv_species_site_coex |> 
  mutate(time.slice = as.numeric(time.slice))

plotting species coexistence considering site coexistence

indiv_species_site_coex2 |> 
  filter(species == "Alopecocyon" | species == "Simocyon" | species == "Prepoecilogale" | species == "Vormela" | species == "Hesperocyon") |> 
  ggplot(aes(x = time.slice, y = mean.per.spp, color = species, group = species)) +  # Line thickness for better visibility
  geom_smooth(se = TRUE, method = "loess", size = 1) +
  facet_wrap(~species) +
  labs(title = "",
       x = "Time",
       y = "mean coexistence") +
  theme_minimal()  +
  scale_x_continuous(breaks = seq(max(indiv_species_site_coex2$time.slice), 0, by = -10)) +
  scale_x_reverse() +
  theme(legend.position = "none")

Individual species site mpd

We can calculate mean pairwise distances of individual species coexistence metrics based on site co-occurrence


df_TS_TE_mass3 <- 
  df_TS_TE_mass2 |> 
  rename(species = "Genus")


indiv_species_site_mpd <- 
  IndivSpec_site_mpd(df.TS.TE = df_TS_TE_mass3, 
                     df.occ = df_occ_faurby, 
                     time.slice = 0.1, 
                     trait = "mean.size",
                     round.digits = 1,
                     species = "species",
                     TS = "TS",
                     TE = "TE",
                     Max.age = "Max.age",
                     Min.age = "Min.age",
                     site = "site")

Individual reach coexistence

We will calculate individual mean coexistence using reach criteria


indiv_species_reach_coex <- 
  IndivSpec_reach_richness(df.TS.TE = df_TS_TE_faurby,
                           df.occ = df_occ_faurby,
                           time.slice = 0.1, 
                           round.digits = 1,
                           species = "species",
                           TS = "TS",
                           TE = "TE",
                           Max.age = "Max.age",
                           Min.age = "Min.age",
                           lat = "lat",
                           lon = "lng")

plotting individual species coexistence with reach criteria


indiv_species_reach_coex2 <- 
  indiv_species_reach_coex |> 
  mutate(time.slice = as.numeric(time.slice))

indiv_species_reach_coex2 |> 
  filter(species == "Ursus" | species == "Simocyon" | species == "Plionarctos" | species == "Vormela" | species == "Hesperocyon") |> 
  ggplot(aes(x = time.slice, y = n.coexistence, color = species, group = species)) +  # Line thickness for better visibility
  geom_smooth(se = TRUE, method = "loess", size = 1) +
  facet_wrap(~species) +
  labs(title = "",
       x = "Time",
       y = "mean coexistence") +
  theme_minimal()  +
  scale_x_continuous(breaks = seq(max(indiv_species_site_coex2$time.slice), 0, by = -10)) +
  scale_x_reverse() +
  theme(legend.position = "none")