gbsm_m.orders: Predictor's contribution and model performance assessment...
In vitaliskim/msco: Multi-Species Co-Occurrence Analyses

gbsm_m.orders

R Documentation

Predictor's contribution and model performance assessment from the results on multiple orders of joint occupancy

Description

This function implements the generalised B-spline model (gbsm; sensu Lagat et al., 2021b) for dissecting the effects of random encounter versus functional trait mismatching on multi-species co-occurrence and interference. Unlike gbsm that performs gbsm for a single order of species, gbsm_m.orders takes into account multiple orders of joint occupancy. In particular: for multiple joint occupancy orders, this function computes:

each predictor's contribution to the explained variation in joint occupancy,
the goodness-of-fit and model performance from cross-validation, and
plots the:
- response curves,
- scatter plots (between the observed and predicted joint occupancy values),
- histograms of the joint occupancy frequency distribution, and
- model performance plots.

Usage

gbsm_m.orders(
  s.data,
  t.data,
  p.d.mat,
  metric = "Simpson_eqn",
  orders,
  d.f = 4,
  degree = 3,
  n = 1000,
  k = 5,
  p = 0.8,
  type = "k-fold",
  gbsm.model,
  scat.plots = FALSE,
  response.curves = TRUE,
  j.occs.distrbn = FALSE,
  mp.plots = FALSE,
  max.vif = 20,
  max.vif2 = 10,
  start.range = c(-0.1, 0)
)

Arguments

`s.data`	A species-by-site presence/absence `data.frame` with entries indicating occurrence (1) and non-occurrence (0) of species in a site.
`t.data`	A `data.frame` with traits as columns and species as rows. The species must be the same as in `s.data`.
`p.d.mat`	A symmetric `matrix` with `dimnames` as species and entries indicating the phylogenetic distance between any two of them (species).
`metric`	As for gbsm.
`orders`	Specific number of species for which the joint occupancy is computed.
`d.f`	As for gbsm.
`degree`	As for gbsm.
`n`	As for gbsm.
`k`	As for cross_valid.
`p`	As for cross_valid.
`type`	As for cross_valid.
`gbsm.model`	As for gbsm.
`scat.plots`	Boolean value indicating if scatter plots between joint occupancy and its predicted values should be plotted.
`response.curves`	A boolean value indicating if all response curves for all joint occupancy orders (`jo.orders`) should be plotted.
`j.occs.distrbn`	A boolean value indicating if the histograms of the frequency distribution of observed joint occupancy should be output.
`mp.plots`	A boolean value indicating if the model performance plots should be output.
`max.vif`	As for gbsm.
`max.vif2`	As for gbsm.
`start.range`	As for gbsm.

Value

gbsm_m.orders function returns a list containing the following outputs:

