cheddar (version 0.1-639)

Intervality: Food web Intervality

Description

Functions for computing the sum diet/consumer gaps of each species in a Community and for minimising the sum diet/consumer gaps using a simulated annealing learning method.

Usage

SumDietGaps(community)
SumConsumerGaps(community)
MinimiseSumDietGaps(community, T.start = 10, T.stop = 0.1, c = 0.9, 
                    swaps.per.T = 1000, trace.anneal = FALSE, n = 1, 
                    best = TRUE)
MinimiseSumConsumerGaps(community, T.start = 10, T.stop = 0.1, c = 0.9, 
                        swaps.per.T = 1000, trace.anneal = FALSE, n = 1, 
                    best = TRUE)

Value

For SumDietGaps and SumConsumerGaps, a single number. For the two minimisation functions, if n is 1 or best is TRUE, a list containing the values

sum.gaps

the lowest SumDietGaps or SumConsumerGaps resulting from the best ordering that was found.

order

a vector of node names giving the best ordering.

reordered

community reordered by the best ordering.

If n is greater than 1 and best is FALSE then a list of n lists, each list containing the above three values, sorted by increasing sum.gaps.

Arguments

community

an object of class Community.

T.start

the temperature at which annealing starts; must be >0

T.stop

annealing will stop when the system temperature drops below T.stop; must be >0 and <T>start

c

cooling coefficient; must be >0 and <1.

swaps.per.T

the number of predation matrix row swaps per temperature.

trace.anneal

logical - if TRUE the annealing process prints feedback.

n

numeric - the number of repetitions of the minimisation procedure.

best

logical - if TRUE then only the result of the best of the n minimsations is returned.

Author

Lawrence Hudson

Details

SumDietGaps and SumConsumerGaps return the total number of gaps in each species' diet (Stouffer et al 2006) and each species' consumers (Zook et al 2011) respectively.

MinimiseSumDietGaps and MinimiseSumConsumerGaps use the simulated annealing learning method described by Stouffer et al (2006) to minimise either SumDietGaps or SumConsumerGaps. Simulated annealing learning is a stochastic method so several optimisations might be required to find the global minimum. Use a value of n greater than 1 to perform several optimisations.

References

Stouffer, D.B. and Camacho, J. and Amaral, L.A.N. (2006) Proceedings of the National Academy of Sciences of the United States of America 103, 50, 19015--19020.

Zook, A.E. and Eklof, A. and Jacob, U. and Allesina, S. (2011) Journal of Theoretical Biology 271, 1 106--113.

See Also

Community, OrderCommunity, PredationMatrix, PlotPredationMatrix

Examples

data(TL84)
# Perform 5 independent optimisations
res <- MinimiseSumDietGaps(TL84, n=5)

# Compare the original, ordered by body mass and minimised predation matrices
par(mfrow=c(1,3))
PlotPredationMatrix(TL84, main=paste('Sum diet gap', SumDietGaps(TL84)))
TL84.by.M <- OrderCommunity(TL84, 'M')
PlotPredationMatrix(TL84.by.M, 
                    main=paste('Sum diet gap', SumDietGaps(TL84.by.M)))
PlotPredationMatrix(res$reordered, main=paste('Sum diet gap', res$sum.gaps))

# The same comparison but retaining the original column ordering
par(mfrow=c(1,3))
PlotPredationMatrix(TL84)
PlotPredationMatrix(TL84, resource.order=NP(TL84.by.M, 'node'))
PlotPredationMatrix(TL84, resource.order=res$order)