plotVowels: Plot vowel formant data and a variety of derivative measures.

In phonR: Tools for Phoneticians and Phonologists

Description

Generates high-quality plots of provided formant values using either the default onscreen device (X11, Quartz, or Win32) or direct-to-file using built-in R file output methods (PDF, SVG, JPG, PNG, TIFF, or BMP).

Usage

    plotVowels(f1, f2, vowel=NULL, group=NULL,
               plot.tokens=TRUE, pch.tokens=NULL,
               cex.tokens=NULL, alpha.tokens=NULL,
               plot.means=FALSE, pch.means=NULL,
               cex.means=NULL, alpha.means=NULL,
               hull.line=FALSE, hull.fill=FALSE,
               hull.args=NULL, poly.line=FALSE,
               poly.fill=FALSE, poly.args=NULL,
               poly.order=NA, ellipse.line=FALSE,
               ellipse.fill=FALSE, ellipse.conf=0.6827,
               ellipse.args=NULL, diph.arrows=FALSE,
               diph.args.tokens=NULL, diph.args.means=NULL,
               diph.label.first.only=TRUE,
               diph.mean.timept=1, diph.smooth=FALSE,
               heatmap=FALSE, heatmap.args=NULL,
               heatmap.legend=FALSE, heatmap.legend.args=NULL,
               var.col.by=NULL, var.sty.by=NULL,
               fill.opacity=0.3, label.las=NULL,
               legend.kwd=NULL, legend.args=NULL,
               pretty=FALSE, output='screen', ...)

Arguments

f1,f2	Vector or matrix of formant frequency values. To plot multiple timepoints for each vowel, f1 and f2 should be matrices with vowel tokens varying along the rows and timepoints varying across the columns.
vowel	Vector of vowel symbols/labels.
group	Vector or factor that determines the groups used in calculating vowel means, e.g., a factor indicating “gender”, “speaker”, “sociolinguistic register”, etc.
plot.tokens	Logical; should individual vowel tokens be plotted?
pch.tokens	Vector of strings or integers; the symbol(s) to use when plotting vowel tokens. Integers are interpreted as standard R pch values (see points).
cex.tokens	Numeric; size of individual vowel points relative to par("cex").
alpha.tokens	Numeric in range [0,1], indicating opacity of plotted vowel tokens.
plot.means	Logical; should individual vowel tokens be plotted?
pch.means	Vector of strings or integers; the symbol(s) to use when plotting vowel means. Integers are interpreted as standard R pch values (see points).
cex.means	Size of vowel means relative to par("cex").
alpha.means	Numeric in range [0,1], indicating opacity of plotted vowel means.
hull.line	Logical; should a line be drawn tracing the convex hull encompassing all tokens (separately for each level of group)?
hull.fill	Logical; should the convex hull(s) have a color fill?
hull.args,poly.args,ellipse.args	Named list of arguments to be passed to polygon. Useful for controlling line width, etc. See “Details” for notes about color handling.
poly.line	Logical; should a line be drawn tracing the polygon connecting the mean values for each vowel (separately for each level of group)?
poly.fill	Logical; should the polygon(s) connecting mean values for each vowel have a color fill?
poly.order	Vector or factor indicating the order in which the polygon vertices should be connected. Should match the levels of factor(vowel). If there are values of vowel not included in poly.order, they will not be connected to the polygon line.
ellipse.line	Logical; should vowel density ellipses be drawn with an outer line?
ellipse.fill	Logical; should vowel density ellipses be filled?
ellipse.conf	Numeric in range (0,1]; the size of the ellipse expressed as a confidence level of the estimate of the true mean (i.e., 0.95 gives a 95% confidence ellipse). The default value (0.6827) corresponds to plus-or-minus one sample standard deviation along the major and minor axes of the bivariate normal density contour.
diph.arrows	Logical; should the last timepoint of each vowel be marked with an arrowhead?
diph.args.tokens,diph.args.means	List of named arguments to be passed to points and/or arrows when plotting tokens or means (ignored if f1 and f2 are 1-dimensional). Default is to plot bare lines (type="l") when pch.tokens is NULL, to draw points and lines overplotted (type="o") when diph.arrows=FALSE, and to plot bare lines with the first timepoint of each diphthong plotted when diph.arrows=TRUE. When pretty=TRUE and diph.arrows=TRUE, additional default settings are length=0.1 and angle=20. For diph.args.means, lwd defaults to 2 * par("lwd") when pretty=TRUE. All of these defaults are overridden by values passed to diph.args.tokens or diph.args.means in the function call.
diph.label.first.only	Logical; if plotting diphthongs, should a symbol or label be drawn only at the first timepoint? Note that if plotting means, the label or symbol may not correspond to the first timepoint; it depends on the value of diph.mean.timept.
diph.mean.timept	A strictly positive integer indicating which timepoint of the diphthongs should be used to calculate means, ellipses, and polygons. For example, if the f1 and f2 arguments are N-by-5 matrices where the 3rd column of each represents the formant measurement at the vowel midpoint (with the other columns providing 2 onglide and 2 offglide measurements), you can plot the means, ellipses, and polygons based on the midpoint measures by specifying diph.mean.timept=3.
diph.smooth	Logical; should a smoothing spline be drawn instead of segments connecting individual timepoints? This feature is under development, unstable, unsupported, and to the extent that it is implemented, it is only implemented for tokens, not means.
heatmap	Logical; should a repulsive force heatmap be drawn?
heatmap.args	Named list of additional arguments passed to repulsiveForceHeatmap. The arguments x, y, and type are passed automatically by plotVowels; heatmap.args is probably most useful for controlling resolution, colormap, and the xform function.
heatmap.legend	Logical; should a legend be drawn showing the color scale used in the repulsive force heatmap?
heatmap.legend.args	Named list of additional arguments passed to repulsiveForceHeatmapLegend. Parameters likely to be user-specified here are x and y for specifying the endpoints of the colorbar, labels for label text at the two ends of the colorbar, and smoothness for the number of color steps to display (limited by the number of levels in the color scale used). See repulsiveForceHeatmapLegend for a more complete description of the available arguments.
var.col.by	Vector or factor indicating the dimension along which to vary color.
var.sty.by	Vector or factor indicating the dimension along which to vary linetype and plotting symbol.
fill.opacity	Number in the range [0, 1] indicating the opacity of color fills for ellipses, hulls, and polygons (if drawn). Does not affect force.heatmap colors, which are specified via force.colmap.
legend.kwd	Keyword indicating legend placement (see legend). If NULL (the default), no legend will be printed.
label.las	Controls the orientation of axis labels relative to the axis line (independently from the axis tick numbers). Possible values are integers 0-4 (see par), or NULL (to use the default value of par("las"), or a value passed to plotVowels as las if available).
legend.args	Named list of additional arguments to be passed to legend, for controlling things like inset, ncol, seg.len, etc.
pretty	Logical; a switch that sets various graphical parameters: mar, las, mgp, xpd, fg, and tcl, as well as arrow parameters like length and angle and plotVowels-specific parameters such as color.palette. It is permissible to set pretty=TRUE and also pass any of these parameters to plotVowels to override the pretty defaults.
output	Graphical device to plot to. Supported values are “screen”, “pdf”, “svg”, “jpg”, “tif”, “png”, “bmp”.
...	Other graphical parameters passed to methods; e.g., width, height, units, asp, res, xlim, xlab, main, etc. Two arguments of plot: ann and type, are always silently overridden by plotVowels.

