bcpa (version 1.3.2)

WindowSweep: Perform window sweep for BCPA

Description

This is the workhorse function of the BCPA. It performs a sweep of the time series, searching for most significant change points and identifying the parsimonious model according to an adjusted BIC.

Usage

WindowSweep(
  data,
  variable,
  time.var = "T.mid",
  windowsize = 50,
  windowstep = 1,
  units = "hours",
  K = 2,
  tau = TRUE,
  range = 0.6,
  progress = TRUE,
  plotme = FALSE,
  ...
)

Arguments

data

the data to be analyzed. Generically, the output of the GetVT function containing step lengths, absolute and turning angles, etc, but can be any data frame with a column representing times and any column (or set of columns) that can be converted to a time series for change point analysis.

variable

a character string representing the response variable to apply the BCPA to. For example "V*cos(theta)" for persistence velocity, "log(V)" for log of velocity if the data are outputs of `codeGetVT`. Otherwise, any column (e.g. "Depth") in the data.

time.var

character string for the time variable. The default is T.mid from the output of the `codeGetVT`.

windowsize

integer size of the analysis window as a number of data points (not time units). Should probably be no smaller than 20.

windowstep

integer step size of analysis. Values greater than 1 speed the analysis up.

units

if the times are POSIX, units (one of "secs", "mins", "hours", "days", "weeks") determine the unit of the windowstep.

K

sensitivity parameter for the adjusted BIC. Smaller values make for a less sensitive model selection, i.e. more likely that the null model of no significant changes will be selected.

tau

a logical indicating whether the autocorrelation "rho" or the characteristic time "tau" should be estimated.

range

a number between 0 and 1 that determines the extent of each window that is scanned for changepoints. I.e., if the window is 100 datapoints long, at the default range=0.6, changepoints will be scanned between 20 and 80.

progress

logical - whether or not to output a progress bar as the analysis is being performed.

plotme

logical - whether or not to plot the analysis as it is happening. This slows the analysis considerably, especially in non-dynamic graphic environments like RStudio.

...

additional parameters to be passed to the PartitionParameters function.

Value

an object of class windowsweep, which is a list containing:

ws

a data frame containing the change point, selected model, and parameter estimates

x

the response variable

t

the time variable - in the units specified in the data object

t.POSIX

the time variable as a POSIX object (containing Y-M-D H:S)

windowsize

the window size

windowstep

the window step size

See Also

for internal functions: GetModels, GetBestBreak, GetDoubleL; for summarizing output: ChangePointSummary; for plotting output: plot.bcpa

Examples

# NOT RUN {
# Using the included simulated  movement data
require(bcpa)
data(Simp)
plot(Simp)
Simp.VT <- GetVT(Simp)
## note: column names of Simp.VT include:
###  "S" - step length
### "Theta" - turning angle
###  T.start" "T.end"   "T.mid"  "T.POSIX" - time variables

if(interactive())
  Simp.ws <- WindowSweep(Simp.VT, "V*cos(Theta)", windowsize = 50, 
                         windowstep = 1, progress=TRUE) else
  Simp.ws <- WindowSweep(Simp.VT, "V*cos(Theta)", windowsize = 50, 
                         windowstep = 1, progress=FALSE)

plot(Simp.ws, threshold = 7)
plot(Simp.ws, type = "flat", clusterwidth = 3)
PathPlot(Simp, Simp.ws)
PathPlot(Simp, Simp.ws, type="flat")
DiagPlot(Simp.ws)

# Example of application on one dimensional data (e.g. depth)

# simulate some data with three change points: surface, medium, deep, surface

## random times within 100 hours of now
n.obs <- 100
time = sort(Sys.time() - runif(n.obs, 0, n.obs) * 60 * 60)

d1 <- 50; d2 <- 100
t1 <- 25; t2 <- 65; t3 <- 85
sd1 <- 1; sd2 <- 5; sd3 <- 10

dtime <- as.numeric(difftime(time, min(time), units="hours"))
phases <- cut(dtime, c(-1, t1, t2, t3, 200), labels = c("P1","P2","P3","P4")) 
means <- c(0,d1,d2,0)[phases]
sds <- c(sd1,sd2,sd3,sd1)[phases]
depth <- rnorm(n.obs,means, sds)
# make all depths positive!
depth <- abs(depth)
mydata <- data.frame(time, depth)

# perform windowsweep
ws <- WindowSweep(mydata, "depth", time.var = "time", windowsize = 30, 
                  windowstep = 1, progress=interactive())
plot(ws)
plot(ws, type = "flat", cluster = 6)
ChangePointSummary(ws, cluster = 6)
# }