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

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.

Examples

Run this code

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)))

Run the code above in your browser using DataLab

Description

Usage

Arguments

Details

See Also

Examples