Details

Notes on color handling. If no col or border arguments are passed to hull.args, poly.args, or ellipse.args, then color is handled as follows: if pretty=FALSE, colors default to the values in palette(), with opacity for fills set by fill.opacity. If pretty=TRUE, equally-spaced hues of HCL colors are used instead of palette(). If the values passed to var.col.by and vowel are identical, hull and polygon lines are drawn in black, and fills are drawn black with appropriate fill.opacity.

Author(s)

McCloy, Daniel [e-mail]

See Also

normVowels

Examples

data(indoVowels)
with(indo, plotVowels(f1, f2, vowel, group=gender, plot.means=TRUE,
                      pch.means=vowel, ellipse.line=TRUE, poly.line=TRUE,
                      poly.order=c('i','e','a','o','u'), var.col.by=vowel,
                      var.sty.by=gender, pretty=TRUE, alpha.tokens=0.3,
                      cex.means=2))
# simulate some diphthongs
f1delta <- sample(c(-10:-5, 5:15), nrow(indo), replace=TRUE)
f2delta <- sample(c(-15:-10, 20:30), nrow(indo), replace=TRUE)
f1coefs <- matrix(sample(c(2:5), nrow(indo) * 2, replace=TRUE), 
                  nrow=nrow(indo))
f2coefs <- matrix(sample(c(3:6), nrow(indo) * 2, replace=TRUE),
                  nrow=nrow(indo))
indo <- within(indo, {
    f1a <- f1  + f1delta * f1coefs[,1]
    f2a <- f2  + f2delta * f2coefs[,1]
    f1b <- f1a + f1delta * f1coefs[,2]
    f2b <- f2a + f2delta * f2coefs[,2]
    })
with(indo, plotVowels(cbind(f1, f1a, f1b), cbind(f2, f2a, f2b), vowel,
                      group=gender, plot.tokens=TRUE, pch.tokens=NA,
                      alpha.tokens=0.3, plot.means=TRUE, pch.means=vowel,
                      var.col.by=vowel, var.sty.by=gender, pretty=TRUE,
                      diph.arrows=TRUE, diph.args.tokens=list(lwd=0.8),
                      diph.args.means=list(lwd=2)))

Example output

There were 50 or more warnings (use warnings() to see the first 50)

phonR documentation built on May 2, 2019, 1:29 p.m.