| Title: | Determine Event Boundaries in Event Segmentation Experiments |
|---|---|
| Description: | Contains functions that help to determine event boundaries in event segmentation experiments by bootstrapping a critical segmentation magnitude under the null hypothesis that all key presses were randomly distributed across the experiment. Segmentation magnitude is defined as the sum of Gaussians centered at the times of the segmentation key presses performed by the participants. Within a participant, the maximum of the overlaid Gaussians is used to prevent an excessive influence of a single participant on the overall outcome (e.g. if a participant is pressing the key multiple times in succession). Further functions are included, such as plotting the results. |
| Authors: | Frank Papenmeier [aut, cre], Konstantin Sering [ctb] |
| Maintainer: | Frank Papenmeier <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 1.2.4 |
| Built: | 2025-02-18 04:56:21 UTC |
| Source: | https://github.com/cran/segmag |
Bootstraps critical segmentation magnitude values for a segmag
object under the null hypothesis that all key presses were randomly
distributed (uniformly) across the experiment (time_min to time_max).
bootstrap_critical_cutoffs(segmag, n_bootstrap, critical_probs, segmag_substract = NULL, visualize = FALSE, save_as = NULL)bootstrap_critical_cutoffs(segmag, n_bootstrap, critical_probs, segmag_substract = NULL, visualize = FALSE, save_as = NULL)
segmag |
object of class |
n_bootstrap |
numeric, number of bootstrap iterations |
critical_probs |
numeric vector of probabilities, e.g. c(.95,.99) |
segmag_substract |
object of class |
visualize |
logical, visualize ordered maxima (and minima if segmag_substract is set) of bootstrapping iterations (Note: Enabling this option might require a lot of RAM with large data sets or large values of n_bootstrap) |
save_as |
character, filename where to save raw bootstrapping data and plot (optional) |
During each bootstrapping iteration, the key presses are randomly distributed (drawn from uniform distribution ranging from time_min to time_max). Then, segmentation magnitude is calculated with those random key press times (note that ids are retained, that is each participant "makes" the same amount of key presses as in the original experiment). The local maxima in segmentation magnitude resulting from the random key press times are ordered according to their size. The largest maximum is kept.
The function returns the critical_probs quantiles of the vector of those
largest maxima obtained across n_bootstap iterations
This function can also be used to bootstrap the critical maxima and minima cutoffs of a difference function of two segmag objects. To do so, segmag and segmag_substract must be defined. All values will be related to the difference of segmag - segmag_substract (Keypress times in segmag and segmag_substract are randomized independently).
critical segmentation magnitudes; If segmag_substract is NULL, then the return value is a numeric vector. Otherwise a list with critical maxima cutoffs and critical minima cutoffs is returned.
#see ?segmag for an example#see ?segmag for an example
Fast detection of local maxima and minima of a numeric vector. This function takes a numeric vector as input and returns a logical vector with the same length and TRUE values at local maxima/minima (depending on function). If multiple succeeding values at a local maximum/minimum are equal, then only the center (rounded up if necessary) of the maximum/minimum is marked with TRUE.
flag_maxima_positions(values) flag_minima_positions(values)flag_maxima_positions(values) flag_minima_positions(values)
values |
numeric vector of values |
logical vector with TRUE at the center of local maxima/minima
var <- c(1,2,3,3,2,1,4,5,6,7,5,4,3) ## Using the Maxima functions flag_maxima_positions(var) # values of maxima var[flag_maxima_positions(var)] # indices of maxima which(flag_maxima_positions(var)) ## Using the Minima functions flag_minima_positions(var) # values of maxima var[flag_minima_positions(var)] # indices of maxima which(flag_minima_positions(var))var <- c(1,2,3,3,2,1,4,5,6,7,5,4,3) ## Using the Maxima functions flag_maxima_positions(var) # values of maxima var[flag_maxima_positions(var)] # indices of maxima which(flag_maxima_positions(var)) ## Using the Minima functions flag_minima_positions(var) # values of maxima var[flag_minima_positions(var)] # indices of maxima which(flag_minima_positions(var))
Returns the times of event boundaries from a segmag object. Event boundaries
are defined as the center of local maxima in segmentation magnitude that are
higher than a critical cutoff value. The critical cutoff value should be
determined with the bootstrap_critical_cutoffs function.
get_eb_times(segmag, cutoff)get_eb_times(segmag, cutoff)
segmag |
object of class |
cutoff |
numeric value determining the critical cutoff in segmentation magnitude |
numeric vector with event boundary times
get_eb_times_segmag_diff, bootstrap_critical_cutoffs
#see ?segmag for an example#see ?segmag for an example
Specific function when calculating event boundaries for the difference of
two segmag objects (segmag - segmag_substract). Returns the times of event
boundaries that are defined as the center of local maxima (minima) in
segmentation magnitude that are higher (lower) than a critical cutoff max/min values.
The critical cutoff max/min values should be determined with the
bootstrap_critical_cutoffs function.
get_eb_times_segmag_diff(segmag, segmag_substract, cutoff_max = NULL, cutoff_min = NULL)get_eb_times_segmag_diff(segmag, segmag_substract, cutoff_max = NULL, cutoff_min = NULL)
segmag |
object of class |
segmag_substract |
object of class |
cutoff_max |
numeric value determining the critical cutoff for maxima in segmentation magnitude |
cutoff_min |
numeric value determining the critical cutoff for minima in segmentation magnitude |
numeric vector with event boundary times. If cutoff_max or cutoff_min is NULL than the respective event boundaries are omitted.
get_eb_times, bootstrap_critical_cutoffs
Draws a plot depicting the segmentation magnitude resulting from overlaid Gaussians for each key press time across participants. If segmag_substract is defined then the difference in segmentation magnitude of segmag - segmag_substract is drawn.
## S3 method for class 'segmag' plot(x, cutoffs = NULL, eb_times = NULL, segmag_substract = NULL, save_as_png = NULL, ...)## S3 method for class 'segmag' plot(x, cutoffs = NULL, eb_times = NULL, segmag_substract = NULL, save_as_png = NULL, ...)
x |
object of class |
cutoffs |
numeric vector of critical cutoffs that are drawn as horizontal
red lines. Use |
eb_times |
numeric vector of event boundary times to highlight in the plot |
segmag_substract |
object of class |
save_as_png |
string, optional name of file where to save plot (.png is added automatically) |
... |
paramters passed to generic plot function |
This function creates a segmag object from a vector of participant ids and a vector of times when the participants pressed the segmentation key on the keyboard. All functions in the segmag package work on this object (e.g., plotting results, determining event boundaries). The additional parameters define the size and offset of the Gaussian that is centered around each key press and the time window in the data set to consider (time_min, time_max, time_steps).
segmag(ids, time_keypresses, data = NULL, time_min = (min(min(time_keypresses), (min(time_keypresses) + gauss_offset)) - gauss_cutoff), time_max = (max(max(time_keypresses), (max(time_keypresses) + gauss_offset)) + gauss_cutoff), time_steps = 0.01, gauss_offset = 0, gauss_sd = 1, gauss_cutoff = 6 * gauss_sd)segmag(ids, time_keypresses, data = NULL, time_min = (min(min(time_keypresses), (min(time_keypresses) + gauss_offset)) - gauss_cutoff), time_max = (max(max(time_keypresses), (max(time_keypresses) + gauss_offset)) + gauss_cutoff), time_steps = 0.01, gauss_offset = 0, gauss_sd = 1, gauss_cutoff = 6 * gauss_sd)
ids |
factor assigning a participant id to each key press (same length as time_keypresses) |
time_keypresses |
numeric vector with the times when the segmentation key was pressed on the keyboard |
data |
optional data.frame where ids and time_keypresses are stored in |
time_min |
time window of key press times used in calculations |
time_max |
time window of key press times used in calculations |
time_steps |
interval length of time steps within time window |
gauss_offset |
offset the overlaid Gaussian relative to the key press times in order to account for manual reaction times (0: centered, negative values: assume that event boundary occurred before key press) |
gauss_sd |
sd of overlaid Gaussian |
gauss_cutoff |
speed up calculations by not considering values of the overlaid Gaussian that are more than gauss_cutoff units from the center of the Gaussian away (because they are very close to 0) |
First, segmentation magnitude for each participant across time is calculated by centering a Gaussian around each key press. If multiple Gaussians overlap across time then only the maximum values is used (not sum) to ensure an equal weight of each participant on the overall segmentation magnitude. Thereafter, the segmentation magnitudes of the participants are summed up to define the overall segmentation magnitude across time. The higher the segmentation magnitude at one point in time the more participants pressed a key around this time point. To account for the fact that participants have a certain temporal error in their key presses, Gaussians are used to expand the influence of a single key press into time. Furthermore, an offset to these Gaussians can be defined in order to account for manual reaction times and to get a better estimate of the "real" time point of an event boundary.
In order to achieve a decent calculation speed, a fixed time scale with interval length time_steps and starting from time_min is used. All key-press times are rounded to their closest interval. A warning is issued if this changes the raw key-press times.
segmag object (also contains a data.frame with segmentation magnitude across time as $data)
bootstrap_critical_cutoffs, get_eb_times, plot.segmag
# segmentation responses (key presses) of 6 participants watching a movie (30 seconds long) participant_ids <- factor(c(1,1,1,1,2,2,3,3,3,3,4,4,4,5,5,6,6,6)) time_keypresses <- c(7,12,18,25,12.1,24.9,6.9,10,25.2,29,7.2,12.05,17.5,7.05,25,6.9,16.1,25) # create segmag object segmag1 <- segmag(participant_ids, time_keypresses, time_min=0, time_max=30) ## Not run: # estimate the critical cutoff against an alpha level of 0.05 # Note: This is an estimate an will vary slightly against multiple calls of this function # (variation is the lower the higher n_bootstrap is set) critical_cutoff <- bootstrap_critical_cutoffs(segmag1, 5000, .95) ## End(Not run) # timestamps of significant event boundaries within the movie eb_times <- get_eb_times(segmag1, critical_cutoff) plot(segmag1, critical_cutoff, eb_times)# segmentation responses (key presses) of 6 participants watching a movie (30 seconds long) participant_ids <- factor(c(1,1,1,1,2,2,3,3,3,3,4,4,4,5,5,6,6,6)) time_keypresses <- c(7,12,18,25,12.1,24.9,6.9,10,25.2,29,7.2,12.05,17.5,7.05,25,6.9,16.1,25) # create segmag object segmag1 <- segmag(participant_ids, time_keypresses, time_min=0, time_max=30) ## Not run: # estimate the critical cutoff against an alpha level of 0.05 # Note: This is an estimate an will vary slightly against multiple calls of this function # (variation is the lower the higher n_bootstrap is set) critical_cutoff <- bootstrap_critical_cutoffs(segmag1, 5000, .95) ## End(Not run) # timestamps of significant event boundaries within the movie eb_times <- get_eb_times(segmag1, critical_cutoff) plot(segmag1, critical_cutoff, eb_times)