fluxing: generate fluxes
In fluxweb: Estimate Energy Fluxes in Food Webs

Description Usage Arguments Details Value Author(s) Examples

Creates a valuated graph adjacency matrix from its binary version.

1 2	fluxing(mat, biomasses = NULL, losses, efficiencies, bioms.prefs = TRUE, bioms.losses = TRUE, ef.level = "prey")

`mat`	Network adjacency matrix describing interactions among species. Interactions can be either binary or weighted.
`biomasses`	Vector of species biomasses.
`losses`	A vector or an array of species energy losses (excluding consumption).
`efficiencies`	A vector or an array of conversion efficiencies of species in the adjacency matrix. These values describe the proportion of consumed energy that is converted to biomass of the consumer.
`bioms.prefs`	Logical - if `TRUE`, consumer preferences are scaled according to species biomasses.
`bioms.losses`	Logical - if `TRUE`, losses are scaled with species biomasses.
`ef.level`	Set to `"prey"` if efficiencies are defined by prey, `"pred"` if they are a property of the predator.

This function computes fluxes in food webs based on an equilibrium hypothesis: for each species, sum of ingoing fluxes (gains from predation) balances the sum of outgoing fluxes. Outgoing fluxes are defined by consumption and the losses argument. Usually losses relate to species metabolic rates and/or natural death rates. For each species i, sum of ingoing fluxes F_i is computed as:

F_{i} = \frac{1}{e_i} (L_i + ∑_j W_{ij}F_j) \quad if \quad \code{ef.level == "pred"}

F_{i} = \frac{L_i + ∑_j W_{ij}F_j}{∑_j W_{ji}e_j} \quad if \quad \code{ef.level == "pred"}

W set the matrix of preferences estimated from mat, according to bioms.prefs. L is the vector depicting sum of losses (scaled or not by biomasses, accordingly to bioms.losses) and e is the vector of species efficiencies.

mat: Either a binary or a valuated matrix can be used. A non zero value for mat[i,j] means that species i is consumed by species j. Matrix entries would assess predator preferences on its prey, thus providing a binary matrix assumes no preferences.
losses: Express species energetic losses not related to consumption. Usually metabolic or death rates. When an array is provided, losses associated to each species correspond to line sums.
efficiencies: Determines how efficient species are to convert energy (see ef.level for more details). Providing an array will assume values depending on both prey and predator identity.
bioms.pref: If TRUE, preferences W_{ij} of predator j on prey i are scaled accordingly to species biomass using the following formula:

W_{i,j} = \frac{mat[i,j] * biomasses[i]}{∑_k mat[i,k]* biomasses[k]}

If FALSE, a normalisation on column values is performed.
bioms.losses: Set to true, function will assume that losses are defined per biomass unit. Thus, total losses will be thereafter multiplied by biomass values for each species.
ef.level: If "prey" (resp "pred"), the total amount of energy that can be metabolized from a trophic link will be determined by prey (resp predator) identity. "link.specific" assumes that efficiencies are defined for each trophic interaction and implies efficiencies parameter to be a matrix.

Returns an adjacency matrix where entries are the computed energy fluxes between consumer species and their respective resources.

Benoit gauzens, benoit.gauzens@gmail.com

# first compute species per unit biomass metabolic rates using the metabolic theory:
losses = 0.1 * species.level$bodymasses^(-0.25)

# call of the function:
fluxing(species.level$mat, 
       species.level$biomasses, 
       losses, 
       species.level$efficiencies, 
       bioms.pref = TRUE, 
       ef.level = "prey")