ProgInRBCIfunc: species_richness_1

#' ---
#' title: 04 run function to produce multiple values for Dq based on values for q
#' author: Edie Bishop
#' ---

#' # Introduction
#' In this script we will use the function multi_q_diversity4, which takes a series of $q$ values as a vector,
#' then passes them one by one to the universal_diversity4 function, and stores each returned value of $Dq$
#' as a vector. This is useful, as we can this way build up a "diversity profile" for a given population,
#' and examine different characteristics of the population based on calculations of diversity. At $q = 0$ we
#' dont care at all about the eveness of the distribution of species, and the
#' rarest species counts just as much as the most common, whereas at $q = \infty$, we only care about the
#' eveness, and not about the actual number of species present. So for populations with an uneven distribution
#' of species, we would expect that the diversity values will decrease with increasing values of $q$.
#'
#' We will use the script "create_datasets.R" in this project, which creates a number of vector
#' files, which contain populations generated from the BCI_2010 dataset (which we obtained from the BCI
#' package) to create test population. .
#'
#'
#'
#' # Load required packages and scripts

# The ProgInRBCIfunc function contains functions which calculate various indices of diversity
library(ProgInRBCIfunc)
library(tidyr)
library(ggplot2)
# the "create_datasets" script produces a list of populations
devtools::wd(".", "Run_Scripts")
source("create_datasets.R")

#' First lets specify some values for q. To demonstrate the point, we will set values of q ranging from
#' 0 to ten, in 0.5 increments.
q <- seq(0, 10, by = 0.5)

#' Then we will use our new multi_q_diversity4 function to calculate diversity values for each value of
#' q, for each population.
tree.popDq <- multi_q_diversity4(tree.pop, q)

quadrat.popDq <- multi_q_diversity4(quadrat.pop, q)

quadrat10.popDq <- multi_q_diversity4(quadrat10.pop, q)

one.popDq <- multi_q_diversity4(one.pop, q)

uneven.popDq <- multi_q_diversity4(uneven.pop, q)

mixed.popDq <- multi_q_diversity4(mixed.pop, q)

even.popDq <- multi_q_diversity4(even.pop, q)

rand.popDq <- multi_q_diversity4(rand.pop, q)

rand50.popDq <- multi_q_diversity4(rand50.pop, q)

#' Now that we have vectors of diversity values for each population, I will put them all into a dataframe
#' so that they can be easily plotted using ggplot. cbind will simply bind each vector to the df.Dq.values
#' dataframe as a new column.
df.Dq.values <- as.data.frame(q)
df.Dq.values <- cbind(df.Dq.values, tree.popDq)
df.Dq.values <- cbind(df.Dq.values, quadrat.popDq)
df.Dq.values <- cbind(df.Dq.values, quadrat10.popDq)
df.Dq.values <- cbind(df.Dq.values, one.popDq)
df.Dq.values <- cbind(df.Dq.values, uneven.popDq)
df.Dq.values <- cbind(df.Dq.values, mixed.popDq)
df.Dq.values <- cbind(df.Dq.values, even.popDq)
df.Dq.values <- cbind(df.Dq.values, rand.popDq)
df.Dq.values <- cbind(df.Dq.values, rand50.popDq)

#' Now the diversity measures for each population exist as a separate column within our dataframe. However,
#' this is not a particularly useful way to organise this data, so we transform the dataframe so that it
#' contains three columns: q, Population and Dq.
df.Dq.useful <- gather(df.Dq.values, Population, Dq, 2:10)

#' Then we can easily plot the diversity (Dq) values for each population against q, so that we can examine
#' how the diversity values change for different populations by varying the value of q.
ggplot(data = df.Dq.useful, aes(x = q, y = Dq, col = Population)) +
  geom_line(size = 0.7) +
  geom_point() +
  theme_bw()

#' ## Conclusion
#' It can be seen from the graph that populations which have a highly even distribution of species (even.pop
#' and rand.pop) show little (or no) change in diversity value for changing values of q. This is because
#' each species in the population is equally (or almost equally) abundant. On the other hand, populations
#' which are very uneven in their species abundances show a steep decline in diversity measures with increasing
#' values of q, such as uneven.pop and tree.pop. One.pop shows zero diversity across all measures for q,
#' which is good as there is only one species in this population, so no diversity! Other populations
#' show curves somwhere in between.