jo.orders: A set of joint occupancy orders.
contrbn_table: A list of data.frames consisting of:
- predictor: A column of predictors.
- var.expld_M1: A column of goodness-of-fit (I.e., the Pearson's r^2 between the observed and predicted values of joint occupancy when all predictors are used in the model.
- var.expld_M2: The Pearson's r^2 between the observed and the predicted values of joint occupancy when all predictors except the predictor whose contribution is to be determined, are used in the model.
- contribution: Each predictor's proportion of contribution in explaining joint occupancy. This value is given by:
  
  contribution = \frac{var.expld_{M1} - var.expld_{M2}}{var.expld_{M1}}
model.validation.table: A data.frame with:
- orders: Orders of joint occupancy used.
- Rsquared_gf: Goodness-of-fit of the model. I.e., it is the Pearson's r^2 between the observed and predicted values of joint occupancy, for different orders.
- Rsquared_cv: Model performance from cross-validation.
metric: As for gbsm.
d.f: As for gbsm.
n: As for gbsm.
degree: As for gbsm.
jo.orders: Orders of joint occupancy used.
Original.VIFs As for gbsm (different orders).
Intermediate.VIFs As for gbsm (different orders).
Final.VIFs As for gbsm (different orders).

References

Curry, H. B., and Schoenberg, I. J. (1988). On Pólya frequency functions IV: the fundamental spline functions and their limits. In IJ Schoenberg Selected Papers (pp. 347-383). Birkhäuser, Boston, MA. https://doi.org/10.1007/978-1-4899-0433-1_17
Hastie, T., and Tibshirani, R. (1986). Generalized additive models. Stat. Sci. 1(3), 297-310. https://doi.org/10.1214/ss/1177013604
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>⁠.
Lagat, V. K., Latombe, G. and Hui, C. (2021b). Dissecting the effects of random encounter versus functional trait mismatching on multi-species co-occurrence and interference with generalised B-spline modelling. DOI: ⁠<To be added>⁠.

Examples

## Not run: 
 my.path <- system.file("extdata/gsmdat", package = "msco")
 setwd(my.path)
 s.data <- get(load("s.data.csv")) ## Species-by-site matrix
 t.data <- get(load("t.data.csv")) ## Species-by-Trait matrix
 p.d.mat <- get(load("p.d.mat.csv")) ## Species-by-species phylogenetic distance matrix


 RNGkind(sample.kind = "Rejection")
 set.seed(1)
 jp <- msco::gbsm_m.orders(s.data, t.data, p.d.mat, gbsm.model,
  metric="Simpson_eqn", orders = c(3:5, 8, 10, 15, 20), d.f=4,
   degree=3, n=1000, k=5, p=0.8, type="k-fold", scat.plots=TRUE,
    response.curves=TRUE, j.occs.distrbn=TRUE, mp.plots=TRUE,
     max.vif = 10, max.vif2 = 4, start.range=c(-0.2,0))

 jp$contbn_table[[1]]
 jp$model.validation.table
 jp$jo.orders
 jp$Original.VIFs$`order 3`
 jp$Intermediate.VIFs$`order 3`
 jp$Final.VIFs$`order 3`

 ## Close the open plots.gbsm.pdf file before running the 2nd example
 RNGkind(sample.kind = "Rejection")
 set.seed(1)
 jp2 <- msco::gbsm_m.orders(s.data, t.data, p.d.mat, gbsm.model,
  metric="Sorensen_eqn", orders = c(3:5, 8, 10, 15, 20), d.f=4,
   degree=3, n=1000, k=5, p=0.8, type="k-fold", scat.plots=TRUE,
    response.curves=TRUE, j.occs.distrbn=TRUE, mp.plots=TRUE,
     max.vif = 10, max.vif2 = 4, start.range=c(-0.2,0))

 jp2$contbn_table[[1]]
 jp2$model.validation.table
 jp2$jo.orders
 jp2$Original.VIFs$`order 3`
 jp2$Intermediate.VIFs$`order 3`
 jp2$Final.VIFs$`order 3`

## Close the open plots.gbsm.pdf file before running the 3rd example
 RNGkind(sample.kind = "Rejection")
 set.seed(1)
 jp3 <- msco::gbsm_m.orders(s.data, t.data, p.d.mat, gbsm.model,
  metric="raw_prop", orders = c(3:5, 8, 10, 15, 20), d.f=4,
   degree=3, n=1000, k=5, p=0.8, type="k-fold", scat.plots=TRUE,
    response.curves=TRUE, j.occs.distrbn=TRUE, mp.plots=TRUE,
    max.vif = 10, max.vif2 = 4, start.range=c(-0.2,0))

 jp3$contbn_table[[1]]
 jp3$model.validation.table
 jp3$jo.orders
 jp3$Original.VIFs$`order 3`
 jp3$Intermediate.VIFs$`order 3`
 jp3$Final.VIFs$`order 3`

## Close the open plots.gbsm.pdf file before running the 4th example
 RNGkind(sample.kind = "Rejection")
 set.seed(1)
 jp4 <- msco::gbsm_m.orders(s.data, t.data, p.d.mat, gbsm.model="nb",
  metric="raw", orders = c(3:5, 8, 10, 15, 20), d.f=4,
   degree=3, n=1000, k=5, p=0.8, type="k-fold", scat.plots=TRUE,
    response.curves=TRUE, j.occs.distrbn=TRUE, mp.plots=TRUE,
    max.vif = 10, max.vif2 = 4, start.range=c(-0.2,0))

 jp4$contbn_table[[1]]
 jp4$model.validation.table
 jp4$jo.orders
 jp4$Original.VIFs$`order 3`
 jp4$Intermediate.VIFs$`order 3`
 jp4$Final.VIFs$`order 3`

## Close the open plots.gbsm.pdf file before running the 5th example
 RNGkind(sample.kind = "Rejection")
 set.seed(1)
 jp5 <- msco::gbsm_m.orders(s.data, t.data, p.d.mat, gbsm.model="quasipoisson",
  metric="raw", orders = c(3:5, 8, 10, 15, 20), d.f=4,
   degree=3, n=1000, k=5, p=0.8, type="k-fold", scat.plots=TRUE,
    response.curves=TRUE, j.occs.distrbn=TRUE, mp.plots=TRUE,
    max.vif = 10, max.vif2 = 4, start.range=c(-0.2,0))

 jp5$contbn_table[[1]]
 jp5$model.validation.table
 jp5$jo.orders
 jp5$Original.VIFs$`order 3`
 jp5$Intermediate.VIFs$`order 3`
 jp5$Final.VIFs$`order 3`

 
## End(Not run)

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