small updates to vignettes

vignettes/V1_Getting_started.Rmd

@@ -46,7 +46,7 @@ obs_homa <- subset(obs_homa,select = -c(obs_ID))
 head(obs_homa)
 ```
 
-Next, we estimate both the reproduction success in the absence of neighbors (lambda) and the competition matrix (alpha). This is done by fitting a model that mathematically relates the reproductive success to the number of neighbors observed. In this first example, we fit the selected species with a Ricker model ('RK' model family, see vignette 4) and fairly standard initial values. The default optimization method (`Nelder-Mead`) does not allow for lower or upper bounds in model parameters, so these arguments are commented out. In ecological terms, this optimization process allow for estimating the strength of both competitive and facilitative interactions, yet bounded optimization algorithms can be used to restrict the analysis to either competition or facilitation (i.e. positive or negative alpha values). We can also specify whether we want to compute standard errors numerically, by setting the argument `bootstrap_samples` to the number of bootstrap replications for the calculation.
+Next, we estimate both the reproduction success in the absence of neighbors (lambda) and the competition matrix (alpha). This is done by fitting a model that mathematically relates the reproductive success to the number of neighbors observed. In this first example, we fit the selected species with a Ricker model ('RK' model family, see vignette 4) and fairly standard initial values. The default optimization method (`Nelder-Mead`) does not allow for lower or upper bounds in model parameters, so these arguments are commented out. In ecological terms, this optimization process allows estimating the strength of both competitive and facilitative interactions, yet bounded optimization algorithms can be used to restrict the analysis to either competition or facilitation (i.e. positive or negative alpha values). We can also specify whether we want to compute standard errors numerically, by setting the argument `bootstrap_samples` to the number of bootstrap replications for the calculation.
 
 ```{r}
 #?cxr_pm_fit #check the help file for a description of the arguments
@@ -98,7 +98,7 @@ Note that some interaction coefficients are set to NA because species do not coo
 
 **Fitting several species at once**
 
-Most likely users will want to fit model parameters to data from two or more focal species. In order to do that with a single call, we provide the function `cxr_pm_multifit`, which has a very similar interface to `cxr_pm_fit`. Here we show how multiple species can be fit using this function. For this multispecies case, rows correspond to species i and columns to species j for each $\alpha_{ij}$ coefficient. The diagonal correspond to the intraspecific cases. In order to showcase other capabilities of the package, we include in this example the effect of a covariate over the fitted lambda and alpha parameters. This covariate, soil salinity, is also included as a dataset in the package (see vignette 2). We consider that the covariate has a linear effect in both the modification of lambda and alpha parameters.
+Most likely users will want to fit model parameters to data from two or more focal species. In order to do that with a single call, we provide the function `cxr_pm_multifit`, which has a very similar interface to `cxr_pm_fit`. Here we show how multiple species can be fit using this function. For this multispecies case, rows in the alpha element of the returning list correspond to species i and columns to species j for each $\alpha_{ij}$ coefficient. The diagonal corresponds to intraspecific coefficients. In order to showcase other capabilities of the package, we include in this example the effect of a covariate over the fitted lambda and alpha parameters. This covariate, soil salinity, is also included as a dataset in the package (see vignette 2). We consider that the covariate has a linear effect in both the modification of lambda and alpha parameters.
 
 ```{r}
 my.sp <- c("BEMA","CETE","LEMA")
@@ -170,9 +170,9 @@ We can also have a glimpse of this multispecies fit with the summary function:
 summary(fit_3sp)
 ```
 
-The numerical estimation of parameters depends on the model with which to estimate fitness values, the optimization method, and the underlying data. In our example dataset, some species are better represented than others, and the function will raise warnings if the estimation can be improved or, for example, if any fitted parameter is equal to the lower or upper bounds provided. The `cxr_pm_multifit` function will behave conservatively and return `NULL` if parameter fitting fails for *any* of the focal species passed as arguments, printing an informative message about which species failed to fit.
+The numerical estimation of parameters depends on the model with which to estimate fitness values, the optimization method, and the underlying data. In our example dataset, some species are better represented than others, and the function will raise warnings if the estimation can be improved or, for example, if any fitted parameter is equal to the lower or upper bounds provided. The `cxr_pm_multifit` function will behave conservatively and return `NULL` if parameter fitting fails for *any* of the focal species passed as arguments, printing an informative message about which species failed to fit. In such cases, users may either fit each species separately or call `cxr_pm_multifit` without the problematic species.
 
