scatterplot {car} | R Documentation

## Scatterplots with Boxplots

### Description

Makes enhanced scatterplots, with boxplots in the margins, a nonparametric regression smooth, smoothed conditional spread, outlier identification, and a regression line; `sp` is an abbreviation for `scatterplot`.

### Usage

    scatterplot(x, ...)

    ## S3 method for class 'formula'
    scatterplot(formula, data, subset, xlab, ylab, legend.title, legend.coords,
    	labels, ...)

    ## Default S3 method:
    scatterplot(x, y,
        smoother=loessLine, smoother.args=list(), smooth, span,
        spread=!by.groups, reg.line=lm,
        boxplots=if (by.groups) "" else "xy",
        xlab=deparse(substitute(x)), ylab=deparse(substitute(y)), las=par("las"),
        lwd=1, lty=1,
        labels, id.method = "mahal",
        id.n = if(id.method[1]=="identify") length(x) else 0,
        id.cex = 1, id.col = palette()[1],
        log="", jitter=list(), xlim=NULL, ylim=NULL,
        cex=par("cex"), cex.axis=par("cex.axis"), cex.lab=par("cex.lab"),
        cex.main=par("cex.main"), cex.sub=par("cex.sub"),
        groups, by.groups=!missing(groups),
        legend.title=deparse(substitute(groups)), legend.coords, legend.columns,
        ellipse=FALSE, levels=c(.5, .95), robust=TRUE,
        col=if (n.groups == 1) palette()[3:1] else rep(palette(), length=n.groups),
        pch=1:n.groups,
        legend.plot=!missing(groups), reset.par=TRUE, grid=TRUE, ...)

    sp(x, ...)

### Arguments

`x` | vector of horizontal coordinates (or first argument of generic function).
`y` | vector of vertical coordinates.
`formula` | a “model” formula, of the form `y ~ x` or (to plot by groups) `y ~ x | z`, where `z` evaluates to a factor or other variable dividing the data into groups. If `x` is a factor, then parallel boxplots are produced using the `Boxplot` function.
`data` | data frame within which to evaluate the formula.
`subset` | expression defining a subset of observations.
`smoother` | a function to draw a nonparametric-regression smooth; the default is `loessLine`, which does loess smoothing. The function `gamLine` fits a generalized additive model and allows including a link and error function. See `ScatterplotSmoothers`. Setting this argument to something other than a function, e.g., `FALSE` suppresses the smoother.
`smoother.args` | a list of named values to be passed to the smoother function; the specified elements of the list depend upon the smoother (see `ScatterplotSmoothers`).
`smooth, span` | these arguments are included for backwards compatility: if `smooth=TRUE` then `smoother` is set to `loessLine`, and if `span` is specified, it is added to `smoother.args`.

`spread`

if TRUE, estimate the (square root) of the variance function. For `loessLine` and for `gamLine`, this is done by separately smoothing the squares of the postive and negative residuals from the mean fit, and then adding the square root of the fitted values to the mean fit. For `quantregLine`, fit the .25 and .75 quantiles with a quantile regression additive model. The default is TRUE if `by.groups=FALSE` and FALSE is `by.groups=TRUE`.

