Given a data frames containing tracking information for a given tracklet, this function scale tracklet path, convert it to a desired time unit and returns a vector containing the value of speed along this tracklet.
Usage
speed(
df,
scale = 1,
timeCol = "frame",
frameR = 1,
timeU = c("f", "s", "m", "h", "d")
)Arguments
- df
A data frame containing x and y coordinates in columns named "x.pos", "y.pos" for a given tracklet, as well as a column containing time information, whatever the unit, over the trajectory.
- scale
A ratio corresponding to the scaling factor to be applied to the trajectory coordinates (e.g., size in cm / size in pixels, default = 1).
- timeCol
A character string corresponding to the name of the column containing Time information (default = 'frame').
- frameR
A numeric value indicating the frame rate of the video, used to convert the speed value according to desired time unit, see also timeU argument (default = 1).
- timeU
A character string indicating the time unit in which the speed values should be converted, "f"=frame, "s"=second, "m"=minute, "h"=hour, "d"=day (default = "f").
Examples
set.seed(2023)
# generate a dummy tracklet
## start to specify some parameters to generate the tracklet
TrackL <-
100 # the length of the tracklet or a sequence to randomly sample tracklet's length
TrackDatTemp <-
trajr::TrajGenerate(sample(TrackL, 1), random = TRUE, fps = 1)
TrackDat <-
data.frame(
x.pos = TrackDatTemp[["x"]] - min(TrackDatTemp[["x"]]),
y.pos = TrackDatTemp[["y"]] - min(TrackDatTemp[["y"]]),
frame = TrackDatTemp[["time"]]
)
# compute the speed of the particle along its trajectory,
# expressing the speed as pixels/frame
TrackDat[["speedFrame"]] <-
MoveR::speed(TrackDat, scale = 1, timeCol = "frame")
# to compute the speed according to another time unit, a new column containing the new timeline could be used
# here we consider that the frame rate is 25 frame per second
TrackDat[["second"]] <- TrackDat[["frame"]] / 25
# then compute the speed of the particle over its trajectory according to the new time unit
TrackDat[["speedSec"]] <-
MoveR::speed(TrackDat, scale = 1, timeCol = "second")
str(TrackDat)
#> 'data.frame': 81 obs. of 6 variables:
#> $ x.pos : num 0 2.07 2.35 2.45 1.91 ...
#> $ y.pos : num 47.3 46.2 44.3 42.2 40.2 ...
#> $ frame : num 0 1 2 3 4 5 6 7 8 9 ...
#> $ speedFrame: num NA 2.35 1.98 2.1 2.03 ...
#> $ second : num 0 0.04 0.08 0.12 0.16 0.2 0.24 0.28 0.32 0.36 ...
#> $ speedSec : num NA 58.7 49.4 52.4 50.7 ...
# alternatively, we can use the frameR and timeU arguments to specify the frame rate and the desired time unit within the function
TrackDat[["speedSec2"]] <-
MoveR::speed(TrackDat, scale = 1, timeCol = "frame", frameR = 25, timeU = "s")
str(TrackDat)
#> 'data.frame': 81 obs. of 7 variables:
#> $ x.pos : num 0 2.07 2.35 2.45 1.91 ...
#> $ y.pos : num 47.3 46.2 44.3 42.2 40.2 ...
#> $ frame : num 0 1 2 3 4 5 6 7 8 9 ...
#> $ speedFrame: num NA 2.35 1.98 2.1 2.03 ...
#> $ second : num 0 0.04 0.08 0.12 0.16 0.2 0.24 0.28 0.32 0.36 ...
#> $ speedSec : num NA 58.7 49.4 52.4 50.7 ...
#> $ speedSec2 : num NA 58.7 49.4 52.4 50.7 ...
# it is also possible to resample the tracklet before computing speed, here every 10 time unit (i.e., frame)
sampledFragDat <-
MoveR::resampTracklets(MoveR::trackletsClass(list(TrackDat)), timeCol = "frame", Tstep = 10)[[1]]
# and then compute the speed of the particle over its trajectory
sampledFragDat[["speedResampl"]] <-
MoveR::speed(sampledFragDat, scale = 1, timeCol = "frame")
str(sampledFragDat)
#> 'data.frame': 9 obs. of 8 variables:
#> $ x.pos : num 0 2.82 13.63 29.6 38.01 ...
#> $ y.pos : num 47.3 29.1 17.2 17.2 33.5 ...
#> $ frame : num 0 10 20 30 40 50 60 70 80
#> $ speedFrame : num NA 1.72 2.02 2.13 1.9 ...
#> $ second : num 0 0.4 0.8 1.2 1.6 2 2.4 2.8 3.2
#> $ speedSec : num NA 43.1 50.4 53.3 47.6 ...
#> $ speedSec2 : num NA 43.1 50.4 53.3 47.6 ...
#> $ speedResampl: num NA 1.84 1.61 1.6 1.83 ...