-Importantly, bounded methods can be very sensitive to the initial values and bounds, so, as in any numerical optimization problem, you should double-check the values obtained, at least by computing standard errors on your parameters with an adequate number of boostrap samples, and preferably by performing sensitivity analyses on the different parameters (in this and other vignettes, we have not included any of these checks, as our examples are merely for demonstration purposes). Aside from these recommendations, in the `cxr` objects returned from our functions, the negative log-likelihood of the fit is also included, which may be useful in helping users choose a certain optimization algorithm for a particular dataset. Remember that the convention is to present negative log-likelihood, and more negative values are better. In general, it is recommended to test different optimization algorithms, as they may produce fairly different results (Mullen 2014). In this example, the method used ("L-BFGS-B", a well-established bounded optimization algorithm) returns the following *negative* log-likelihood values:
+Importantly, bounded methods can be very sensitive to the initial values and bounds, so, as in any numerical optimization problem, you should double-check the values obtained, at least by computing standard errors on your parameters with an adequate number of boostrap samples, and preferably by performing sensitivity analyses on the different parameters (in this and other vignettes, we have not included any of these checks, as our examples are merely for demonstration purposes). Aside from these recommendations, in the `cxr` objects returned from our functions, the negative log-likelihood of the fit is also included, which may be useful in helping users choose a certain optimization algorithm for a particular dataset. Remember that the convention is to present negative log-likelihood, and more negative values are better. In general, it is recommended to test different optimization algorithms, as they may produce fairly different results (Mullen 2014). In this example, the method used ("bobyqa", a well-established bounded optimization algorithm) returns the following *negative* log-likelihood values:
 
 ```{r}
 fit_3sp$log_likelihood
@@ -346,7 +346,6 @@ fixed_terms <- list(list(lambda = 1), # focal sp 1
 
 In this release of `cxr`, you must specify the same initial values for every focal species when using the `cxr_pm_multifit` option. This means, in practice, that if you want to fit species with different sets of fixed parameters, (e.g. only `lambda` for one species, but `lambda` and `alpha_intra` for another), or with different initial values, you should fit them separately, using `cxr_pm_fit`.
 
-
 **References**
 
 Godoy, O., Stouffer, D. B., Kraft, N. J., & Levine, J. M. (2017). Intransitivity is infrequent and fails to promote annual plant coexistence without pairwise niche differences. Ecology, 98(5), 1193-1200.

vignettes/V3_Coexistence_metrics.Rmd

@@ -20,7 +20,7 @@ The `cxr` package facilitates the estimation of key metrics from modern coexiste
 
 **Stabilizing niche differences**
 
-`Cxr` allows the calculation of niche overlap ($\rho$) between pairs of species, from which niche differences can be easily obtained as $1 - \rho$. Conceptually, if species limit themselves much more than they limit their competitors niche overlap will be very low and niche differences will be close to the maximum (i.e. 1). Conversely, if species limit themselves and other species similarly niche overlap will be very high and niche differences will be close to zero. In the absence of niche differences, the species with higher fitness (next section) is defined as the superior competitor. For obtaining niche overlap, thus, we need interaction coefficients among pairs of species.
+`cxr` allows the calculation of niche overlap ($\rho$) between pairs of species, from which niche differences can be easily obtained as $1 - \rho$. Conceptually, if species limit themselves much more than they limit their competitors niche overlap will be very low and niche differences will be close to the maximum (i.e. 1). Conversely, if species limit themselves and other species similarly niche overlap will be very high and niche differences will be close to zero. In the absence of niche differences, the species with higher fitness (next section) is defined as the superior competitor. For obtaining niche overlap, thus, we need interaction coefficients among pairs of species.
 
 First, we specify the data to use and the starting parameter values and bounds.
 
@@ -70,11 +70,11 @@ all.sp.fit <- cxr_pm_multifit(data = data,
 
 ```
 
