Jo.eng: Joint occupancy model engine

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

Joint occupancy model engine

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 one particular community. In particular, Jo.eng:

• computes the joint occupancy (i.e. the number of sites or assemblages harbouring multiple species simultaneously);

• performs a null model test using the same index;

• fits the three regression models (exponential, power law and exponential-power law) to joint occupancy decline (sensu Lagat et al., 2021a) with order (number of species);

• estimates the parameter values of these models;

• determines the best model among the three using AIC values;

• quantifies the performance of the fitted models using the Pearson's r^2;

• plots the joint occupancy decline regression and null models, and

• ascertains the archetypes of the patterns of species co-occurrences (from null model test) from which inferences on the type of drivers structuralising ecological communities can be made.

Usage

Jo.eng(
  s.data,
  algo = "sim2",
  metric = "raw",
  nReps = 999,
  dig = 3,
  s.dplot = FALSE,
  All.plots = TRUE,
  Jo.coeff = TRUE,
  my.AIC = TRUE,
  my.rsq = TRUE,
  Exp_Reg = TRUE,
  P.law_Reg = TRUE,
  Exp_p.l_Reg = TRUE,
  Obs.data = FALSE,
  Sim.data = FALSE,
  Jo_val.sim = FALSE,
  C.I_Jo_val.sim = FALSE,
  Jo_val.obs = TRUE,
  Metric = TRUE,
  Algorithm = TRUE,
  S.order = TRUE,
  nmod_stats = TRUE,
  Pt_Arch_Vals = TRUE,
  Atype = TRUE,
  p.n.plot = FALSE,
  trans = FALSE,
  lab = FALSE,
  leg = FALSE,
  m.n.plot = FALSE
)

Arguments

s.data	A species-by-site presence/absence matrix with entries indicating occurrence (1) and non-occurrence (0) of species in a site.
algo	Randomisation algorithm used for the comparison with the null model. 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.
dig	The number of decimal places of the joint occupancy values (y axis) in the plots. The default is 3.
s.dplot	A Boolean indicating whether the standard deviation of multi-species co-occurrence index should be included in the plots of joint occupancy decline or not.
All.plots	A Boolean indicating whether joint occupancy decline regression and null model plots should be output.
Jo.coeff	A Boolean indicating if coefficient estimates of the joint occupancy decline regression models should be printed.
my.AIC	A Boolean indicating whether Akaike Information Criterion of the joint occupancy decline regression models should be output or not.
my.rsq	A Boolean indicating whether square of correlation coefficient between the observed and predicted values of joint occupancy should be output.
Exp_Reg	A Boolean indicating if exponential regression parametric model should be printed.
P.law_Reg	A Boolean indicating if power law regression parametric model should be printed.
Exp_p.l_Reg	A Boolean indicating if exponential-power law regression parametric model should be printed.
Obs.data	A Boolean indicating if observed/empirical data should be output.
Sim.data	A Boolean indicating if simulated/random data produced using any of the simulation algorithms should be output.
Jo_val.sim	A Boolean indicating if joint occupancy values of the simulated species-by-site presence/absence matrices should be output.
C.I_Jo_val.sim	A Boolean indicating if 95% confidence interval of the joint occupancy values of the simulated data should be printed. This interval is the area under the null model.
Jo_val.obs	A Boolean indicating if joint occupancy values of the observed species-by-site presence/absence matrices should be output.
Metric	A Boolean indicating if metric used should be printed.
Algorithm	A Boolean indicating if simulation algorithm used should be printed.
S.order	A Boolean indicating if the number of species whose joint occupancy is computed should be printed.
nmod_stats	A Boolean indicating whether the summary statistics for the null model test should be output.
Pt_Arch_Vals	A Boolean indicating if character strings indicating the location of joint occupancy value of the observed data relative to the critical values of the 95% closed confidence interval for every order (number of species), should be printed.
Atype	A Boolean indicating if a character string indicating the overall archetype of joint occupancy decline should be printed.This value 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.
p.n.plot	A Boolean indicating whether null model plot produced using the pairwise natural metric should be output.
trans	A Boolean indicating if the observed and simulated values used in p.n.plot should be transformed by raising them to (1/100). This can be done to compare p.n.plot with All.plots at a point where the order, i = 2.
lab	A Boolean indicating if the plot labels should be added to the m.n.plot. This parameter helps to control the appearance of plots in this function.
leg	A Boolean indicating if the legend should be added to the m.n.plot. This parameter helps to control the appearance of plots in this function.
m.n.plot	A Boolean indicating whether null model plot produced using joint occupancy metrics should be output. The default is FALSE.

Value

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

all.plots	Joint occupancy decline regression and null model plots.
jo.coeff	Coefficient estimates of the joint occupancy decline regression models.
AIC	Akaike information criterion of the joint occupancy decline regression models.
r2	Square of correlation coefficient between the observed and predicted values of joint occupancy.
Exp_reg	Exponential regression parametric model.
P.law_reg	Power law regression parametric model.
Exp_p.l_reg	Exponential-power law regression parametric model.
Obs.data	Observed/empirical data.
Sim.data	Simulated/random data produced using any of the simulation algorithms.
jo.val.sim	Joint occupancy value of the simulated species-by-site presence/absence matrices.
C.I_Jo_val.sim	95% confidence interval of the joint occupancy value of the simulated data.
jo.val.obs	joint occupancy value of the observed species-by-site presence/absence matrices.
Metric	Metric used. It must be "j.occ".
Algorithm	Simulation algorithm used.
nReps	Number of simulations performed. This value together with the joint occupancy value of the observed data, constitutes the sampling distribution.
s.order	Number of species whose joint occupancy is computed.
Pt_Arch_vals	Character strings indicating the location of joint occupancy value of the observed data relative to the critical values of the 95% closed confidence interval of the simulated data, for every order (number of species).
Archetype	A character string indicating the overall archetype from Pt_Arch_vals. It 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 (see Arch_schem).

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

Examples

ex.data <- read.csv(system.file("extdata", "274.csv", package = "msco"))
j.en <- msco::Jo.eng(ex.data, algo="sim2", metric = "raw", nReps = 999,
           dig = 3, s.dplot = FALSE, All.plots = TRUE, Jo.coeff = TRUE,
           my.AIC = TRUE, my.rsq = TRUE, Exp_Reg = TRUE, P.law_Reg = TRUE,
           Exp_p.l_Reg = TRUE, Obs.data = FALSE, Sim.data = FALSE,
           Jo_val.sim = FALSE, C.I_Jo_val.sim = FALSE, Jo_val.obs = TRUE,
           Metric = TRUE, Algorithm = TRUE, S.order = TRUE,
           nmod_stats = TRUE, Pt_Arch_Vals = TRUE, Atype = TRUE,
           p.n.plot = FALSE, trans = FALSE, lab=FALSE, leg=FALSE, m.n.plot = FALSE)
j.en

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