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

Plot vowel formant frequencies {phonR} | R Documentation

## 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`.

### Author(s)

McCloy, Daniel drmccloy@uw.edu

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

[Package phonR version 1.0-7 Index]