mJo.eng: Joint occupancy model engine for multiple communities

In vitaliskim/msco: Multi-Species Co-Occurrence Analyses

Joint occupancy model engine for multiple communities

Description

This function is the engine behind the null model testing of species co-occurrence patterns, and analyses of the joint occupancy decline and the parametric forms of this decline, for multiple communities. In particular:

• It performs the null model testing of species co-occurrence patterns and generates the archetypes depicting how joint occupancy declines with the number of species (the order of msco) based on species-by-site presence/absence .csv data matrices. From these archetypes, inferences can be made according to the implemented null models;

• Determines the robustness of the exponential, power law and exponential-power law forms of joint occupancy decline by computing the Pearson's r^2 between the joint occupancy values of the observed data and predicted data, for all orders of species;

• Gives a summary of the total number of communities (under each and for all archetypes) whose forms of joint occupancy decline have r^2 > 0.95;

• Computes the AIC and Delta AIC of joint occupancy decline regression models for all communities;

• Computes the total number of communities:

  • with exponential as the best form of joint occupancy decline than power law and vice versa;

  • with either of the three regression models (exponential, power law and exponential-power law) having the best form of the joint occupancy decline;

• Estimates the parameters of:

  1. exponential: j^{\{i\}} = a \times exp(b \times i);

  2. power law: j^{\{i\}} = a \times i^b; and

  3. exponential-power law: j^{\{i\}} = a \times exp(b \times i) \times i^c

  forms of joint occupancy decline, respectively, and their 95% confidence interval.

Usage

mJo.eng(
  my.files,
  algo = "sim2",
  metric = "raw",
  nReps = 999,
  Archetypes = FALSE,
  AICs = FALSE,
  Delta_AIC = FALSE,
  datf.Delta_AIC = FALSE,
  param_hist = FALSE,
  params = FALSE,
  best.mod2 = FALSE,
  best.mod3 = FALSE,
  params_c.i = FALSE,
  my.r2 = FALSE,
  my.r2.s = FALSE
)

Arguments

my.files	A vector containing names of species-by-site presence/absence .csv data matrices. The data matrices should be saved in the working directory.
algo	Simulation algorithm used. The possible options to choose from are: sim1, sim2, sim3, sim4, sim5, sim6, sim7, sim8, and sim9, all from Gotelli (2000). sim2 is highly recommended (see Lagat et al., 2021a).
metric	The type of rescaling applied to the joint occupancy metric. Available options are: Simpson_eqn for Simpson equivalent, Sorensen_eqn for Sorensen equivalent, and raw for the raw form of index without rescaling.
nReps	Number of simulations used in the null model test.
Archetypes	A Boolean indicating if the archetypes of the patterns of species co-occurrences in multiple communities should be included in the output.
AICs	A Boolean indicating whether the akaike information criterion (AIC) and Delta AIC of joint occupancy decline regression models for all communities should be included in the output.
Delta_AIC	A Boolean indicating whether Delta AIC (excluding AIC) should be output.
datf.Delta_AIC	A Boolean indicating whether a data.frame with Classes and Param.mods as columns, where the former has 1, 2 and 3 values categorizing the three parametric models that has Delta_AIC=0 for each communities; and the later shows the respective parametric form of joint occupancy decline.
param_hist	A Boolean indicating whether histograms of the number of communities where the three parametric forms (exponential, power law and exponential-power law) of joint occupancy decline had the lowest AIC values, should be plotted.
params	A Boolean indicating whether parameter estimates of the joint occupancy decline regression models should be included in the output.
best.mod2	A Boolean indicating if exponential and power law regression model comparisons should be included in the output.
best.mod3	A Boolean indicating if exponential, power law and exponential-power law regression model comparisons should be included in the output.
params_c.i	A Boolean indicating if 95% C.I of the parameter estimates of the joint occupancy decline regression models should be included in the output.
my.r2	A Boolean indicating if the robustness of joint occupancy decline regression models should be computed and output.
my.r2.s	A Boolean indicating if the robustness summary values of joint occupancy decline regression models should be computed and output.

Details

mJo.eng function is useful when analyzing multiple species-by-site presence/absence data matrices at once. If one community matrix is analyzed, the outputs of the function Jo.eng should suffice.

