The aniframe-level entry point to the mask_na_*() family. Applies a
named criterion to the frame's declared position columns, within its
existing grouping — so a criterion is never
evaluated across a track boundary.
Usage
mask_na_across(
data,
method = c("range", "speed", "excursion", "hampel", "roi", "confidence"),
variables = NULL,
...,
on_deltas = FALSE
)Arguments
- data
An aniframe.
- method
Criterion to apply. One of
"range","speed","excursion","hampel","roi"or"confidence".- variables
Columns to mask, as a tidyselect expression. Defaults to the declared position columns.
- ...
Arguments passed to the underlying function.
For
"speed",thresholdadditionally accepts"pooled":"auto"estimates a threshold separately for each group, so every track is judged against its own noise;"pooled"estimates one threshold from all groups at once, which is steadier when tracks are short.- on_deltas
If
TRUE, difference each column, mask the differences, and re-integrate from the original starting value — rejecting implausible single-window displacements rather than implausible positions. See Masking on displacements below.Only
"range"accepts it. The others either already judge a sample against its neighbours, or are not about displacement at all, so differencing first would answer a different question than their name promises; they error rather than quietly compute it.
Details
Beyond looping over columns, it fills in what the frame already knows:
"speed" takes its time from the index column (anicore::get_index()),
and "confidence" takes its confidence from the column of that name.
Either can be passed explicitly to override. For "confidence", the
warning about rows with no score is given once for the whole frame,
not once per group; see mask_na_confidence() for missing.
Only "range" is univariate. The others decide per row using all the
selected columns at once, and blank every one of them on a flagged row.
Where a confidence column is present, it is blanked on rows that this
call masked — the cross-column effect that the vector-level functions
cannot perform, since confidence is not a coordinate.
Masking on displacements
on_deltas matters more here than it does for smoothing. Where the
coordinates are cumulative — trackball data, say, whose raw readings are
per-window displacements that were integrated with cumsum() — masking a
position blanks the sample you flagged but leaves the spurious jump
baked into every subsequent position. Masking the displacement removes
the bad step itself, and everything downstream shifts back into place.
A masked step counts as no movement, and is restored as NA at its own
sample alone; the NA is not propagated forward. So the reading is "this
step is not believable", not "the animal's position is unknown from here".
The first sample of each group is never masked: it is the starting point,
and there is no step into it to judge.
See also
mask_na_with() for the vector-level generic.
Examples
tracking_data <- anicore::example_anipoint()
# time comes from the aniframe's metadata
mask_na_across(tracking_data, "speed", threshold = "auto")
#> # Individuals: 1, 2, 3
#> # Keypoints: head, neck, shoulder_right, shoulder_left, abdomen, hip_right,
#> # hip_left, knee_right, knee_left, foot_right, foot_left
#> # Sessions: 1
#> # Trials: 1
#> individual keypoint session trial time x y confidence
#> <int> <fct> <int> <int> <int> <dbl> <dbl> <dbl>
#> 1 1 head 1 1 1 0.933 0.574 0.912
#> 2 1 head 1 1 2 0.303 1.34 0.685
#> 3 1 head 1 1 3 -1.96 -0.461 0.908
#> 4 1 head 1 1 4 0.354 -0.192 0.912
#> 5 1 head 1 1 5 0.450 -2.08 0.951
#> 6 1 head 1 1 6 0.660 -1.91 0.832
#> 7 1 head 1 1 7 -1.03 1.41 0.801
#> 8 1 head 1 1 8 -2.37 0.528 0.463
#> 9 1 head 1 1 9 -0.325 0.644 0.820
#> 10 1 head 1 1 10 -0.944 0.901 0.425
#> # ℹ 1,640 more rows
mask_na_across(tracking_data, "range", min_value = -2, max_value = 2)
#> # Individuals: 1, 2, 3
#> # Keypoints: head, neck, shoulder_right, shoulder_left, abdomen, hip_right,
#> # hip_left, knee_right, knee_left, foot_right, foot_left
#> # Sessions: 1
#> # Trials: 1
#> individual keypoint session trial time x y confidence
#> <int> <fct> <int> <int> <int> <dbl> <dbl> <dbl>
#> 1 1 head 1 1 1 0.933 0.574 0.912
#> 2 1 head 1 1 2 0.303 1.34 0.685
#> 3 1 head 1 1 3 -1.96 -0.461 0.908
#> 4 1 head 1 1 4 0.354 -0.192 0.912
#> 5 1 head 1 1 5 0.450 NA 0.951
#> 6 1 head 1 1 6 0.660 -1.91 0.832
#> 7 1 head 1 1 7 -1.03 1.41 0.801
#> 8 1 head 1 1 8 NA 0.528 0.463
#> 9 1 head 1 1 9 -0.325 0.644 0.820
#> 10 1 head 1 1 10 -0.944 0.901 0.425
#> # ℹ 1,640 more rows
# trackball positions are integrated displacements: reject the step,
# not the position it left behind
trackball_data <- anicore::as_anipoint(data.frame(
time = 1:8,
x = cumsum(c(0, 1, 1, 1, 50, 1, 1, 1)),
y = cumsum(c(0, 1, 1, 1, 1, 1, 1, 1))
))
mask_na_across(
trackball_data,
"range",
min_value = -10,
max_value = 10,
on_deltas = TRUE
)
#> # Keypoints: centroid
#> keypoint time x y
#> <fct> <int> <dbl> <dbl>
#> 1 centroid 1 0 0
#> 2 centroid 2 1 1
#> 3 centroid 3 2 2
#> 4 centroid 4 3 3
#> 5 centroid 5 NA 4
#> 6 centroid 6 4 5
#> 7 centroid 7 5 6
#> 8 centroid 8 6 7