R: Fit a Broken Stick Model on Log Frequency Data for...

bout-misc {diveMove} | R Documentation

## Fit a Broken Stick Model on Log Frequency Data for identification of bouts of behaviour

### Description

Application of methods described by Sibly et al. (1990) and Mori et al. (2001) for the identification of bouts of behaviour.

### Usage

    boutfreqs(x, bw, method=c("standard", "seq.diff"), plot=TRUE, ...)
    boutinit(lnfreq, x.break, plot=TRUE, ...)
    labelBouts(x, bec, bec.method=c("standard", "seq.diff"))
    logit(p)
    unLogit(logit)

### Arguments

`x` | numeric vector on which bouts will be identified based on “method”. For `labelBouts` it can also be a matrix with different variables for which bouts should be identified.
`bw` | numeric scalar: bin width for the histogram.
`method, bec.method` | character: method used for calculating the frequencies: “standard” simply uses x, while “seq.diff” uses the sequential differences method.
`plot` | logical, whether to plot results or not.
`...` | For `boutfreqs`, arguments passed to hist (must exclude `breaks` and `include.lowest`); for `boutinit`, arguments passed to `plot` (must exclude `type`).
`lnfreq` | `data.frame` with components lnfreq (log frequencies) and corresponding x (mid points of histogram bins).
`x.break` | vector of length 1 or 2 with `x` value(s) defining the break(s) point(s) for broken stick model, such that `x` < `x.break`[1] is 1st process, and `x` >= `x.break`[1] & `x` < `x.break`[2] is 2nd one, and `x` >= `x.break`[2] is 3rd one.
`bec` | numeric vector or matrix with values for the bout ending criterion which should be compared against the values in x for identifying the bouts.
`p` | numeric vector of proportions (0-1) to transform to the logit scale.
`logit` | numeric scalar: logit value to transform back to original scale.

### Details

This follows the procedure described in Mori et al. (2001), which is based on Sibly et al. 1990. Currently, only a two process model is supported.

`boutfreqs` creates a histogram with the log transformed frequencies of x with a chosen bin width and upper limit. Bins following empty ones have their frequencies averaged over the number of previous empty bins plus one.

`boutinit` fits a "broken stick" model to the log frequencies modelled as a function of x (well, the midpoints of the binned data), using chosen value(s) to separate the two or three processes.

`labelBouts` labels each element (or row, if a matrix) of x with a sequential number, identifying which bout the reading belongs to. The `bec` argument needs to have the same dimensions as `x` to allow for situations where `bec` within `x`.

`logit` and `unLogit` are useful for reparameterizing the negative maximum likelihood function, if using Langton et al. (1995).

### Value

`boutfreqs` returns a data frame with components lnfreq containing the log frequencies and x, containing the corresponding mid points of the histogram. Empty bins are excluded. A plot (histogram of input data) is produced as a side effect if argument plot is `TRUE`. See the Details section.

`boutinit` returns a list with as many elements as the number of processes implied by `x.break` (i.e. `length(x.break) + 1`). Each element is a vector of length two, corresponding to `a` and `lambda`, which are starting values derived from broken stick model. A plot is produced as a side effect if argument `plot` is `TRUE`.

`labelBouts` returns a numeric vector sequentially labelling each row or element of x, which associates it with a particular bout.

`unLogit` and `logit` return a numeric vector with the (un)transformed arguments.

### Author(s)

Sebastian P. Luque spluque@gmail.com

### References

Langton, S.; Collett, D. and Sibly, R. (1995) Splitting behaviour into bouts; a maximum likelihood approach. Behaviour 132, 9-10.

Luque, S.P. and Guinet, C. (2007) A maximum likelihood approach for identifying dive bouts improves accuracy, precision, and objectivity. Behaviour, 144, 1315-1332.

Mori, Y.; Yoda, K. and Sato, K. (2001) Defining dive bouts using a sequential differences analysis. Behaviour, 2001 138, 1451-1466.

Sibly, R.; Nott, H. and Fletcher, D. (1990) Splitting behaviour into bouts. Animal Behaviour 39, 63-69.

### See Also

`bouts2.nls`, `bouts.mle`. These include an example for `labelBouts`.

### Examples

    ## Too long for checks
    ## Using the Example from '?diveStats':
    utils::example("diveStats", package="diveMove",
                   ask=FALSE, echo=FALSE, run.donttest=TRUE)
    postdives <- tdrX.tab$postdive.dur[tdrX.tab$phase.no == 2]
    ## Remove isolated dives
    postdives <- postdives[postdives < 2000]
    lnfreq <- boutfreqs(postdives, bw=0.1, method="seq.diff", plot=FALSE)
    boutinit(lnfreq, 50)

    ## See ?bouts.mle for labelBouts() example

[Package diveMove version 1.5.2 Index]