plotOutliers: Plot potential outliers for specific frames

In axzinker/blenderFace: Collection of functions to process blender measured facial movement data

Plot potential outliers for specific frames

Description

Because in this case the SD is inappropriate for the purpose of outlier detection (e.g., if there is rarely movement, even very small movements / noise are detected as outliers), a theoretical approach is used: The fastest human movement is the eyeblink, which takes about 300 - 400 ms (Robert A.Moses (Ed.), (1981). Adler's Physiology of the eye clinical application. Mosby, Chapter 1, p. 1-15). The cornea of the eye has a diameter of 11.5 mm. The speed of the eye-blink movement can be therefore (11.5mm / 150 ms) = 0.0766 mm/ms. Based on the framerate (fps), the maximal plausible movement from one frame to the next is computed, and taken as a cut off value. For example, a video clip recorded at 30fps contains an image taken every 33ms. Therefore the maximal distance from one frame to the next is 0.0766 mm/ms * 33 ms = 2.53 mm. Every larger distance is marked as an outlier. The function computes the 2D distance (Pytagoras) of a marker coordinates pair (x and y) of frame t and frame t + 1. Per default, any distance larger than 2.53 mm is marked as a potential outlier. The function plots for each potential outlier the movement of the centered marker coordinates (x and y), the distance from t to t + 1, the upper cut off value, and marks the frame with the outlier. This function needs data scaled to mm because the cut off value is scaled in mm. Therefore, use the function bu2mm beforehand, otherwise the outlier detection is not meaningful.

Usage

plotOutliers(
  data,
  colNameFrames,
  colNameData,
  colNameCond = "",
  maxM = 2.53,
  title = colNameData,
  savePlots = FALSE,
  verbose = FALSE
)

Arguments

data	Data-frame containing the variables labeled in colNameFrames, colNameData, and colNameCond.
colNameFrames	Character vector containing the column name of the frames column of the data data-frame
colNameData	Character vector containing the column names for x and y values of the data which should be analyzed for outliers (e.g., BL2_x, BL2_y)
colNameCond	Character vector containing the column name of the stimuli presented at each frame. Default is no colNameCond.
maxM	Numeric vector of length 1. Cut off value (maximal allwed movement) in mm. Movments larger than maxM are marked as outliers. Optional value, default is 2.2 mm.
title	Default are the column names.
savePlots	Set to TRUE if outlier plots should be saved as a pdf. As a filename the title is used. Default is FALSE.
verbose	Logical value. If verbose is TRUE, the plots for each outlier will be presented separately.

Value

See vignette for example plots.

Author(s)

Axel Zinkernagel [e-mail], Rainer Alexandrowicz [e-mail]

Examples

## Not run: 
# fix me: meaningful example

## End(Not run)   

axzinker/blenderFace documentation built on Feb. 27, 2024, 10:25 a.m.