Value

mJo.eng function returns a list containing the following outputs:

$Archs

For every community, a list consisting of:

• ⁠$nmod_stats⁠: A data frame with the summary statistics for the null model test; and

• ⁠$Archetype⁠: Archetypes of the patterns of species co-occurrences in ecological communities/matrices (my.files). These archetypes must be \in \{"A1", "A2", "A3", "A4", "A5", "A6", "A7", "A8", "A9"\} or "NA". "NA" could be the combinations of two or more of the nine expected archetypes.

$all.AICs

A list of data.frames containig the following components:

df	The number of parameters in each of the three (exponential, power law and exponential-power law) joint occupancy decline regression models.
aic	The aic values for each of the three joint occupancy decline regression models.
delta_aic3	The delta_aic values for each of the three joint occupancy decline regression models.
delta_aic2	The delta_aic values for exponential and power law forms of joint occupancy decline regression models.

$params

A data.frame consisting of:

arch	The archetypes of the patterns of species co-occurrences in each of the species-by-site presence/absence .csv data matrices.
a.ex	The a parameter estimate of the exponential form of joint occupancy decline.
b.ex	The b parameter estimate of the exponential form of joint occupancy decline.
a.pl	The a parameter estimate of the power law form of joint occupancy decline.
b.pl	The b parameter estimate of the power law form of joint occupancy decline.
a.expl	The a parameter estimate of the exponential-power law form of joint occupancy decline.
b.expl	The b parameter estimate of the exponential-power law form of joint occupancy decline.
c.expl	The c parameter estimate of the exponential-power law form of joint occupancy decline.

$best.mod2

Atable containig the following components:

n	The number of ecological communities represented by species-by-site presence/absence .csv data matrices.
n.lwst_aic	The number of communities with exponential as the best form of joint occupancy decline than power law.
n.delta_aic	The number of communities whose exponential and power law forms of joint occupancy decline have delta_aic = 0, respectively. This number must be equal to n.lwst_aic.
⁠%⁠	The percentage of n.lwst_aic (or n.delta_aic) relative to the total number of communities (n) analyzed.

$best.mod3

A table containig the following components:

n	The number of ecological communities represented by species-by-site presence/absence .csv data matrices.
n.lwst_aic	The number of communities with exponential or power law or exponential-power law as the best form of joint occupancy decline among the three (exponential, power law and exponential-power law) regression models.
n.delta_aic	The number of communities whose exponential, power law and exponential-power law forms of joint occupancy decline, respectively, have delta_aic = 0. This number must be equal to n.lwst_aic.
⁠%⁠	The percentage of n.lwst_aic (or n.delta_aic) relative to the total number of communities (n) analyzed.

$params_c.i

A data.frame consisting of:

arch	The archetypes of the patterns of species co-occurrences in each of the species-by-site presence/absence .csv data matrices.
n	The number of communities under every archetype.
⁠ex_%⁠	The percentages of the number of communities (under every archetype) where exponential form of joint occupancy decline fitted better than power law.
a.ex	The 95% closed confidence interval of the a parameter estimates of the exponential form of joint occupancy decline, under every archetype.
b.ex	The 95% closed confidence interval of the b parameter estimates of the exponential form of joint occupancy decline, under every archetype.
⁠p.l_%⁠	The percentages of the number of communities (under every archetype) where power law form of joint occupancy decline fitted better than exponential.
a.pl	The 95% closed confidence interval of the a parameter estimates of the power law form of joint occupancy decline, under every archetype.
b.pl	The 95% closed confidence interval of the b parameter estimates of the power law form of joint occupancy decline, under every archetype.
⁠ex.pl_%⁠	The percentages of the number of communities (under every archetype) where exponential-power law form of joint occupancy decline fitted better than both the exponential and power law forms.
a.expl	The 95% closed confidence interval of the a parameter estimates of the exponential-power law form of joint occupancy decline, under every archetype.
b.expl	The 95% closed confidence interval of the b parameter estimates of the exponential-power law form of joint occupancy decline, under every archetype.
c.expl	The 95% closed confidence interval of the c parameter estimates of the exponential-power law form of joint occupancy decline, under every archetype.

