points.geodata {geoR} | R Documentation

## Plots Spatial Locations and Data Values

### Description

This function produces a plot with points indicating the data locations. Arguments can control the points sizes, patterns and colors. These can be set to be proportional to data values, ranks or quantiles. Alternatively, points can be added to the current plot.

### Usage

    ## S3 method for class 'geodata':
    points(x, coords=x$coords, data=x$data, data.col = 1, borders,
                   pt.divide=c("data.proportional","rank.proportional",
                               "quintiles", "quartiles", "deciles", "equal"),
                   lambda = 1, trend = "cte", abs.residuals = FALSE,
                   weights.divide = "units.m", cex.min, cex.max, cex.var,
                   pch.seq, col.seq, add.to.plot = FALSE,
                   x.leg, y.leg, dig.leg = 2,
                   round.quantiles = FALSE, graph.pars = FALSE,
                   permute = FALSE, ...)

### Arguments

`x` | a list containing elements `coords` and `data` described next. Typically an object of the class `"geodata"` - a geoR data-set. If not provided the arguments `coords` and `data` must be provided instead.
`coords` | an n x 2 matrix containing coordinates of the n data locations in each row. Defaults to `geodata$coords`.
`data` | a vector or matrix with data values. If a matrix is provided each column is regarded as one variable or realization. Defaults to `geodata$data`.
`data.col` | the number of the data column. Only used if `data` is a matrix with columns corresponding to different variables or simulations.
`borders` | If an nx2 matrix or data-frame with the coordinates of the borders of the regions is provided, the borders are added to the plot. By default it searches for a element named "borders" in the geodata object.
`pt.divide` | defines the division of the points in categories. See `DETAILS` below for the available options. Defaults to `pt.divide = "data.proportional"`.
`trend` | specifies the mean part of the model. The options are: `"cte"` (constant mean - default option), `"1st"` (a first order polynomial on the coordinates), `"2nd"` (a second order polynomial on the coordinates), or a formula of the type `~X` where `X` is a matrix with the covariates (external trend). If provided the trend is "removed" using the function `lm` and the residuals are plotted.
`abs.residuals` | logical. If `TRUE` and the value passed to the argument `trend` is different from `"cte"` the point sizes are proportional to absolute values of the residuals.
`lambda` | value of the Box-Cox transformation parameter. Two particular cases are lambda = 1 which corresponds to no transformation and lambda = 0 corresponding to the log-transformation.
`weights.divide` | if a vector of weights with the same length as the data is provided each data is divided by the corresponding element in this vector. Defaults divides the data by the element `units.m` in the data object, if present, otherwise no action is taken and original data is used. The usage oc `units.m` is common for data objects to be analysed using the package geoRglm.
`cex.min` | minimum value for the graphical parameter `cex`. This value defines the size of the point corresponding the minimum of the data. Defaults to 0.5.
`cex.max` | maximum value for the graphical parameter `cex`. This value defines the size of the point corresponding the maximum of the data. If `pt.divide = "equal"` it is used to set the value for the graphical parameter `cex`. Defaults to 1.5.
`cex.var` | a numeric vector with the values of a variable defining the size of the points. Particularly useful for displaying 2 variables at once.
`pch.seq` | number(s) defining the graphical parameter `pch`.
`col.seq` | number(s) defining the colors in the graphical parameter `col`.
`add.to.plot` | logical. If `TRUE` the points are added to the current plot otherwise a display is open. Defaults to `FALSE`.
`x.leg, y.leg` | `x` and `y` location of the legend.
`dig.leg` | integer indicating the precision to be used in the legend values.
`round.quantiles` | logical. Defines whether or not the values of the quantiles should be rounded. Defaults to `FALSE`.
`graph.pars` | logical. If `TRUE` the graphics parameters used to produce the plots are returned. Defaults to `FALSE`.
`permute` | logical indication whether the data values should be randomly re-alocatted to the coordinates. See `DETAILS` below.
`...` | further arguments to be passed to the function `plot`, if `add.to.plot = FALSE`; or to the function `points`, if `add.to.plot = TRUE`.

### Details

The points can be devided in categories and have different sizes and/or colours according to the argument `pt.divide`. The options are:

"data.proportional"
  sizes proportional to the data values.
"rank.proportional"
  sizes proportional to the rank of the data.
"quintiles"
  five different sizes according to the quintiles of the data.
"quartiles"
  four different sizes according to the quartiles of the data.
"deciles"
  ten different sizes according to the deciles of the data.
"equal"
  all points with the same size.
a scalar
  defines a number of quantiles, the number provided defines the number of different points sizes and colors.
a numerical vector with quantiles and length > 1
  the values in the vector will be used by the function `cut` as break points to divide the data in classes.

For cases where points have different sizes the arguments `cex.min` and `cex.max` set the minimum and the maximum point sizes. Additionally, `pch.seq` can set different patterns for the points and `col.seq` can be used to define colors. For example, different colors can be used for quartiles, quintiles and deciles while a sequence of gray tones (or a color sequence) can be used for point sizes proportional to the data or their ranks. For more details see the section `EXAMPLES`.

The argument `cex.var` allows for displaying 2 variables at once. In this case one variable defines the backgroung colour of the points and the other defines the points size.

The argument `permute` if set to `TRUE` randomly realocates the data in the coordinates. This may be used to contrast the spatial pattern of original data against another situation where there is no spatial dependence (when setting `permute = TRUE`). If a `trend` is provided the residuals (and not the original data) are permuted.

### Value

A plot is created or points are added to the current graphics device.
By default no value is returned. However, if `graph.pars = TRUE` a list with graphical parameters used to produce the plot is returned. According to the input options, the list has some or all of the following components:

`quantiles` | the values of the quantiles used to divide the data.
`cex` | the values of the graphics expansion parameter `cex`.
`col` | the values of the graphics color parameter `col`.
`pch` | the values of the graphics pattern parameter `pch`.

### Author(s)

Paulo J. Ribeiro Jr. paulojus@leg.ufpr.br,
Peter J. Diggle p.diggle@lancaster.ac.uk.

### References

Further information on the package geoR can be found at:
http://www.leg.ufpr.br/geoR.

### See Also

`plot.geodata` for another display of the data and `points` and `plot` for information on the generic R functions. The documentation of `par` provides details on graphical parameters. For color schemes in R see `gray` and `rainbow`.

### Examples

    op <- par(no.readonly = TRUE)
    par(mfrow=c(2,2), mar=c(3,3,1,1), mgp = c(2,1,0))
    points(s100, xlab="Coord X", ylab="Coord Y")
    points(s100, xlab="Coord X", ylab="Coord Y", pt.divide="rank.prop")
    points(s100, xlab="Coord X", ylab="Coord Y", cex.max=1.7,
                   col=gray(seq(1, 0.1, l=100)), pt.divide="equal")
    points(s100, pt.divide="quintile", xlab="Coord X", ylab="Coord Y")
    par(op)

    points(ca20, pt.div='quartile', x.leg=4900, y.leg=5850, bor=borders)

    par(mfrow=c(1,2), mar=c(3,3,1,1), mgp = c(2,1,0))
    points(s100, main="Original data")
    points(s100, permute=TRUE, main="Permuting locations")

    ## Now an example using 2 variable, 1 defining the
    ## gray scale and the other the points size
    points.geodata(coords=camg[,1:2], data=camg[,3], col="gray",
                   cex.var=camg[,5])
    points.geodata(coords=camg[,1:2], data=camg[,3], col="gray",
                   cex.var=camg[,5], pt.div="quint")

[Package geoR version 1.6-19 Index]