Count entries into a goal zone for trajectories in a circular field

For each trial, counts the number of times the trajectory enters a circular zone of radius `crossing_radius` centred on the goal location. Applicable to any circular-field analysis with a defined goal (e.g. the hidden platform in a water maze, a reward zone in an open-field).

Usage

count_goal_entries(
  x,
  target_angle,
  target_radius = 1,
  crossing_radius = 0.15,
  coords = c("absolute", "relative")
)

Arguments

x

A [`Tracks`] object with x/y (or rel_x/rel_y) columns registered.

target_angle

Numeric. Radians. Direction of the goal from the origin.

target_radius

Numeric. Distance of the goal from the origin. Default `1` (wall). Together with `target_angle` gives the goal position: `gx = target_radius * cos(target_angle)`, `gy = target_radius * sin(target_angle)`.

crossing_radius

Numeric. Radius of the goal zone in unit-circle coordinates. Default `0.15` (15% of the radius; roughly a 10 cm platform in a 60 cm pool).

coords

Character. `"absolute"` (default) or `"relative"`. See [zone_dwell()].

Value

A `data.frame` with one row per trial: `id` (character) and `n_entries` (integer).

Details

An "entry" is a `FALSE -> TRUE` transition in the `distance < crossing_radius` sequence (ordered by time). A trajectory that starts inside the zone on the first frame counts as one entry.

See also

[zone_dwell()]

Examples

# Treat 45 degrees (NE) at the wall as the goal, as for a water maze probe
data(cpunctatus)
entries <- count_goal_entries(cpunctatus, target_angle = pi / 4,
                              crossing_radius = 0.15)
# n_entries > 1 indicates memory of the platform location
head(entries)
#>              id n_entries
#> 10_10_1 10_10_1         0
#> 10_11_1 10_11_1         0
#> 10_12_1 10_12_1         0
#> 10_13_1 10_13_1         0
#> 10_14_1 10_14_1         0
#> 10_15_1 10_15_1         0