$r2

A list of data.frames containig the following components:

rsq.ex	r^2 for the exponential form of joint occupancy decline.
rsq.pl	r^2 for the power law form of joint occupancy decline.
rsq.ex.pl	r^2 for the exponential-power law form of joint occupancy decline.

$r2.s

• A list containig the following components:

  $rsq.per.Archs

  • Archs: Archetypes of the patterns of species co-occurrences in each of the species-by-site presence/absence .csv data matrices.

  • n.a: Number of communities under each archetype.

  • rsq.ex: Number of communities under each archetype whose exponential forms of joint occupancy decline have r^2 > 0.95.

  • rsq.pl: Number of communities under each archetype whose power law forms of joint occupancy decline have r^2 > 0.95.

  • rsq.ex-pl: Number of communities under each archetype whose exponential-power law forms of joint occupancy decline have r^2 > 0.95.

  $rsq.all.Communities

  • n: Number of all communities analyzed

  • ex: Number of communities whose exponential forms of joint occupancy decline have r^2 > 0.95

  • pl: Number of communities whose power law forms of joint occupancy decline have r^2 > 0.95

  • ex.pl: Number of communities whose exponential-power law forms of joint occupancy decline have r^2 > 0.95

$m.Jo.plots

Produces a .pdf file with multiple figures each consisting of the following plots:

(a)	as for Jo.plots
(b)	as for Jo.plots
(c)	as for Jo.plots
(d)	as for Jo.plots
(e)	as for Jo.plots

References

1. Lagat, V. K., Latombe, G. and Hui, C. (2021a). A multi-species co-occurrence index to avoid type II errors in null model testing. DOI: ⁠<To be added>⁠.

2. Gotelli, N. J. (2000). Null model analysis of species co-occurrence patterns. Ecology, 81(9), 2606-2621. https://doi.org/10.1890/0012-9658(2000)081[2606:NMAOSC]2.0.CO;2

3. Pearson, K. (1895) VII. Note on regression and inheritance in the case of two parents. proceedings of the royal society of London, 58:240-242. https://doi.org/10.1098/rspl.1895.0041

4. Petrossian, G.A., Maxfield, M (2018). An information theory approach to hypothesis testing in criminological research. crime science, 7(1), 2. https://doi.org/10.1186/s40163-018-0077-5

Examples

## Not run: 

my.path <- system.file("extdata", package = "msco")
setwd(my.path)
my.files <- gtools::mixedsort(list.files(path = my.path, pattern = ".csv"))
my.res <- msco::mJo.eng(my.files = my.files, algo = "sim2", Archetypes = TRUE,
             metric = "raw", nReps = 999, AICs = FALSE, params = FALSE,
             best.mod2 = FALSE, best.mod3 = FALSE, params_c.i = FALSE,
             my.r2 = FALSE, my.r2.s = FALSE)
my.res$Archs$`252.csv`

my.path2 <- system.file("extdata/myCSVs", package = "msco")
setwd(my.path2)
my.files2 <- gtools::mixedsort(list.files(path = my.path2, pattern = ".csv"))
my.res2 <- msco::mJo.eng(my.files = my.files2[250:255], algo = "sim2", Archetypes = FALSE,
              metric = "raw", nReps = 999, AICs = FALSE, params = TRUE,
              best.mod2 = FALSE, best.mod3 = FALSE, params_c.i = FALSE,
              my.r2 = FALSE, my.r2.s = FALSE)
my.res2

my.path2 <- system.file("extdata/myCSVs", package = "msco")
setwd(my.path2)
my.files2 <- gtools::mixedsort(list.files(path = my.path2, pattern = ".csv"))
my.res3 <- msco::mJo.eng(my.files = my.files2[250:255], algo = "sim2", Archetypes = FALSE,
              metric = "raw", nReps = 999, AICs = FALSE, params = FALSE,
              best.mod2 = FALSE, best.mod3 = FALSE, params_c.i = TRUE,
              my.r2 = FALSE, my.r2.s = FALSE)
my.res3
 
## End(Not run)

vitaliskim/msco documentation built on Sept. 29, 2023, 9:22 p.m.