Holds a still subject still. The output stays where it is until the
tracked point has moved more than threshold away from it, so the small
wandering of tracking noise on a stationary point is removed entirely
rather than merely made smaller.
Usage
filter_deadband(data, threshold, mode = c("hold", "drag"), max_gap = Inf)Arguments
- data
A data frame of numeric coordinate columns — typically supplied by
dplyr::pick()insidedplyr::mutate(). To filter a whole aniframe, usefilter_across().- threshold
A single non-negative number, in the units of the coordinates: how far the point has to move from the anchor before the output follows.
0returnsdataunchanged.- mode
How the output follows once the threshold is crossed:
"hold"(default) jumps to the point,"drag"moves just far enough to bring the point back to the edge of the dead zone. See Details.- max_gap
A whole number of rows, or
Inf(default): the longest run of incomplete rows across which the anchor is kept. After a longer gap, the next complete row starts afresh.
Details
Tracking noise on a point that is not moving adds a little to its path
every frame, so distance travelled is overestimated — the more so the
longer the subject is still and the higher the sampling rate — and speed
never reaches zero. A smoother scales that noise down but does not remove
it. A deadband does: movement smaller than threshold is ignored.
The output keeps an anchor, starting at the first complete row. For
each row, the distance from the anchor to the row's point is compared
with threshold. While it is at most threshold, the output is the
anchor. Once it is more, the anchor moves, in one of two ways:
"hold"(default): the anchor jumps to the point. This is the "direct" Minimal Distance Moved of Noldus EthoVision XT, and the behaviour OptiTrack Motive describes for its rigid-body Deadband Filter, so results can be compared with theirs."drag": the anchor is pulled towards the point until it is exactlythresholdaway, as if on a lead of that length. This is the play (backlash) operator of hysteresis theory, in its vector form (Krejčí, 1991). The output never jumps and trails the point by at mostthreshold, but sustained movement is shortened bythresholdat each start and stop.
With several coordinate columns the distance is Euclidean, so the dead zone is a circle or sphere: a move registers by its length, whatever its direction. The axes should therefore share a unit, and be Cartesian.
Choosing a threshold
threshold is in the units of the coordinates. It should exceed the
noise on a still point — a few times its standard deviation, measured on
a stretch where the subject is known to be still — and stay below the
smallest movement that matters. Smoothing first, for instance with
filter_lowpass(), lowers the noise and so lets the threshold be
smaller.
What it does to derivatives
A deadband is for distance travelled, immobility and bout detection, not
for kinematics. In "hold" mode the speed is zero while the anchor holds
and spikes when it jumps; in "drag" mode it is zero, then continuous.
Neither is the subject's real speed.
The filter is recursive and causal: each output depends on the rows before it, so the result depends on where the series starts, and running it backwards in time gives a different answer.
Missing values
A row with any coordinate missing is not a point: it is left as it is,
and does not move the anchor. The next complete row is compared with the
anchor as it stood before the gap, so a subject that is in the same place
after a dropout stays exactly where it was. When a run of such rows is
longer than max_gap, the anchor is reset instead: the next complete row
is taken as it is, as at the start of the series.
Input shape
This is a column-level function: it takes a data frame of coordinate
columns and returns one of the same shape. The aniframe tier is
filter_across(), which applies it within the frame's existing grouping
so each individual / track / keypoint is filtered as its own trajectory.
filter_across(af, "deadband", threshold = 2) # a whole aniframe
data |> mutate(filter_deadband(pick(all_of(c("x", "y"))), threshold = 2)) # the columnsThe distance depends on all coordinates jointly, so this cannot be used
with dplyr::across(), which passes one column at a time. For a single
signal, pass a one-column frame.
References
OptiTrack. Properties Pane: Rigid Body — Deadband Filter. Motive documentation. https://docs.optitrack.com/motive-ui-panes/properties-pane/properties-pane-rigid-body
Noldus Information Technology. Smooth the tracks: Minimal Distance Moved methods. EthoVision XT 19 reference manual. https://noldus.com/shared/resources/book/noldus-product-documentation/chapter/ethovision-xt/page/ethovision-xt-19-smooth-the-tracks-minimum-distance-moved-methods
Hen, I., Sakov, A., Kafkafi, N., Golani, I., & Benjamini, Y. (2004). The dynamics of spatial behavior: how can robust smoothing techniques help? Journal of Neuroscience Methods, 133, 161–172. doi:10.1016/j.jneumeth.2003.10.013
Krasnosel'skiǐ, M. A., & Pokrovskiǐ, A. V. (1989). Systems with Hysteresis. Springer. doi:10.1007/978-3-642-61302-9
Krejčí, P. (1991). Vector hysteresis models. European Journal of Applied Mathematics, 2, 281–292. doi:10.1017/S0956792500000541
See also
filter_lowpass() and filter_one_euro(), which reduce noise
rather than remove it, and work well before a deadband.
Examples
# A point that sits still with a little noise for 100 frames, then moves
# 10 units in 10 frames
set.seed(1)
coords <- data.frame(
x = c(rep(0, 100), 1:10) + rnorm(110, sd = 0.05),
y = rnorm(110, sd = 0.05)
)
# The still stretch comes out exactly still
held <- filter_deadband(coords, threshold = 0.2)
held[95:105, ]
#> x y
#> 95 -0.03716366 -0.016700042
#> 96 -0.03716366 -0.016700042
#> 97 -0.03716366 -0.016700042
#> 98 -0.03716366 -0.016700042
#> 99 -0.03716366 -0.016700042
#> 100 -0.03716366 -0.016700042
#> 101 0.96898167 -0.008218792
#> 102 2.00210579 0.021034732
#> 103 2.95445392 -0.020012337
#> 104 4.00790144 -0.068510394
#> 105 4.96727077 0.049391913
# So the noise no longer adds to the path length
path_length <- function(d) sum(sqrt(diff(d$x)^2 + diff(d$y)^2))
path_length(coords)
#> [1] 18.54119
path_length(held)
#> [1] 10.55844
# "drag" follows without jumping, at most `threshold` behind
filter_deadband(coords, threshold = 0.2, mode = "drag")[95:105, ]
#> x y
#> 95 -0.02332386 -0.02401083
#> 96 -0.02332386 -0.02401083
#> 97 -0.02332386 -0.02401083
#> 98 -0.02332386 -0.02401083
#> 99 -0.02332386 -0.02401083
#> 100 -0.02332386 -0.02401083
#> 101 0.76900699 -0.01140129
#> 102 1.80217495 0.01577566
#> 103 2.75455031 -0.01380364
#> 104 3.80809168 -0.05978902
#> 105 4.76815205 0.03063729
# The aniframe tier
af <- anicore::example_anipoint(n_obs = 60, n_individuals = 1, n_keypoints = 1)
filter_across(af, "deadband", threshold = 0.5)
#> # Individuals: 1
#> # Keypoints: centroid
#> # Sessions: 1
#> # Trials: 1
#> individual keypoint session trial time x y confidence
#> <int> <fct> <int> <int> <int> <dbl> <dbl> <dbl>
#> 1 1 centroid 1 1 1 -1.73 -2.26 0.627
#> 2 1 centroid 1 1 2 0.00213 -1.41 0.790
#> 3 1 centroid 1 1 3 -0.630 0.916 0.836
#> 4 1 centroid 1 1 4 -0.341 -0.191 0.818
#> 5 1 centroid 1 1 5 -1.16 0.803 0.876
#> 6 1 centroid 1 1 6 1.80 1.89 0.831
#> 7 1 centroid 1 1 7 -0.331 1.47 0.486
#> 8 1 centroid 1 1 8 -1.61 0.677 0.619
#> 9 1 centroid 1 1 9 0.197 0.380 0.469
#> 10 1 centroid 1 1 10 0.263 -0.193 0.787
#> # ℹ 50 more rows