getJacobian: Jacobian matrix from an energy-flux model
In dswdejonge/fwstability: Infer Food-Web Stability

getJacobian

R Documentation

Jacobian matrix from an energy-flux model

Description

This is a wrapper function that reviews the given energy-flux food-web model and redirects the input to the correct function for obtaining interaction strengths in a Jacobian matrix.

Usage

getJacobian(
  model = stop("Model input required"),
  diagonal = "model",
  verbose = TRUE,
  netMatrix = TRUE
)

Arguments

`model`	(required) A named list containing elements with food web model data. One list element named `type` denoting the type of input model must exist and should either be the string "EF", or "LIM". "EF" should be used if the model is a quantified energy flux model. Other list elements required for EF models are `FM`, `BM`, `AE`, and `GE` to be used by the `getJacobianEnergyFlux` function. "LIM" should be used if the model is a linear inverse model created with the package LIM and is formatted to contain tags. The other list element required for LIM type models is `LIM` containing a read-in LIM. If the LIM is resolved the flow solutions can be provided in the list element `web`. If the LIM is not resolved, the function will use the parsimonious (least distance) solution.
`diagonal`	(required) is by default calculated from the model (= "model"). Can also be set to an all-zero diagonal (= 0) or a numeric vector.
`verbose`	(optional) Default is TRUE. Whether or not to print messages.
`netMatrix`	(optional) Boolean. Default is TRUE: the netMatrix is used to calculate interaction strengths. This is only relevant if there are two food web compartments which act both as prey and predators to one another.

Value

This function returns a matrix containing interaction strengths, i.e. the effect of the resources (rows) on the consumers (columns) - for all interactions in the food web. If the model input is a LIM the output is a list JM with element JM (so JM$JM) that is the Jacobian matrix with interaction strengths, and with element extracted_data (so JM$extracted_data) that is another list with all data extracted from the LIM the Jacobian matrix is calculated from.

Energy Flux models

Interaction strenghts can be calculated from energy flux models as presented in De Ruiter (1995) and Neutel & Thorne (2014). The energy flux model should at least include quantified flows, compartment biomasses, and conversion efficiencies. If you want to calculate the intraspecific interactions, i.e. the diagonal values, from the model, then non-predatory mortality are necessary. Non-predatory mortality rates can be calculated from the model or parsed manually. Beware that these model-derived diagonal values represent an upperbound. It is the maximum amount of self-dampening possible in the respective populations. If your model includes dead compartments, like detritus or nutrients, it is highly recommended to also include these in the special argument dead. Conversion efficiencies are not needed for dead compartments, and you should include information on defecation into these compartments. Interaction strengths of dead compartments are calculated in another way than for living compartments. Inclusion of recycling processes may impact your stability results (Wilson & Wolkovich, 2011).
The list with model information should contain:

type (required) should be "EF" for energy flux models.
FM (required) is a named square flowmatrix with sources in rows and sinks in columns.
BM (required) is a named numeric with biomasses for all compartments.
AE (required) is a named numeric with assimilation efficiencies for living compartments.
GE (required) is a named numeric with growth efficiencies for living compartments.
dead (optional) is a list with the elements names and frac that contains the names of dead compartments (character vector) and what fraction of each flow comprises defecation (matrix similar to FM after removal of externals, only required with parallel flows).
externals (optional) is a character vector with any compartments that should not be considered in the calculations.
MR (optional) Mortality rates for all compartments per unit time (t-1). Default behaviour (MR = NULL) is calculation of mortality rates as (growth - predation)/biomass. Otherwise, you can provide a named numeric vector.

More detailed information about argument requirements see ?getJacobianEnergyFlux.

Linear Inverse models

Linear programming can be used to quantify fluxes. Therefore, a solved linear inverse model (LIM) often already contains the elements needed to calculate interaction strengths, but they need to be extracted and calculated first. A LIM can be created with the R-package LIM. By sticking to certain rules when writing the model input file, the fwstability package can automatically derive the necessary information for stability analysis. These requirements include the use of tags in the names of compartments, variables, and flows to later identify dead compartments, defecation and mortality flows, and variables representing assimilation and growth. Tags should be used in combination with only the compartmentname to assign the extracted value to the right compartment (exception is for defecation flows). Tags are not case-sensitive and can be placed either in front or after the compartmentname. Default tags are "dead", "ass", "growth", "mort", and "def", but you can also choose your own tag names. More information on setting up the input model with these tags can be found in the vignette.
The LIM can be solved and quantified in various ways (e.g. by optimization or maximum likelihood) and added to the model list in the element web as named numeric. If you do not solve your LIM before parsing it into this function, the model will be solved using Ldei, which is the parsimonious solution minimizing the sum of squares.
The list with model information should contain:

type (required) should be "LIM"
LIM (required) should be a read-in LIM. This can be acquired by Read(<path-to-input-file>) from the LIM R-package.
setup (optional) can be Setup(Read(<path-to-input-file>)), otherwise set-up within function.
web (optional) named numeric with flow solutions.
aTag, gTag, mTag, defTag, deadTag are optional. Default tags are "ass", "growth", "mort", "def", and "dead" respectively.

More information on the requirements of the arguments see ?extractLIMdata

References

de Ruiter, P.C., Neutel, A.M., Moore, J.C., 1995. Energetics, Patterns of Interaction Strengths, and Stability in Real Ecosystems. Science (80-. ). 269, 1257–1260. https://doi.org/10.1126/science.269.5228.1257
Neutel, A.M., Thorne, M.A.S., 2014. Interaction strengths in balanced carbon cycles and the absence of a relation between ecosystem complexity and stability. Ecol. Lett. 17, 651–661. https://doi.org/10.1111/ele.12266
Moore, J. C., Berlow, E. L., Coleman, D. C., De Ruiter, P. C., Dong, Q., Hastings, A., … Wall, D. H. (2004). Detritus, trophic dynamics and biodiversity. Ecology Letters, 7(7), 584–600. https://doi.org/10.1111/j.1461-0248.2004.00606.x
LIM package, Soetaert & van Oevelen 2015.

Examples

### Energy-flux model defined in R
# Use example food-web model of soil
model <- fwmodels::LovinkhoeveCP
# Create a Jacobian matrix, with a diagonal calculated from the model (default).
JM <- getJacobian(model, diagonal = "model")
# Create a Jacobian matrix, with an all-zero diagonal.
JM <- getJacobian(model, diagonal = 0)
# Create a Jacobian matrix, with -1 on the diagonal.
JM <- getJacobian(model, diagonal = -1)
# Create a Jacobian matrix, with a numeric vector as diagonal
diagonal <- runif(dim(model$FM)[1], min = -1, max = 0)
JM <- getJacobian(model, diagonal = diagonal)
### Energy-flux model defined as a LIM
lim <- Read(system.file("extdata", "foodweb2.lim", package = "fwstability"))
lim_solved <- LIM::Ldei(Setup(lim))
model <- list(type = "LIM", LIM = lim)
JM <- getJacobian(model)

dswdejonge/fwstability documentation built on Dec. 7, 2022, 7:24 p.m.