-With these parameters, we can compute pairwise niche differences as 1 - niche overlap. Niche overlap following Chesson's (2013) definition can only include interaction coefficients with positive values (i.e. competition). Niche overlap can range from 0 to infinity and therefore niche differences can range from minus infinity to zero. Negative niche differences can be interpreted as a signature of priority effects. This means that the species of a pair arriving first to community is the winner. Niche differences between 0 and 1 reflect the degree to which species A and B limit each other compared to themselves. Within this range of values, species might coexist or be competitive excluded according to how stabilizing niche differences offset average fitness differences (see Adler et al. (2007) for more details).
+With these parameters, we can compute pairwise niche differences as 1 - niche overlap. Niche overlap following Chesson's (2013) definition can only include interaction coefficients with positive values (i.e. competition). Niche overlap can range from 0 to infinity, which implies that niche differences can range from minus infinity to zero. Negative niche differences can be interpreted as a signature of priority effects, meaning in a very broad sense that the first species of a pair to arrive to a community is the winner. Niche differences between 0 and 1 reflect the degree to which species A and B limit each other compared to themselves. Within this range of values, species might coexist or be competitive excluded according to how stabilizing niche differences offset average fitness differences (see Adler et al. (2007) for more details).
 
-Finally, it is worth noting that for those cases in which interaction coefficients are negative (i.e. a negative interaction coefficients in some models imply facilitative interaction between species), the `cxr` package provides another definition of niche differences, developed by Saavedra et al. (2017). This definition of niche differences uses another set of tools based on the Structural Approach (SA) to species coexistence, and while it is qualitatively coherent with the MCT framework, niche differences from both definitions do not exactly match (see Saavedra et al. (2017) for more details).
+Finally, it is worth noting that for those cases in which interaction coefficients are negative (i.e. negative interaction coefficients in Beverton-Holt or Ricker models imply facilitative interactions), the `cxr` package provides another definition of niche differences, developed by Saavedra et al. (2017). This definition of niche differences uses another set of tools based on the Structural Approach (SA) to species coexistence, and while it is qualitatively coherent with the MCT framework, niche differences from both definitions do not exactly match (see Saavedra et al. (2017) for more details).
 
-The function `niche_overlap` computes both definitions (MCT and SA). If the input is a `cxr_pm_multifit` object it will compute the niche overlap between all pairs of focal species.
+The function `niche_overlap` computes both definitions (MCT and SA). If the input is a `cxr_pm_multifit` object it will compute the niche overlap between all pairs of focal species (but it can also accept other arguments, see the help of the function for details).
 
 ```{r}
 niche_overlap_all_pairs <- niche_overlap(cxr_multifit = all.sp.fit)
@@ -99,7 +99,7 @@ The second type of pairwise differences relevant to species coexistence are the
 
 Average fitness differences are defined by two components, the 'demographic ratio' and the 'competitive response ratio'. The 'demographic ratio' is a density independent term that describes the degree to which one species (species j) has higher offspring production than another species (species i). The 'competitive response ratio' is a density dependent term, which describes the degree to which species i is more sensitive to both intra and interspecific competition than species j. Because both ratios define the average fitness differences, this means that a species can be a superior competitor because it produces high number of for instance seeds/eggs or because its offspring production is little reduced in the presence of competitors. This formulation is explained in greater detail by Godoy and Levine (2014).
 
-Both components of average fitness differences can be computed with `cxr`. As it is the case with the niche overlap calculations, average fitness differences in the context of MCT are only defined for negative interactions, i.e. positive alpha values. Saavedra et al. (2017) developed a structural analog of this metric, that we also include in our package. Thus, the function `avg_fitness_diff` returns the demographic ratio, competitive response ratio, and average fitness differences for each species pair in the context of MCT, as well as the structural analog of these differences. It accepts the same arguments as the `niche_overlap` function (see help for details), and here we use the multispecies fit obtained above to calculate differences across all pairs of focal species.
+Both components of average fitness differences can be computed with `cxr`. As it is the case with the niche overlap calculations, average fitness differences in the context of MCT are only defined for negative interactions, i.e. positive alpha values. Saavedra et al. (2017) developed a structural analog of this metric, that we also include in our package. Thus, the function `avg_fitness_diff` returns the demographic ratio, competitive response ratio, and average fitness differences for each species pair in the context of MCT, as well as the structural analog of these differences. It accepts the same arguments as the `niche_overlap` function (see help for details), and here we use the multispecies fit obtained above to calculate fitness differences across all pairs of focal species.
 
 ```{r}
 avg_fitness_diff_all_pairs <- avg_fitness_diff(cxr_multifit = all.sp.fit)
