FindLandmarks: Find Gestural Landmarks
In patrickreidy/ag501: Carstens AG501 Electromagnetic Articulograph

Description Usage Arguments Details Value

Find the gestural onset, target onset, target offset, and gestural offset within a speed time-series.

FindLandmarks(x, ...)

## S3 method for class 'data.frame'
FindLandmarks(x, channels = NULL, matches = NULL,
  from = -Inf, to = Inf, onsetNear = NULL, targetNear = NULL,
  theta = 0.2, alpha = 0.1, ...)

## S3 method for class 'list'
FindLandmarks(x, channels = NULL, matches = NULL,
  from = -Inf, to = Inf, onsetNear = NULL, targetNear = NULL,
  theta = 0.2, alpha = 0.1, ...)

`x`	A data.frame (or a list of data.frames) that contain(s) kinematic data (e.g., position, velocity, speed, or acceleration data). `x` must have one column named `Time` and at least one other column.
`...`	Placeholder for future methods.
`channels`	A character vector, each element of which should match exactly the name of some column in `x` other than `Time`. Default matches all columns of `x` other than `Time`.
`matches`	A pattern used to match columns in `x`. A non-null value for this argument will supercede a non-null value for the `channels` argument. Default matches all columns of `x` other than `Time`.
`from, to`	Atomic numerics. Local maxima will only be found within the `[from,to]` interval. Default values will include all available data in the channel.
`onsetNear, targetNear`	Atomic numerics.
`theta`	A proportion within the range `[0,1)`. Given consecutive local maximum `max` and local minimum `min`, the gestural landmark `mark` is the point in time between the local maximum and minimum such that: `value(mark) = value(min) + (theta * (value(max) - value(min)))`. Default is `0.2`, which is the "industry standard".
`alpha`	A proportion within the range `[0,1)`. Local maxima in a given channel will only be found if their value exceeds `100*alpha` percent of the data range in that channel.

Gestural landmarks may be found only within a time series that denotes the speed of a sensor (or of a derived quantity, such as lip aperture) in one or more dimensions. Within a speed time-series, a gesture is comprises three local minima (m1, m3, m5), with a local maximum (m2, m4) between each local minima: i.e., these local minima and maxima are ordered such that m1 < m2 < m3 < m4 < m5. The first half of the gesture, during which the constriction is formed, corresponds to the interval [m1, m3), where the speed values trace a concave downward trajectory. The second half of the gesture, during which the constriction is released, corresponds to the interval [m3, m5], where again the speed values trace a concave downward trajectory.

A gestural landmark corresponds to the point in time between two consecutive local extrema, where the speed time-series is equal to some proportion (theta) of the range between the two local extrema. For example, if theta = 0.2, then the gestural onset is the point in time where the speed is equal to 20 percent of the range between the speed at m1, and the speed at m2: speed(m1) + (0.2 * (speed(m2) - speed(m1))).

In order to find landmarks, the user must provide a fixed point in time that is near to the local minima of the onset of the gesture (i.e., via the onsetNear argument) or the target (i.e., via the targetNear argument).

A data table with the following variables:

Channel: the name of the channel in which the local maximum occurs.
Landmark: the name of the landmark: GestureOnset, TargetOnset, TargetOffset, GestureOffset.
Time: the time at which the local occurs.
Value: the amplitude value of the local minimum.