Intervality {cheddar} | R Documentation

## 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)

### 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.

### 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.

### 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`.

### Author(s)

Lawrence Hudson

### 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)

[Package cheddar version 0.1-633 Index]