@@ -115,9 +115,9 @@ avg_fitness_diff_all_pairs <- avg_fitness_diff_all_pairs[complete.cases(
 head(avg_fitness_diff_all_pairs)
 ```
 
-**Estimation of species competitive ability**
+**Estimation of species' competitive ability**
 
-From average fitness differences, we can compute species' competitive ability. The definition of species competitive ability changes according to the population model selected to describe the dynamics of interacting species. The mathematical procedure to obtain the definition of species competitive ability was firstly described in Godoy and Levine (2014) for the annual plant model, and expanded to a wider family of models by Hart et al. (2018). 
+From average fitness differences, we can compute species' competitive ability. The formulation of species' competitive ability changes according to the population model selected to describe the dynamics of interacting species. The mathematical procedure to obtain the definition of species competitive ability was firstly described in Godoy and Levine (2014) for the annual plant model, and expanded to a wider family of models by Hart et al. (2018). 
 
 Competitive ability can be calculated given a set of species parameters and model family (e.g. as specified in `cxr` objects). Again, the set of arguments accepted by the `competitive_ability` function is the same as the arguments passed to the `niche_overlap` and `avg_fitness_diff` functions. The easiest way is to provide a `cxr_pm_multifit` object with all necessary information.
 
@@ -131,7 +131,7 @@ head(competitive_ability_all_pairs)
 
 **Estimation of species fitness in the absence of niche differences**
 
-In the previous steps, average fitness differences and therefore species competitive ability are computed combining density independent and density dependent effects. This means that these metrics are estimated in the presence of stabilizing niche differences. However in some cases, it can be interesting for the user to estimate species fitness in the absence of niche differences. This is the case for instance if we want to list species according to a competitive hierarchy. With this procedure, we would be able to tease apart which species would be the first superior competitor if we remove niche differences, the second superior competitor, and so on, up to the weakest competitor. In order to define this species fitness against all other competitors, we need to collapse pairwise interaction coefficients into two components: how species respond to overall competition (competitive response) and how species affect other species (competitive effect). Both components are defined in Godoy et al. (2014). 
+In the previous steps, average fitness differences and therefore species competitive ability are computed combining density independent and density dependent effects. This means that these metrics are estimated in the presence of stabilizing niche differences. However in some cases, it can be interesting for the user to estimate species fitness in the absence of niche differences. This is the case for instance if we want to list species according to a competitive hierarchy. With this procedure, we would be able to tease apart which species would be the first superior competitor if we remove niche differences, which would be the second superior competitor and so on, up to the weakest competitor. In order to define this species fitness against all other competitors, we need to collapse pairwise interaction coefficients into two components: how species respond to overall competition (competitive response) and how species affect other species (competitive effect). Both components are defined in Godoy et al. (2014). 
 
 In `cxr`, we first need to obtain these components from observational data, and this calculation is done with the `cxr_er_fit` function. This function is similar to `cxr_pm_fit`, with some caveats. It accepts a list of observational dataframes, but in this case the number of observations of each focal species must match (this is in order to compute balanced parameters). Furthermore, the set of focal species needs to be the same as the set of neighbours, unlike in `cxr_pm_fit`.