spatstat.explore (version 3.2-3)

plot.fv: Plot Function Values

Description

Plot method for the class "fv".

Usage

# S3 method for fv
plot(x, fmla, ..., subset=NULL, lty=NULL, col=NULL, lwd=NULL,
           xlim=NULL, ylim=NULL, xlab=NULL, ylab=NULL,
           clip.xlim=TRUE, ylim.covers=NULL,
           legend=!add, legendpos="topleft", legendavoid=missing(legendpos),
           legendmath=TRUE, legendargs=list(),
           shade=fvnames(x, ".s"), shadecol="grey",
           add=FALSE, log="",
           mathfont=c("italic", "plain", "bold", "bolditalic"), 
           limitsonly=FALSE)

Value

Invisible: either NULL, or a data frame giving the meaning of the different line types and colours.

Arguments

x

An object of class "fv", containing the variables to be plotted or variables from which the plotting coordinates can be computed.

fmla

an R language formula determining which variables or expressions are plotted. Either a formula object, or a string that can be parsed as a formula. See Details.

subset

(optional) subset of rows of the data frame that will be plotted.

lty

(optional) numeric vector of values of the graphical parameter lty controlling the line style of each plot.

col

(optional) numeric vector of values of the graphical parameter col controlling the colour of each plot.

lwd

(optional) numeric vector of values of the graphical parameter lwd controlling the line width of each plot.

xlim

(optional) range of x axis

ylim

(optional) range of y axis

xlab

(optional) label for x axis

ylab

(optional) label for y axis

...

Extra arguments passed to plot.default.

clip.xlim

Logical value specifying whether the range of the horizontal axis xlim should be automatically restricted to a subset of the range of the available data. See the section on Controlling the horizontal axis limits below.

ylim.covers

Optional vector of \(y\) values that must be included in the \(y\) axis. For example ylim.covers=0 will ensure that the \(y\) axis includes the origin.

legend

Logical flag or NULL. If legend=TRUE, the algorithm plots a legend in the top left corner of the plot, explaining the meaning of the different line types and colours.

legendpos

The position of the legend. Either a character string keyword (see legend for keyword options) or a pair of coordinates in the format list(x,y). Alternatively if legendpos="float", a location will be selected inside the plot region, avoiding the graphics.

legendavoid

Whether to avoid collisions between the legend and the graphics. Logical value. If TRUE, the code will check for collisions between the legend box and the graphics, and will override legendpos if a collision occurs. If FALSE, the value of legendpos is always respected.

legendmath

Logical. If TRUE, the legend will display the mathematical notation for each curve. If FALSE, the legend text is the identifier (column name) for each curve.

legendargs

Named list containing additional arguments to be passed to legend controlling the appearance of the legend.

shade

A character vector giving the names of two columns of x, or another type of index that identifies two columns. When the corresponding curves are plotted, the region between the curves will be shaded in light grey. The object x may or may not contain two columns which are designated as boundaries for shading; they are identified by fvnames(x, ".s"). The default is to shade between these two curves if they exist. To suppress this behaviour, set shade=NULL.

shadecol

The colour to be used in the shade plot. A character string or an integer specifying a colour.

add

Logical. Whether the plot should be added to an existing plot

log

A character string which contains "x" if the x axis is to be logarithmic, "y" if the y axis is to be logarithmic and "xy" or "yx" if both axes are to be logarithmic.

mathfont

Character string. The font to be used for mathematical expressions in the axis labels and the legend.

limitsonly

Logical. If FALSE, plotting is performed normally. If TRUE, no plotting is performed at all; just the \(x\) and \(y\) limits of the plot are computed and returned.

Controlling the horizontal axis limits

The plot generated by plot(x) does not necessarily display all the data that is contained in the object. The range of values of the function argument \(r\) displayed in the plot may be narrower than the range of values actually contained in the data frame.

To override this behaviour and display all the available data, set clip.xlim=FALSE.

Statistical literature for summary functions of spatial data recommends that, when the function is plotted, the values of the function argument on the horizontal axis should be restricted to a limited range of values. For example, Ripley recommends that the K-function \(K(r)\) should be plotted only for values of distance \(r\) between \(0\) and \(b/4\) where \(b\) is the shortest side of the enclosing rectangle of the data.

