Skip to contents

Derive trial-level track positions in polar coordinates.

Source: R/circular_trials.R
get_tracked_object_pos.Rd

Using the trial limits returned by [get_trial_limits()], this helper extracts the corresponding rows from a track data frame or `Tracks`, centres and scales the coordinates, and computes angles in both absolute and reference-relative frames. The function optionally controls how inner/outer radius crossings are selected.

Usage

get_tracked_object_pos(
  trial_limits,
  track,
  circ0 = 0.1,
  circ1 = 0.2,
  radius_criterion = c("first_past", "closest"),
  .report_oob = TRUE
)

Arguments

trial_limits

Data frame produced by [get_trial_limits()].

track

Data frame or `Tracks` of Cartesian coordinates for the entire video.

circ0

Inner radius threshold (default `0.1`).

circ1

Outer radius threshold (default `0.2`).

radius_criterion

Strategy for choosing the radius landmarks. `"first_past"` selects the first point beyond each threshold, while `"closest"` chooses the closest sample to the specified radius. With `"first_past"`, a radius no point reaches gives that landmark `NA`, with a warning.

.report_oob

Internal. When `TRUE` (default), emit a single message summarising any track points that fall outside the unit circle. Callers that loop over many files (e.g. [get_all_object_pos()]) set this to `FALSE` and read the tally from `meta$oob_points`/`meta$oob_trials` to report once.

Value

A `Tracks` containing all valid trial observations. The corresponding trial limits (including `valid_track` flags) are stored in `meta$trial_limits`.

Examples

untar(system.file("extdata", "tracks.tar.gz", package = "radiatR"),
      exdir = tempdir())
track_dir <- file.path(tempdir(), "tracks")
file_tbl <- import_tracks(track_dir)[1, ]
read_xy <- function(f) {
  d <- utils::read.delim(file.path(track_dir, f), header = FALSE)[1:3]
  stats::setNames(d, c("frame", "x", "y"))
}
landmarks <- read_xy(file_tbl$landmark)  # origin, then reference, per trial
track <- read_xy(file_tbl$track)
limits <- get_trial_limits(landmarks, track, file_tbl, vid_num = 1)
get_tracked_object_pos(limits, track)
#> Tracks: 1 trajectories, 299 observations
#> Columns: id='trial_id', time='frame', angle='rel_theta' (radians), x='trans_x', y='trans_y', rel_x='rel_x', rel_y='rel_y'
#> Transform steps: unit_circle_mapping 
#> # A tibble: 6 × 10
#>   trial_id frame     x     y trans_x trans_y rel_theta video order vid_ord
#>   <chr>    <int> <dbl> <dbl>   <dbl>   <dbl>     <dbl> <chr> <chr> <chr>  
#> 1 10_10_1      1  470.  379.  0.0371 -0.0149      2.71 10_10 1     10_10_1
#> 2 10_10_1      2  478.  387.  0.0619 -0.0371      2.55 10_10 1     10_10_1
#> 3 10_10_1      3  479.  389.  0.0669 -0.0446      2.50 10_10 1     10_10_1
#> 4 10_10_1      4  482.  401.  0.0768 -0.0818      2.27 10_10 1     10_10_1
#> 5 10_10_1      5  485.  406.  0.0842 -0.0991      2.22 10_10 1     10_10_1
#> 6 10_10_1      6  484.  417.  0.0818 -0.134       2.06 10_10 1     10_10_1