Compute 95% studentized CI across tracklets and time.

Given an object of class "tracklets" containing a list of tracklets (including the timeline) and a custom function, this function perform the computation specified by the custom function across time and compute studentized 95% confidence interval (CI) by bootstrapping the results over the tracklets.

Usage

temporalBoot(
  trackDat,
  timeCol = "frame",
  customFunc = NULL,
  Tinterval = NULL,
  Tstep = 1,
  sampling = 1,
  bootn = 500,
  wtd = FALSE,
  progress = TRUE
)

Arguments

trackDat: An object of class "tracklets" containing a list of tracklets and their characteristics classically used for further computations (at least x.pos, y.pos, frame).
timeCol: A character string corresponding to the name of the column containing Time information (default = 'frame').
customFunc: A function or a list of functions used to perform the computation across time. NB: in case customFunc is a list of unnamed function it will try to retrieve their names by returning the first character string following the function() call as the name of the results column.
Tinterval: A vector containing two numeric values expressed in the timeline unit and specifying the time interval on which the computation is performed (default is null, meaning the computation will be performed on the whole timeline).
Tstep: A numeric value expressed in the timeline unit and specifying the size of the sliding window used to perform the computation (e.g., a value of 200, mean that for each sampling point, the computation is performed using the 100 previous and the 100 next values).
sampling: A numeric value expressed in the timeline unit and specifying a subsampling used to to perform the computation, allow to make computation faster, it hence determine the resolution of the returned results (e.g., a value of 5000 mean that values will be computed every 5000 time units).
bootn: A numeric value indicating the number of bootstrap sampling used to compute studentize 95%IC.
wtd: A logical value (i.e., TRUE or FALSE) indicating whether the function should compute a weighed metric according to the length of the tracklets (default is FALSE).
progress: A logical value (i.e., TRUE or FALSE) indicating whether a progress bar should be displayed to inform process progression (default = TRUE).

Value

this function returns a list containing two elements:

"BootCiStudent": a list containing as much data frame as the number of custom functions specified by the customFunc argument. Each dataframe contains:
- "97.5%": the upper limit of the studentized confidence interval (97.5%).
- "2.5%": the lower limit of the studentized confidence interval (2.5%).
- "mean": the result of the computation performed according to the customFunc and averaged over the sliding window specified by the Tstep argument.
- "timeCol": the timeline according to timeCol and sampling arguments.
- "nbTracklets": the number of tracklets included within each computation.
"BootSampling": a list of sublists corresponding to the sampling points according to timeCol and sampling arguments. Each sublist contains:
- "UnWtd_Result" or "wtd_Result": a dataframe containing either unweighted or weighted mean and sd for each customFunc according to the wtd argument.
- "sampled_Tracklets": a list of matrices (one matrix per customFunc) containing the identity of the sampled tracklets (rows) over each bootstrap sampling (columns).
- "sampled_Values": a list of matrices (one matrix per customFunc) containing the value returned by a given customFunc (rows) over each bootstrap sampling (columns).
- "omitted_Tracklets": a list of matrices (one matrix per customFunc) containing the identity of the omitted tracklets (rows) over each bootstrap sampling (columns). Tracklet omission may occur when a given customFunc returns NA. This list is only included in the output if at least one tracklets have been omitted.

Author

Quentin PETITJEAN

Examples


set.seed(2023)
# generate some dummy tracklets
## start to specify some parameters to generate tracklets
TrackN <- 25 # the number of tracklet to simulate
TrackL <-
  100:1000 # the length of the tracklets or a sequence to randomly sample tracklet length
id <- 0
TrackList <- MoveR::trackletsClass(stats::setNames(lapply(lapply(seq(TrackN), function(i)
  trajr::TrajGenerate(sample(TrackL, 1), random = TRUE, fps = 1)), function(j) {
    id <<- id + 1
    data.frame(
      x.pos = j$x - min(j$x),
      y.pos = j$y - min(j$y),
      frame = j$time,
      identity = paste("Tracklet", id, sep = "_")
    )
  }), seq(TrackN)))

# check the tracklets
MoveR::drawTracklets(TrackList)


# add some metric to the dataset (speed and turning angle) and time unit conversion
TrackListV1 <-
  MoveR::analyseTracklets(
    TrackList,
    customFunc = list(
      # specify a first function to compute speed over each tracklet (a modulus present within the MoveR package)
      speed = function(x)
        MoveR::speed(x,
                     timeCol = "frame",
                     scale = 1),
      # compute turning angle in radians over each tracklet (a modulus present within the MoveR package)
      TurnAngle = function(x)
        MoveR::turnAngle(
          x,
         unit = "radians",
          timeCol = "frame",
         scale = 1
        ),
      # convert the time expressed in frame in second using a conversion factor of 25 frame per second
      TimeSec = function(x)
        x[["frame"]] / 25,
      # or in minutes
      TimeMin = function(x)
        x[["frame"]] / 25 / 60
    )
  )

# smooth the speed and the turning angle across tracklets and time, and compute studentize 95% CI using bootstrap with 999 sampling.
# Here the computation is performed every 50 time unit and over an interval of 100 values, 
# 50 values are taken before and 50 values after the given time unit.
SmoothedtracksBoot <- MoveR::temporalBoot(
  trackDat = TrackListV1,
  timeCol = "frame",
  Tstep = 100,
  sampling = 50,
  wtd = TRUE,
  bootn = 999,
  customFunc = list(
    MeanSpeed = function(x)
      mean(x[["speed"]], na.rm = T),
    MeanTurnAngle = function(x)
      mean(x[["TurnAngle"]], na.rm = T)
  )
)

# plot the results
## need to remove the NA introduced during smoothing to plot the 95% CI envelope
SmoothedtracksBootCInoNA <-
  lapply(SmoothedtracksBoot[["BootCiStudent"]], function(x)
    x[!is.na(x[["mean"]]),])

## plot the mean and the 95% CI envelope by looping through the list containing the smoothed results for the speed and the turning angle
par(mfrow = c(1, 2))
for (i in seq(length(SmoothedtracksBootCInoNA))) {
  plot(
    SmoothedtracksBootCInoNA[[i]]$mean ~ SmoothedtracksBootCInoNA[[i]]$frame,
    type = "l",
    ylab = names(SmoothedtracksBootCInoNA)[[i]],
    xlab = "Time (frame)",
    ylim = c(round(min(
      c(
        SmoothedtracksBootCInoNA[[i]]$`2.5%`,
        SmoothedtracksBootCInoNA[[i]]$`97.5%`
      ) ,
      na.rm = T
    ), digits = 5),
    round(max(
      c(
        SmoothedtracksBootCInoNA[[i]]$`2.5%`,
        SmoothedtracksBootCInoNA[[i]]$`97.5%`
      ),
      na.rm = T
    ), digits = 5))
  )
  polygon(
    x = c(
      SmoothedtracksBootCInoNA[[i]]$frame,
      rev(SmoothedtracksBootCInoNA[[i]]$frame)
    ),
    y = c(
      SmoothedtracksBootCInoNA[[i]]$`2.5%`,
      rev(SmoothedtracksBootCInoNA[[i]]$`97.5%`)
    ),
    col = rgb(1, 0, 0, 0.1),
    border = NA,
    density = NA
  )
}