This may be desirable so that the interesting detail is clearly visible in the plot. It may be necessary because values outside the recommended range are theoretically invalid, or unreliable due to high variance or large bias.

To support this standard practice, each object of class "fv" may include data specifying a “recommended range” of values of the function argument. The object produced by Kest includes a recommended range following Ripley's recommendation above. Similarly for Gest, Fest and many other commands.

When plot(x) is executed, the horizontal axis is restricted to the recommended range of values. This recommendation can be overridden by setting clip.xlim=FALSE or by specifying the numerical limits xlim.

Author

Adrian Baddeley and Rolf Turner

Details

This is the plot method for the class "fv".

An object of class "fv" is a convenient way of storing several different statistical estimates of a summary function; see fv.object. The default behaviour, executed by plot(x), displays these different estimates as curves with different colours and line styles, and plots a legend explaining them.

The use of the argument fmla is like plot.formula, but offers some extra functionality.

The left and right hand sides of fmla are evaluated, and the results are plotted against each other (the left side on the \(y\) axis against the right side on the \(x\) axis).

The left and right hand sides of fmla may be the names of columns of the data frame x, or expressions involving these names. If a variable in fmla is not the name of a column of x, the algorithm will search for an object of this name in the environment where plot.fv was called, and then in the enclosing environment, and so on.

Multiple curves may be specified by a single formula of the form cbind(y1,y2,...,yn) ~ x, where x,y1,y2,...,yn are expressions involving the variables in the data frame. Each of the variables y1,y2,...,yn in turn will be plotted against x. See the examples.

Convenient abbreviations which can be used in the formula are

• the symbol . which represents all the columns in the data frame that will be plotted by default;

• the symbol .x which represents the function argument;

• the symbol .y which represents the recommended value of the function.

For further information, see fvnames.

The value returned by this plot function indicates the meaning of the line types and colours in the plot. It can be used to make a suitable legend for the plot if you want to do this by hand. See the examples.

The argument shade can be used to display critical bands or confidence intervals. If it is not NULL, then it should be a subset index for the columns of x, that identifies exactly 2 columns. When the corresponding curves are plotted, the region between the curves will be shaded in light grey. See the Examples.

The default values of lty, col and lwd can be changed using spatstat.options("plot.fv").

Use type = "n" to create the plot region and draw the axes without plotting any data.

Use limitsonly=TRUE to suppress all plotting and just compute the \(x\) and \(y\) limits. This can be used to calculate common \(x\) and \(y\) scales for several plots.

To change the kind of parenthesis enclosing the explanatory text about the unit of length, use spatstat.options('units.paren')

See Also

fv.object, Kest

Examples

   K <- Kest(cells)
   # K is an object of class "fv"

   plot(K, iso ~ r)                # plots iso against r

   plot(K, sqrt(iso/pi) ~ r)   # plots sqrt(iso/r)  against r

   plot(K, cbind(iso,theo) ~ r)   # plots iso against r  AND theo against r

   plot(K, .  ~ r)            # plots all available estimates of K against r

   plot(K, sqrt(./pi) ~ r)   # plots all estimates of L-function
                             # L(r) = sqrt(K(r)/pi)

   plot(K, cbind(iso,theo) ~ r, col=c(2,3))
                                   # plots iso against r  in colour 2
                                   # and theo against r in colour 3

   plot(K, iso ~ r, subset=quote(r < 0.2))
                                   # plots iso against r for r < 10

   # Can't remember the names of the columns? No problem..
   plot(K, sqrt(./pi) ~ .x)

   # making a legend by hand
   v <- plot(K, . ~ r, legend=FALSE)
   legend("topleft", legend=v$meaning, lty=v$lty, col=v$col)

   # significance bands
   KE <- envelope(cells, Kest, nsim=19)
   plot(KE, shade=c("hi", "lo"))

   # how to display two functions on a common scale
   Kr <- Kest(redwood)
   a <- plot(K, limitsonly=TRUE)
   b <- plot(Kr, limitsonly=TRUE)
   xlim <- range(a$xlim, b$xlim)
   ylim <- range(a$ylim, b$ylim)
   opa <- par(mfrow=c(1,2))
   plot(K, xlim=xlim, ylim=ylim)
   plot(Kr, xlim=xlim, ylim=ylim)
   par(opa)
   # For a shortcut, try plot(anylist(K, Kr), equal.scales=TRUE)