gazetools: Gazetools

# This file was generated by Rcpp::compileAttributes
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' Classify Raw Gaze Data {C++}
#'
#' Velocity based classification of raw gaze samples to discrete events such as saccades and fixations.
#' With this classifier, fixations are what ever samples are left after identifying all other events.
#' In other words, there is no concept of minium fixation duration.
#'
#' @param v a vector of the instantaneous velocities for a set raw gaze samples
#' @param e a vector indicating blinks or otherwise bad data in the velocity vector
#' @param samplerate the number of samples taken in one second of time
#' @param vt saccade onset velocity threshold
#' @param sigma when greater than 0, the saccade onset velocity threshold is iteratively adjusted such that
#'        the saccade onset threshold is \emph{sigma} standard deviations higher than the mean of all velocity samples
#'        lower than the saccade onset threshold, when glissade detection is enabled \emph{sigma}/2 is used as the
#'        saccade offset velocity threshold
#' @param minblink the minimum duration in seconds required for noise to be considered a blink
#' @param minsac the minimum saccade duration in seconds
#' @param glswin the duration (in seconds) of the window post-saccade to look for glissades in, setting to 0 disables glissade detection
#' @param alpha the weight (from 0 to 1) of the saccade onset threshold component of the saccade offset threshold,
#'        \emph{1-alpha} is used as the weight for the noise threshold component the saccade offset threshold
#'
#' @export
classify <- function(v, e, samplerate, vt = 100, sigma = 6, minblink = .08, minsac = .02, glswin = .04, alpha = .7) {
    .Call('gazetools_classify', PACKAGE = 'gazetools', v, e, samplerate, vt, sigma, minblink, minsac, glswin, alpha)
}

#' Distance to Point {C++}
#'
#' Takes an x and y screen coordinate and returns the physical distance
#' from the observer to that point on the screen.
#'
#' @param x the horizontal coordinate of a point on a screen (pixels)
#' @param y the vertical coordinate of a point on a screen (pixels)
#' @param rx the horizontal resolution of the screen (pixels)
#' @param ry the vertical resolution of the screen (pixels)
#' @param sw the physical screen width (mm)
#' @param sh the physical screen height (mm)
#' @param ez the perpendicular distance from the viewer to the screen (mm)
#' @param ex the horizontal offset of the viewer from screen center (mm)
#' @param ey the vertical offset of the viewer from screen center (mm)
#'
#' @export
#'
#' @examples
#' distance_2_point(840, 525, 1680, 1050, 473.76, 296.1, 750)
#'
distance_2_point <- function(x, y, rx, ry, sw, sh, ez, ex = as.numeric( c(0.0)), ey = as.numeric( c(0.0))) {
    .Call('gazetools_distance_2_point', PACKAGE = 'gazetools', x, y, rx, ry, sw, sh, ez, ex, ey)
}

#' String-based (continuous) unique ID runs {C++}
#'
#' For a vector strings, assigns each continuous run of particular string a unique ID.
#'
#' @param x a vector of class \code{"character"}
#'
#' @return a vector of \code{"numeric"}
#'
#' @examples
#' ruidvec(c("One","One","Two","Three","Three","Two","Three","Three","One"))
#'
#' @export
ruidvec <- function(x, start = 0L) {
    .Call('gazetools_ruidvec', PACKAGE = 'gazetools', x, start)
}

#' Sigma Threshold {C++}
#'
#' Iteratively converges on a threshold for which the mean of the values below the threshold
#' is \emph{sigma} standard deviations away from the threshold
#'
#' @param x a vector of values that a sigma threshold needs to be determined for
#' @param e a vector of class \code{"logical"} indicating samples that should be excluded from any calculations
#' @param threshold the starting threshold for the iterative algorithm
#' @param sigma the number of standard deviations of separation between the threshold and the mean of the values below the threhold
#'
#' @examples
#' d <- with(highspeed, pva(x,y,1250,1024,768,.38,.30,.67))
#' sigthresh(d$v,d$blinks,80,5)
#'
#' @export
#'
sigthresh <- function(x, e, threshold, sigma) {
    .Call('gazetools_sigthresh', PACKAGE = 'gazetools', x, e, threshold, sigma)
}

#' Subtended Angle {C++}
#'
#' Takes two screen coordinates and returns the angle (in degrees)
#' subtended by those two points.
#'
#' @param x1 the horizontal coordinate of the first point on a screen (pixels)
#' @param y1 the vertical coordinate of the first point on a screen (pixels)
#' @param x2 the horizontal coordinate of the second point on a screen (pixels)
#' @param y2 the vertical coordinate of the second point on a screen (pixels)
#' @param rx the horizontal resolution of the screen (pixels)
#' @param ry the vertical resolution of the screen (pixels)
#' @param sw the physical screen width (mm)
#' @param sh the physical screen height (mm)
#' @param ez the perpendicular distance from the viewer to the screen (mm)
#' @param ex the horizontal offset of the viewer from screen center (mm)
#' @param ey the vertical offset of the viewer from screen center (mm)
#'
#' @return degrees of visual angle
#'
#' @export
#'
#' @examples
#' subtended_angle(835, 525, 845, 525, 1680, 1050, 473.76, 296.1, 750)
#'
subtended_angle <- function(x1, y1, x2, y2, rx, ry, sw, sh, ez, ex = as.numeric( c(0.0)), ey = as.numeric( c(0.0))) {
    .Call('gazetools_subtended_angle', PACKAGE = 'gazetools', x1, y1, x2, y2, rx, ry, sw, sh, ez, ex, ey)
}

#' Logical-based (non-continuous) unique ID runs {C++}
#'
#' For a vector of logicals, assigns each continuous run of TRUE values a unique ID.
#'
#' @param x a vector of class \code{"logical"}
#'
#' @return a vector of \code{"numeric"}
#'
#' @examples
#' uidvec(c(FALSE,FALSE,TRUE,TRUE,TRUE,FALSE,TRUE,FALSE,TRUE,TRUE,FALSE,TRUE))
#'
#' @export
uidvec <- function(x, start = 0L) {
    .Call('gazetools_uidvec', PACKAGE = 'gazetools', x, start)
}