Fits predator-prey functional responses and returns data in a consistent, predictable way, exposing some useful methods.

1 |

`formula ` |
A simple formula of the form |

`data ` |
The dataframe containing |

`response ` |
A string denoting the response to fit. See Details. |

`start ` |
A named list. Starting values for optimised parameters. |

`fixed ` |
A named list. Values that are not optimised. |

`frair_fit`

is a utility function which helps users fit common non-linear predator-prey curves to integer data. It uses maximum likelihood estimation, via `mle2`

from the `bbmle`

package.

The response requested must be known to FRAIR. To establish what is supported, inspect the output from `frair_responses()`

. All parameters listed by `frair_responses()`

(except `X`

) must be provided in either `start`

or `fixed`

and some guidance is given on the help pages for each function about what should (and should not) be optimised.

Generally speaking fitting non-linear curves to ecological datasets can be challenging. Approaches to fitting predator-prey functional response curves are described in further detail by Juliano (2001) and Bolker (2008). Many of the pitfalls (along with very sound advice) in non-linear curve fitting in general are described by Bolker *et al.* 2013. Users are directed there for more information.

Note that currently all fits encoded by FRAIR use the `optim`

optimiser with a non-default number of iterations (5000 [frair] vs. 500 [default]) and that all fits except `typeI`

use the 'Nelder-Mead' method (see Note). This is different from the mle2 default, which currently (bbmle v. 1.0.15) uses the 'BFGS' method.

`mle2`

is clever inasmuch as it will return fitted values even if inverting the Hessian matrix at the optimum fails. However, this will result in a warning along the lines of:

1 2 3 |

If this happens it could mean many things, but generally speaking it is indicative of a poor fit to the data. You might consider:

Checking the data for transcription errors or outliers

Trying different starting values

Trying a different (simpler) curve

Fitting the curve outside of FRAIR using another optimiser or another approach (see the Note, below)

Collecting more data

Note that the advice given in mle2 to use the 'Nelder-Mead' method, is largely redundant because this is already the default in FRAIR (though you could try the 'BFGS' method quite safely...)

If convergence (i.e. fitting) fails for other reasons, see the manual page of `optim`

.

This function returns a named list of class `frfit`

with the following named items:

`call ` |
The original call to |

`x ` |
The original x data supplied to |

`y ` |
The original y data supplied to |

`response ` |
A string. The fitted response. |

`xvar ` |
A string. The right hand side of |

`yvar ` |
A string. The left hand side of |

`optimvars ` |
A character vector. The optimised values (passed to |

`fixedvars ` |
A character vector. The fixed values (passed to |

`coefficients ` |
A named numeric. All coefficients needed to draw the optimised curve. |

`sample ` |
A numeric vector. Always |

`fit ` |
The raw object returned by |

Objects of class `frfit`

have print, plot and lines methods defined. See the help for those methods for more information.

Future versions will allow the user more control over the underlying fitting algorithms. In the meantime FRAIR exports all of its (useful) functions so that users can fit the curves directly using their preferred method if the defaults are undesirable. See the Examples for an illustration of this approach.

Daniel Pritchard

Juliano SA (2001) *Nonlinear curve fitting: Predation and functional response curves*. In: Scheiner SM, Gurevitch J (eds). *Design and analysis of ecological experiments*. Oxford University Press, Oxford, United Kingdom. pp 178–196.

Bolker BM (2008) *Ecological Models and Data in R*. Princeton University Press, Princeton, NJ.

Bolker BM and others (2013) *Strategies for fitting nonlinear ecological models in R, AD Model Builder, and BUGS*. Methods in Ecology and Evolution 4: 501–512. doi:10.1111/2041-210X.12044.

`frair_boot`

, `frair_responses`

, `fr_rogersII`

.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 | ```
data(gammarus)
frair_responses() # See what is available
# A typeII fit
outII <- frair_fit(eaten~density, data=gammarus, response='rogersII',
start=list(a = 1.2, h = 0.015), fixed=list(T=40/24))
# A linear fit
outI <- frair_fit(eaten~density, data=gammarus, response='typeI',
start=list(a=0.5), fixed=list(T=40/24))
# Visualise fits
plot(outII, pch=20, col=rgb(0,0,0,0.2), xlim=c(0,30))
lines(outII)
lines(outI, lty=3)
# Have a look at original fits returned by mle2 (*highly* recommended)
summary(outII$fit)
summary(outI$fit)
# Compare models using AIC
AIC(outI$fit,outII$fit)
# Bythotrephes
data("bythotrephes")
# Fit several models and examine them using AIC.
b_flex <- frair_fit(eaten~density, data=bythotrephes,
response='flexpnr',
start=list(b = 1.2, q = 0, h = 0.015),
fixed=list(T=12/24))
b_II <- frair_fit(eaten~density, data=bythotrephes,
response='flexpnr',
start=list(b = 1.2, h = 0.015),
fixed=list(T=12/24, q = 0))
b_rogersII <- frair_fit(eaten~density, data=bythotrephes,
response='rogersII',
start=list(a = 1.2, h = 0.015),
fixed=list(T=12/24))
AIC(b_flex$fit, b_II$fit, b_rogersII$fit)
AICtab(b_flex$fit, b_II$fit, b_rogersII$fit)
# b_II and b_rogersII are identical, by definition when q = 0
# b_flex is strongly preferred (delta AIC = 16.9)
# The role of T
## Users need to be aware that changing T will change
## the units of fitted coefficients.
## For example, with the Gammarus dataset:
g_T1 <- frair_fit(formula = eaten~density, data = gammarus,
response = "rogersII",
start = list(a = 2, h = 0.1), fixed = list(T = 1))
g_Td <- frair_fit(formula = eaten~density, data = gammarus,
response = "rogersII",
start = list(a = 1, h = 0.1), fixed = list(T = 40/24))
g_Th <- frair_fit(formula = eaten~density, data = gammarus,
response = "rogersII",
start = list(a = 0.05, h = 4), fixed = list(T = 40))
diff_t <- round(rbind(coef(g_T1), coef(g_Td), coef(g_Th)), 2)
row.names(diff_t) <- c("g_T1 (Experimental Time)", "g_Td (Days)", "g_Th (Hours)")
print(diff_t)
## Not run:
## Fitting curves outside of FRAIR
# Many advanced users will not be satisfied with FRAIR current limitations.
# To fit models outside FRAIR, you could proceed as follows:
# Using mle2 or mle manually:
strt <- list(a = 1.2, h = 0.015)
fxd <- list(T=40/24)
dat <- list('X'=gammarus$density, 'Y'=gammarus$eaten)
manual_fit <- mle2(rogersII_nll, start=strt, fixed=fxd,
method='SANN', data=dat)
# Note that the SANN method is *not* a general-purpose algorithm,
# but it will return *something*, so might be helpful for finding starting values.
# Controlling iterations, optimisers, etc... See ?mle2 and ?optim
cntrl <- list(trace = 3, maxit = 1000)
manual_fit_2 <- mle2(rogersII_nll, start=strt, fixed=fxd,
method='BFGS', data=dat, control=cntrl)
## End(Not run)
``` |

Questions? Problems? Suggestions? Tweet to @rdrrHQ or email at ian@mutexlabs.com.

Please suggest features or report bugs with the GitHub issue tracker.

All documentation is copyright its authors; we didn't write any of that.