Skip to content

Commit

Permalink
Implemented generalized 2- or 3-process Poisson mixture analyses
Browse files Browse the repository at this point in the history 
Also moved all documentation to roxygen.
  • Loading branch information
Sebastian Luque committed May 12, 2021
1 parent 58a4a16 commit 7a71a91
Show file tree
Hide file tree
Showing 70 changed files with 5,336 additions and 3,601 deletions.
1 change: 1 addition & 0 deletions .Rbuildignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,4 @@ EXAMPLES.*
^.AppleDouble$
^vignettes/auto$
^src/\.clang-format$
man-roxygen
13 changes: 8 additions & 5 deletions DESCRIPTION
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Package: diveMove
Type: Package
Title: Dive Analysis and Calibration
Version: 1.5.4
Version: 1.6.0
Depends: R (>= 3.5.0), methods, stats4
Suggests: knitr, lattice, pander, rmarkdown, tinytest
Imports: geosphere, KernSmooth, plotly, quantreg, uniReg
Expand All @@ -12,14 +12,17 @@ Description: Utilities to represent, visualize, filter, analyse, and summarize
handling location data are also provided.
LazyLoad: yes
LazyData: no
Encoding: UTF-8
ZipData: no
BuildResaveData: no
VignetteBuilder: knitr
Collate: AllClass.R AllGenerics.R AllMethod.R austFilter.R bouts.R calibrate.R
detDive.R detPhase.R distSpeed.R diveStats.R oneDiveStats.R plotTDR.R
plotZOC.R readLocs.R readTDR.R runquantile.R speedStats.R stampDive.R
zoc.R zzz.R
Collate: AllClass.R AllGenerics.R AllMethod.R austFilter.R bouts_helpers.R
bouts.R calibrate.R detDive.R detPhase.R distSpeed.R diveStats.R
oneDiveStats.R plotTDR.R plotZOC.R readLocs.R readTDR.R runquantile.R
speedStats.R stampDive.R zoc.R diveMove-deprecated.R
diveMove-defunct.R zzz.R
NeedsCompilation: yes
License: GPL-3
URL: https://github.com/spluque/diveMove
BugReports: https://github.com/spluque/diveMove/issues
RoxygenNote: 7.1.1
41 changes: 25 additions & 16 deletions NAMESPACE
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ importFrom(grDevices, colorRampPalette, contourLines, dev.off, hsv, rgb)
importFrom(plotly,
plot_ly, add_lines, add_markers, subplot, "%>%")
importFrom(stats, approx, approxfun, bw.nrd, ecdf, lm, median, nls,
nls.control, predict, quantile, sd, smooth.spline, splinefun)
nls.control, predict, quantile, rexp, sd, smooth.spline,
splinefun, stepfun)
importFrom(utils, read.csv)

## bkde2d and rq for speed calibration
Expand All @@ -27,35 +28,46 @@ export("grpSpeedFilter",
"logit",
"unLogit",
"boutfreqs",
"boutinit",
"bouts2.nlsFUN",
"bouts2.nls",
"bouts3.nlsFUN",
"bouts3.nls",
"labelBouts",
"bouts2.mleFUN",
"bouts2.ll",
"bouts2.LL",
"bouts.mle",
## "boutsCDF",
"calibrateDepth",
"calibrateSpeed",
"rqPlot",
"distSpeed",
"diveStats",
"oneDiveStats",
"plotBouts2.cdf",
"readLocs",
"readTDR",
"rmixexp",
"createTDR",
"stampDive")
## Deprecated functions
export("bouts2.nlsFUN",
"bouts2.nls",
"bec2",
"bec3",
"bouts3.nlsFUN",
"bouts3.nls",
"bouts2.mleFUN")
## Defunct functions
export("bouts2.ll",
"bouts2.LL",
"bouts.mle")

exportClasses("TDR",
"TDRspeed",
"TDRcalibrate",
"Bouts",
"diveModel")

exportMethods("as.data.frame",
"as.TDRspeed",
"bec",
"boutinit",
"fitNLSbouts",
"fitMLEbouts",
"plotBouts",
"plotBoutsCDF",
"labelBouts",
"timeBudget",
"coerce",
"depth<-",
Expand All @@ -78,7 +90,4 @@ exportMethods("as.data.frame",
"getTDR",
"getTime",
"getSpeedCoef",
"getSpeed",
"plotBouts",
"bec2",
"bec3")
"getSpeed")
13 changes: 13 additions & 0 deletions NEWS
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,16 @@
Changes in version 1.6.0:

o Analyses for 2- and 3-process Poisson mixtures are now fully
implemented. The bout analysis module has a new API, which includes a
new S4 class `Bouts' for representing Poisson process mixtures, and S4
methods and functions for performing related analyses. As a result,
most functions for bout analyses in previous diveMove versions have
been deprecated or are defunct. Please see
help("diveMove-deprecated") and help("diveMove-defunct") for details.

o New function rmixexp() for sampling from mixtures of exponential
distributions, as parameterized in Langton et al. (1990).

Changes in version 1.5.4:

o Internal function .speedStats() now guarantees numeric matrix output,
Expand Down
211 changes: 210 additions & 1 deletion R/AllClass.R
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,33 @@

##' Classes "TDR" and "TDRspeed" for representing TDR information
##'
##' These classes store information gathered by time-depth recorders.
##'
##' Since the data to store in objects of these clases usually come from a
##' file, the easiest way to construct such objects is with the function
##' \code{\link{readTDR}} to retrieve all the necessary information.
##'
##' @aliases TDR
##' @slot file Object of class \sQuote{character}, string indicating the
##' file where the data comes from.
##' @slot dtime Object of class \sQuote{numeric}, sampling interval in
##' seconds.
##' @slot time Object of class \code{\link{POSIXct}}, time stamp for every
##' reading.
##' @slot depth Object of class \sQuote{numeric}, depth (m) readings.
##' @slot concurrentData Object of class \code{\link{data.frame}}, optional
##' data collected concurrently.
##' @section Objects from the class:
##' Objects can be created by calls of the form \code{new("TDR", \dots)}
##' and \code{new("TDRspeed", \dots)}.
##'
##' \sQuote{TDR} objects contain concurrent time and depth readings, as
##' well as a string indicating the file the data originates from, and a
##' number indicating the sampling interval for these data.
##' \sQuote{TDRspeed} extends \sQuote{TDR} objects containing additional
##' concurrent speed readings.
##' @author Sebastian P. Luque \email{spluque@@gmail.com}
##' @seealso \code{\link{readTDR}}, \code{\link{TDRcalibrate}}.
##' @keywords classes
setClass("TDR",
slots=c(file="character", dtime="numeric", time="POSIXct",
depth="numeric", concurrentData="data.frame"),
Expand All @@ -25,6 +54,9 @@ setClass("TDR",
})

.speedNames <- c("velocity", "speed")

##' @describeIn TDR Class \code{TDRspeed}
##' @aliases TDRspeed
setClass("TDRspeed", contains="TDR",
validity=function(object) {
ccData <- object@concurrentData
Expand All @@ -38,6 +70,80 @@ setClass("TDRspeed", contains="TDR",
return(TRUE)
})

##' Class "TDRcalibrate" for dive analysis
##'
##' This class holds information produced at various stages of dive
##' analysis. Methods are provided for extracting data from each slot.
##'
##' This is perhaps the most important class in diveMove, as it holds all
##' the information necessary for calculating requested summaries for a
##' TDR.
##'
##' @aliases TDRcalibrate
##' @slot call Object of class \code{\link{call}}. The matched call to the
##' function that created the object.
##' @slot tdr Object of class \code{\link{TDR}}. This slot contains the
##' time, zero-offset corrected depth, and possibly a data frame. If
##' the object is also of class "TDRspeed", then the data frame might
##' contain calibrated or uncalibrated speed. See
##' \code{\link{readTDR}} and the accessor function
##' \code{\link{getTDR}} for this slot.
##' @slot gross.activity Object of class \sQuote{list}. This slot holds a
##' list of the form returned by \code{\link{.detPhase}}, composed of 4
##' elements. It contains a vector (named \code{phase.id}) numbering
##' each major activity phase found in the record, a factor (named
##' \code{activity}) labelling each row as being dry, wet, or trivial
##' wet activity. These two elements are as long as there are rows in
##' \code{tdr}. This list also contains two more vectors, named
##' \code{begin} and \code{end}: one with the beginning time of each
##' phase, and another with the ending time; both represented as
##' \code{\link{POSIXct}} objects. See \code{\link{.detPhase}}.
##' @slot dive.activity Object of class \code{\link{data.frame}}. This
##' slot contains a \code{\link{data.frame}} of the form returned by
##' \code{\link{.detDive}}, with as many rows as those in \code{tdr},
##' consisting of three vectors named: \code{dive.id}, which is an
##' integer vector, sequentially numbering each dive (rows that are not
##' part of a dive are labelled 0), dive.activity is a factor which
##' completes that in \code{activity} above, further identifying rows
##' in the record belonging to a dive. The third vector in
##' \code{dive.activity} is an integer vector sequentially numbering
##' each postdive interval (all rows that belong to a dive are labelled
##' 0). See \code{\link{.detDive}}, and \code{\link{getDAct}} to
##' access all or any one of these vectors.
##' @slot dive.phases Object of class \sQuote{factor}. This slot is a
##' factor that labels each row in the record as belonging to a
##' particular phase of a dive. It has the same form as the
##' \dQuote{phase.labels} component of the list returned by
##' \code{\link{.labDivePhase}}.
##' @slot dive.models Object of class \sQuote{list}. This slot contains
##' the details of the process of dive phase identification for each
##' dive. It has the same form as the \code{dive.models} component of
##' the list returned by \code{\link{.labDivePhase}}. It has as many
##' components as there are dives in the \code{\link{TDR}} object, each
##' of them of class \code{\link{diveModel}}.
##' @slot dry.thr Object of class \sQuote{numeric}. The temporal criteria
##' used for detecting dry periods that should be considered as wet.
##' @slot wet.thr Object of class \sQuote{numeric} the temporal criteria
##' used for detecting periods wet that should not be considered as
##' foraging time.
##' @slot dive.thr Object of class \sQuote{numeric}. The temporal criteria
##' used for detecting periods wet that should not be considered as
##' foraging time.
##' @slot speed.calib.coefs Object of class \sQuote{numeric}. The
##' intercept and slope derived from the speed calibration procedure.
##' Defaults to c(0, 1) meaning uncalibrated speeds.
##' @section Objects from the Class:
##'
##' Objects can be created by calls of the form \code{new("TDRcalibrate",
##' \dots{})}. The objects of this class contain information necessary to
##' divide the record into sections (e.g. dry/water), dive/surface, and
##' different sections within dives. They also contain the parameters used
##' to calibrate speed and criteria to divide the record into phases.
##' @author Sebastian P. Luque \email{spluque@@gmail.com}
##' @seealso \code{\link{TDR}} for links to other classes in the package.
##' \code{\link{TDRcalibrate-methods}} for the various methods
##' available.
##' @keywords classes
setClass("TDRcalibrate",
slots=c(call="call", tdr="TDR", gross.activity="list",
dive.activity="data.frame", dive.phases="factor",
Expand Down Expand Up @@ -72,6 +178,76 @@ setOldClass("smooth.spline")
setOldClass("bSpline")
setClassUnion("dive.spline", c("smooth.spline", "bSpline"))
setOldClass("xyVector")

##' Class "diveModel" for representing a model for identifying dive phases
##'
##' Details of model used to identify the different phases of a dive.
##' @aliases diveModel
##' @slot label.matrix Object of class \code{"matrix"}. A 2-column
##' character matrix with row numbers matching each observation to the
##' full \code{\link{TDR}} object, and a vector labelling the phases of
##' each dive.
##' @slot model Object of class \code{"character"}. A string identifying
##' the specific model fit to dives for the purpose of dive phase
##' identification. It should be one of \sQuote{smooth.spline} or
##' \sQuote{unimodal}.
##' @slot dive.spline Object of class \code{"smooth.spline"}. Details of
##' cubic smoothing spline fit (see
##' \code{\link[stats]{smooth.spline}}).
##' @slot spline.deriv Object of class \code{"list"}. A list with the
##' first derivative of the smoothing spline (see
##' \code{\link[stats]{predict.smooth.spline}}).
##' @slot descent.crit Object of class \code{"numeric"}. The index of the
##' observation at which the descent was deemed to have ended (from
##' initial surface observation).
##' @slot ascent.crit Object of class \code{"numeric"}. the index of the
##' observation at which the ascent was deemed to have ended (from
##' initial surface observation).
##' @slot descent.crit.rate Object of class \code{"numeric"}. The rate of
##' descent corresponding to the critical quantile used.
##' @slot ascent.crit.rate Object of class \code{"numeric"}. The rate of
##' ascent corresponding to the critical quantile used.
##' @section Objects from the Class:
##' Objects can be created by calls of the form \code{new("diveModel",
##' ...)}.
##'
##' \sQuote{diveModel} objects contain all relevant details of the process to
##' identify phases of a dive. Objects of this class are typically generated
##' during depth calibration, using \code{\link{calibrateDepth}}, more
##' specifically \code{\link{.cutDive}}.
##' @author Sebastian P. Luque \email{spluque@@gmail.com}
##' @seealso \code{\link{getDiveDeriv}}, \code{\link{plotDiveModel}}
##' @keywords classes
##' @examples
##' showClass("diveModel")
##'
##' \donttest{## Too long for checks
##' ## Continuing the Example from '?calibrateDepth':
##' utils::example("calibrateDepth", package="diveMove",
##' ask=FALSE, echo=FALSE, run.donttest=TRUE)
##' dcalib # the 'TDRcalibrate' that was created
##'
##' ## Compare dive models for dive phase detection
##' diveNo <- 255
##' diveX <- as.data.frame(extractDive(dcalib, diveNo=diveNo))
##' diveX.m <- cbind(as.numeric(row.names(diveX[-c(1, nrow(diveX)), ])),
##' diveX$depth[-c(1, nrow(diveX))],
##' diveX$time[-c(1, nrow(diveX))])
##'
##' ## calibrateDepth() default unimodal regression. Number of inner knots is
##' ## either 10 or the number of samples in the dive, whichever is larger.
##' (phases.uni <- diveMove:::.cutDive(diveX.m, smooth.par=0.2, knot.factor=20,
##' dive.model="unimodal",
##' descent.crit.q=0.01, ascent.crit.q=0))
##' ## Smoothing spline model, using default smoothing parameter.
##' (phases.spl <- diveMove:::.cutDive(diveX.m, smooth.par=0.2, knot.factor=20,
##' dive.model="smooth.spline",
##' descent.crit.q=0.01, ascent.crit.q=0))
##' plotDiveModel(phases.spl,
##' diveNo=paste(diveNo, ", smooth.par=", 0.2, sep=""))
##' plotDiveModel(phases.uni, diveNo=paste(diveNo))
##'
##' }
setClass("diveModel",
slots=c(label.matrix="matrix", model="character",
dive.spline="dive.spline", spline.deriv="xyVector",
Expand All @@ -97,3 +273,36 @@ setClass("diveModel",
})

setOldClass("nls") # For bout methods

##' Class "Bouts" for representing Poisson mixtures for identification of
##' behavioural bouts
##'
##' Base class for storing key information for modelling and detecting
##' bouts in behavioural data.
##' @aliases Bouts
##' @slot x Object of class \code{"numeric"}. Data to be modelled.
##' @slot method Object of class \code{"character"}. A string indicating
##' the type of frequency to calculate from \code{x}: "standard" or
##' "seq.diff". If "standard", frequencies are calculated directly
##' from \code{x}, and from the sequential differences in \code{x}
##' otherwise.
##' @slot lnfreq Object of class \code{\link{data.frame}}. Columns named
##' \var{lnfreq} (log frequencies) and \var{x} (mid points of histogram
##' bins).
##' @section Objects from the class:
##' Objects can be created most conveniently via the
##' \code{\link{boutfreqs}} function, which sets the \code{lnfreq} slot,
##' but can also be created via \code{new("Bouts")}.
##' @author Sebastian P. Luque \email{spluque@@gmail.com}
##' @seealso \code{\link{boutfreqs}}
##' @keywords classes
setClass("Bouts",
slots=c(x="numeric", method="character", lnfreq="data.frame"),
prototype=prototype(method="standard", lnfreq=data.frame()),
validity=function(object) {
meths <- c("standard", "seq.diff")
meths.msg = paste(meths, collapse=", ")
if (! object@method %in% meths)
return(paste("method must be one of:", meths.msg))
return(TRUE)
})
Loading

0 comments on commit 7a71a91

Please sign in to comment.