`reg.line` | function to draw a regression line on the plot or `FALSE` not to plot a regression line.
`boxplots` | if `"x"` a boxplot for `x` is drawn below the plot; if `"y"` a boxplot for `y` is drawn to the left of the plot; if `"xy"` both boxplots are drawn; set to `""` or `FALSE` to suppress both boxplots.
`xlab` | label for horizontal axis.
`ylab` | label for vertical axis.
`las` | if `0`, ticks labels are drawn parallel to the axis; set to `1` for horizontal labels (see `par`).
`lwd` | width of linear-regression lines (default `1`).
`lty` | type of linear-regression lines (default `1`, solid line).
`id.method,id.n,id.cex,id.col` | Arguments for the labelling of points. The default is `id.n=0` for labeling no points. See `showLabels` for details of these arguments. If the plot uses different colors for groups, then the `id.col` argument is ignored and label colors are determined by the `col` argument.
`labels` | a vector of point labels; if absent, the function tries to determine reasonable labels, and, failing that, will use observation numbers.
`log` | same as the `log` argument to `plot`, to produce log axes.
`jitter` | a list with elements `x` or `y` or both, specifying jitter factors for the horizontal and vertical coordinates of the points in the scatterplot. The `jitter` function is used to randomly perturb the points; specifying a factor of `1` produces the default jitter. Fitted lines are unaffected by the jitter.
`xlim` | the x limits (min, max) of the plot; if `NULL`, determined from the data.
`ylim` | the y limits (min, max) of the plot; if `NULL`, determined from the data.
`groups` | a factor or other variable dividing the data into groups; groups are plotted with different colors and plotting characters.
`by.groups` | if `TRUE`, regression lines are fit by groups.
`legend.title` | title for legend box; defaults to the name of the groups variable.
`legend.coords` | coordinates for placing legend; can be a list with components x and y to specify the coordinates of the upper-left-hand corner of the legend; or a quoted keyword, such as `"topleft"`, recognized by `legend`.
`legend.columns` | number of columns for the legend; if absent will be supplied automatically to prefer horizontal legends when plotted above the graph.
`ellipse` | if `TRUE` data-concentration ellipses are plotted.
`levels` | level or levels at which concentration ellipses are plotted; the default is `c(.5, .95)`.
`robust` | if `TRUE` (the default) use the `cov.trob` function in the `MASS` package to calculate the center and covariance matrix for the data ellipses.
`col` | colors for lines and points; the default is taken from the color palette, with `palette()[3]` for linear regression lines, `palette()[2]` for nonparametric regression lines, and `palette()[1]` for points if there are no groups, and successive colors for the groups if there are groups.
`pch` | plotting characters for points; default is the plotting characters in order (see `par`).
`cex, cex.axis, cex.lab, cex.main, cex.sub` | set sizes of various graphical elements; (see `par`).
`legend.plot` | if `TRUE` then a legend for the groups is plotted in the upper margin.
`reset.par` | if `TRUE` then plotting parameters are reset to their previous values when `scatterplot` exits; if `FALSE` then the `mar` and `mfcol` parameters are altered for the current plotting device. Set to `FALSE` if you want to add graphical elements (such as lines) to the plot.
`...` | other arguments passed down and to `plot`.
`grid` | If TRUE, the default, a light-gray background grid is put on the graph

### Value

If points are identified, their labels are returned; otherwise `NULL` is returned invisibly.

### Author(s)

John Fox jfox@mcmaster.ca

### See Also

`boxplot`, `jitter`, `legend`, `scatterplotMatrix`, `dataEllipse`, `Boxplot`, `cov.trob`, `showLabels`, `ScatterplotSmoothers`.

### Examples

    scatterplot(prestige ~ income, data=Prestige, ellipse=TRUE)

    if (interactive()){
    scatterplot(prestige ~ income, data=Prestige, smoother=quantregLine)
    }

    scatterplot(prestige ~ income|type, data=Prestige, smoother=loessLine,
        smoother.args=list(span=1))

    scatterplot(prestige ~ income|type, data=Prestige, legend.coords="topleft")

    scatterplot(vocabulary ~ education, jitter=list(x=1, y=1),
    	data=Vocab, id.n=0, smoother=FALSE)

    scatterplot(infant.mortality ~ gdp, log="xy", data=UN, id.n=5)

    scatterplot(income ~ type, data=Prestige)

    	## Not run:
    scatterplot(infant.mortality ~ gdp, id.method="identify", data=UN)

    scatterplot(infant.mortality ~ gdp, id.method="identify", smoother=loessLine, data=UN)

    ## End(Not run)

[Package car version 2.1-2 Index]