Sample density maps at fixation locations over time

This function samples template density maps at source fixation locations across specified time points. It is useful for analyzing how fixation patterns relate to a reference density map over the course of a trial (e.g., "reinstatement across time" analysis).

Usage

sample_density_time(
  template_tab,
  source_tab,
  match_on,
  times = seq(0, 3000, by = 50),
  time_bins = NULL,
  template_var = "density",
  source_var = "fixgroup",
  permutations = 0,
  permute_on = NULL,
  aggregate_fun = mean,
  normalize = c("none", "max", "sum", "zscore")
)

Arguments

template_tab

A data frame or tibble containing template density maps (e.g., from an encoding phase).

source_tab

A data frame or tibble containing fixation groups (e.g., from a retrieval phase).

match_on

A character string specifying the column name used to match template density maps to source fixation groups.

times

A numeric vector of time points (in ms) at which to sample the density. Default is seq(0, 3000, by = 50).

time_bins

An optional numeric vector specifying bin boundaries for aggregating samples. For example, c(0, 1000, 2000, 3000) creates 3 bins: [0-1000), [1000-2000), [2000-3000). Every bin is half-open, including the last, so a time point equal to the final break (3000 here) is not assigned to any bin. Default is NULL (no binning).

template_var

A character string specifying the name of the density column in template_tab. Default is "density".

source_var

A character string specifying the name of the fixation group column in source_tab. Default is "fixgroup".

permutations

An integer specifying the number of permutation samples for computing a baseline. Default is 0 (no permutations).

permute_on

An optional character string specifying the column used to stratify permutations (e.g., "subject" to permute within subjects).

aggregate_fun

A function used to aggregate density values within time bins. Default is mean.

normalize

A character string specifying how to normalize each density map before sampling. One of "none" (default), "max", "sum", or "zscore". See sample_density for details. Using "zscore" is recommended when comparing across conditions or groups that may differ in fixation count or density bandwidth.

Value

A tibble containing:

• All columns from source_tab

• sampled: A list column with data frames containing z (density values) and time columns for each row

• If time_bins is provided: columns bin_1, bin_2, etc. with aggregated values for each bin

• If permutations > 0: perm_sampled (list column with mean permuted trajectory) and perm_bin_1, perm_bin_2, etc.

Details

The function matches each row in source_tab to a corresponding density map in template_tab based on the match_on column. For each matched pair, it samples the template density at the fixation coordinates interpolated at each time point in times.

This approach avoids the problem of having too few fixations to compute density maps within short time windows. Instead, a single density map is created from all fixations (e.g., during encoding), and the sampling is done over time (e.g., during retrieval).

If time_bins is provided, the sampled values are aggregated within each bin using aggregate_fun. The result includes columns named bin_1, bin_2, etc.

If permutations > 0, a baseline is computed by sampling from non-matching density maps. As in template_similarity, the candidates are the distinct templates matched by other source rows (within the permute_on stratum, if given); every copy of the true match is excluded, each other template counts once, and up to permutations of them are drawn without replacement. The result includes perm_sampled (mean permuted trajectory) and bin-specific permutation columns if binning is used.

Examples

set.seed(1)
# Encoding fixations for three images, and one recall per image that
# revisits the encoded locations with some noise.
centres <- list(c(150, 150), c(400, 300), c(650, 150))
fixations <- function(centre, jitter) {
  fixation_group(x = centre[1] + rnorm(6, 0, jitter),
                 y = centre[2] + rnorm(6, 0, jitter),
                 onset = seq(0, 1000, by = 200), duration = rep(200, 6))
}
encoding <- tibble::tibble(image = 1:3,
                           fixgroup = lapply(centres, fixations, jitter = 40))
recall <- tibble::tibble(image = 1:3,
                         fixgroup = lapply(centres, fixations, jitter = 60))
templates <- density_by(encoding, groups = "image", sigma = 60,
                        xbounds = c(0, 800), ybounds = c(0, 450),
                        outdim = c(80, 45))
res <- sample_density_time(templates, recall, match_on = "image",
                           times = seq(0, 1000, by = 100),
                           time_bins = c(0, 500, 1000), permutations = 2)
res[, c("image", "bin_1", "bin_2", "perm_bin_1", "perm_bin_2")]
#> # A tibble: 3 × 5
#>   image   bin_1   bin_2  perm_bin_1  perm_bin_2
#>   <int>   <dbl>   <dbl>       <dbl>       <dbl>
#> 1     1 0.00322 0.00260 0.000000352 0.000000236
#> 2     2 0.00148 0.00215 0.000000213 0.00000281 
#> 3     3 0.00126 0.00201 0.000000442 0.00000275