Repulsive force {phonR}

Repulsive force calculations and plots for vowel systems.

Description

For each point, calculates the sum of inverse squared distances to all points that are not of the same type.

Usage

    repulsiveForce(x, y, type, xform=log, exclude.inf=TRUE)
    repulsiveForceHeatmap(x, y, type=NULL, xform=log, 
                          exclude.inf=TRUE, resolution=10,
                          colormap=NULL, fast=FALSE, ...)
    repulsiveForceHeatmapLegend(x, y, labels=c("low", "high"),
                                pos=c(1, 3), colormap=NULL,
                                smoothness=50, lend=2, lwd=12, ...)

Arguments

x, y

Numeric vector of x and y values (e.g., F2 and F1 frequencies), or in the case of repulsiveForceHeatmapLegend, length-2 vectors specifying the endpoints of the legend colorbar.

type

Attribute of the (x, y) points used to interpolate values for intermediate points. In typical linguistic usage of this function, type would be the vowel identities of the F2 and F1 values passed to x and y (respectively).

xform

A function to apply to the calculated force values before applying the colormap. Default is to use the log function.

exclude.inf

Logical; should infinite force values be excluded? If true, force for points with identical x and y values but different values of type will be calculated as if the distance between those points was half as long as the smallest non-zero distance in the data (instead of 0).

resolution

Number of points to interpolate between each axis unit. Higher resolution yields smoother heatmaps at the cost of increased computational time. NOTE: in typical linguistic usage, an appropriate resolution value will depend on the type of units used to plot the formant data (e.g., you will need higher resolution for vowels plotted on the Bark scale to get an equivalently smooth heatmap to one plotted with lower resolution on a Hertz scale.)

colormap

Colormap to use when drawing the heatmap and legend (see color.scale. Note that although the heatmap may use semi-transparent colors, this transparency does not usually translate well to the force.legend colorbar, due to the way that color.scale.lines works. In short: the legend colorbar is made of lots of little segments that don't quite touch when plotted, leaving thin gaps in the colorbar where the background shows through. In phonR this has been avoided by adding a square cap to the line ends of each segment in the colorbar, causing neighboring segments to overlap. This overlapping is not noticeable when the force.colormap uses fully opaque colors, but usually yields a colorbar that looks opaque even when the force.colormap colors are semi-transparent. For better results, generate the force.colmap with pale, opaque colors instead of intense colors that are semi-transparent.

fast

Logical; should an interpolation algorithm be used instead of the normal repulsive force function when assigning force values to grid points? If FALSE, the function assigns each grid point a vowel identity based on its nearest neighbor and assigns a color value based on the repulsive force that would occur for a vowel at that location (if it had existed in the dataset). If TRUE, the function performs a Delaunay triangulation of the vowel space using the vowel points in the dataset, and then uses Juan Pineda's triangle filling algorithm to interpolate force values for grid points inside the triangles. This method is fast even at high resolutions, but may appear discontinuous at the edges of adjacent triangles.

labels

Vector of strings (length 2); the labels to write at each end of the force legend color bar. Ignored if heatmap.legend is FALSE.

pos

Vector of integers (length 2); position codes for the colorbar labels. See the pos argument of text for explanation.

smoothness

Number of color steps to use when drawing the legend colorbar. Limited by the number of colors specified in colormap; values larger than length(colormap) will be ignored and use length(colormap) instead.

lend

End-cap style for the individual segments of the colorbar. See par.

lwd

Width of the colorbar. See par.

...

Additional arguments passed to image by repulsiveForceHeatmap, or passed to color.scale.lines by repulsiveForceHeatmapLegend.

Details

Given endpoints x and y, forceHeatmapLegend draws a colorbar legend with smoothness number of steps using the provided colormap (or defaults to grayscale if colormap is NULL.

Value

repulsiveForce returns the sum of the repulsive forces calculated at each point (x,y).

Author(s)

McCloy, Daniel [e-mail]

References

Liljencrants, J., & Lindblom, B. 1972 “Numerical simulation of vowel quality systems: The role of perceptual contrast”. Language, 48(4), 839-862. http://www.jstor.org/stable/411991

McCloy, D. R., Wright, R. A., & Souza, P. E. 2014 “Talker versus dialect effects on speech intelligibility: A symmetrical study”. Language and Speech. http://dx.doi.org/10.1177/0023830914559234

Pineda, J. 1988 “A parallel algorithm for polygon rasterization”. ACM SIGGRAPH Computer Graphics, 22(4), 17-20. http://dx.doi.org/10.1145/378456.378457

See Also

plotVowels

Examples

    require(plotrix)
    data(indoVowels)
    force <- with(indo[indo$subj==indo$subj[1],], 
                  repulsiveForce(f2, f1, vowel))
    colmap <- color.scale(x=0:100, cs1=c(0, 180), cs2=100, 
                          cs3=c(25, 100), color.spec='hcl')
    with(indo[indo$subj==indo$subj[1],],
        repulsiveForceHeatmap(f2, f1, type=vowel, resolution=10,
                              colormap=colmap, add=FALSE))
    xl <- rep(max(range(indo$f2)), 2)
    yl <- range(indo$f1) + c(abs(diff(range(indo$f1)) / 2), 0)
    repulsiveForceHeatmapLegend(xl, yl, colormap=colmap, useRaster=TRUE)