EVOLUTION-MANAGER
Edit File: points.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Add Points to a Plot</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for points {graphics}"><tr><td>points {graphics}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Add Points to a Plot</h2> <h3>Description</h3> <p><code>points</code> is a generic function to draw a sequence of points at the specified coordinates. The specified character(s) are plotted, centered at the coordinates. </p> <h3>Usage</h3> <pre> points(x, ...) ## Default S3 method: points(x, y = NULL, type = "p", ...) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>x, y</code></td> <td> <p>coordinate vectors of points to plot.</p> </td></tr> <tr valign="top"><td><code>type</code></td> <td> <p>character indicating the type of plotting; actually any of the <code>type</code>s as in <code><a href="plot.default.html">plot.default</a></code>.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>Further <a href="par.html">graphical parameters</a> may also be supplied as arguments. See ‘Details’.</p> </td></tr> </table> <h3>Details</h3> <p>The coordinates can be passed in a plotting structure (a list with <code>x</code> and <code>y</code> components), a two-column matrix, a time series, .... See <code><a href="../../grDevices/html/xy.coords.html">xy.coords</a></code>. If supplied separately, they must be of the same length. </p> <p>Graphical parameters commonly used are </p> <dl> <dt><code>pch</code></dt><dd><p>plotting ‘character’, i.e., symbol to use. This can either be a single character or an integer code for one of a set of graphics symbols. The full set of S symbols is available with <code>pch = 0:18</code>, see the examples below. (NB: <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> uses circles instead of the octagons used in S.) </p> <p>Value <code>pch = "."</code> (equivalently <code>pch = 46</code>) is handled specially. It is a rectangle of side 0.01 inch (scaled by <code>cex</code>). In addition, if <code>cex = 1</code> (the default), each side is at least one pixel (1/72 inch on the <code><a href="../../grDevices/html/pdf.html">pdf</a></code>, <code><a href="../../grDevices/html/postscript.html">postscript</a></code> and <code><a href="../../grDevices/html/xfig.html">xfig</a></code> devices). </p> <p>For other text symbols, <code>cex = 1</code> corresponds to the default fontsize of the device, often specified by an argument <code>pointsize</code>. For <code>pch</code> in <code>0:25</code> the default size is about 75% of the character height (see <code>par("cin")</code>). </p> </dd> <dt><code>col</code></dt><dd><p>color code or name, see <code><a href="par.html">par</a></code>.</p> </dd> <dt><code>bg</code></dt><dd><p>background (fill) color for the open plot symbols given by <code>pch = 21:25</code>.</p> </dd> <dt><code>cex</code></dt><dd><p>character (or symbol) expansion: a numerical vector. This works as a multiple of <code><a href="par.html">par</a>("cex")</code>.</p> </dd> <dt><code>lwd</code></dt><dd><p>line width for drawing symbols see <code><a href="par.html">par</a></code>.</p> </dd> </dl> <p>Others less commonly used are <code>lty</code> and <code>lwd</code> for types such as <code>"b"</code> and <code>"l"</code>. </p> <p>The <a href="par.html">graphical parameters</a> <code>pch</code>, <code>col</code>, <code>bg</code>, <code>cex</code> and <code>lwd</code> can be vectors (which will be recycled as needed) giving a value for each point plotted. If lines are to be plotted (e.g., for <code>type = "b"</code>) the first element of <code>lwd</code> is used. </p> <p>Points whose <code>x</code>, <code>y</code>, <code>pch</code>, <code>col</code> or <code>cex</code> value is <code>NA</code> are omitted from the plot. </p> <h3>'pch' values</h3> <p>Values of <code>pch</code> are stored internally as integers. The interpretation is </p> <ul> <li> <p><code>NA_integer_</code>: no symbol. </p> </li> <li> <p><code>0:18</code>: S-compatible vector symbols. </p> </li> <li> <p><code>19:25</code>: further <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> vector symbols. </p> </li> <li> <p><code>26:31</code>: unused (and ignored). </p> </li> <li> <p><code>32:127</code>: ASCII characters. </p> </li> <li> <p><code>128:255</code> native characters <em>only in a single-byte locale and for the symbol font</em>. (<code>128:159</code> are only used on Windows.) </p> </li> <li> <p><code>-32 ...</code> Unicode code point (where supported). </p> </li></ul> <p>Note that unlike S (which uses octagons), symbols <code>1</code>, <code>10</code>, <code>13</code> and <code>16</code> use circles. The filled shapes <code>15:18</code> do not include a border. </p> <p><img src="../help/figures/pch.png" alt="Illustration of pch = 0:25" /> </p> <p>The following <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> plotting symbols are can be obtained with <code>pch = 19:25</code>: those with <code>21:25</code> can be colored and filled with different colors: <code>col</code> gives the border color and <code>bg</code> the background color (which is <span class="samp">"grey"</span> in the figure) </p> <ul> <li> <p><code>pch = 19</code>: solid circle, </p> </li> <li> <p><code>pch = 20</code>: bullet (smaller solid circle, 2/3 the size of <code>19</code>), </p> </li> <li> <p><code>pch = 21</code>: filled circle, </p> </li> <li> <p><code>pch = 22</code>: filled square, </p> </li> <li> <p><code>pch = 23</code>: filled diamond, </p> </li> <li> <p><code>pch = 24</code>: filled triangle point-up, </p> </li> <li> <p><code>pch = 25</code>: filled triangle point down. </p> </li></ul> <p>Note that all of these both fill the shape and draw a border. Some care in interpretation is needed when semi-transparent colours are used for both fill and border (and the result might be device-specific and even viewer-specific for <code><a href="../../grDevices/html/pdf.html">pdf</a></code>). </p> <p>The difference between <code>pch = 16</code> and <code>pch = 19</code> is that the latter uses a border and so is perceptibly larger when <code>lwd</code> is large relative to <code>cex</code>. </p> <p>Values <code>pch = 26:31</code> are currently unused and <code>pch = 32:127</code> give the ASCII characters. In a single-byte locale <code>pch = 128:255</code> give the corresponding character (if any) in the locale's character set. Where supported by the OS, negative values specify a Unicode code point, so e.g. <code>-0x2642L</code> is a ‘male sign’ and <code>-0x20ACL</code> is the Euro. </p> <p>A character string consisting of a single character is converted to an integer: <code>32:127</code> for ASCII characters, and usually to the Unicode code point otherwise. (In non-Latin-1 single-byte locales, <code>128:255</code> will be used for 8-bit characters.) </p> <p>If <code>pch</code> supplied is a logical, integer or character <code>NA</code> or an empty character string the point is omitted from the plot. </p> <p>If <code>pch</code> is <code>NULL</code> or otherwise of length 0, <code>par("pch")</code> is used. </p> <p>If the symbol font (<code><a href="par.html">par</a>(font = 5)</code>) is used, numerical values should be used for <code>pch</code>: the range is <code>c(32:126, 160:254)</code> in all locales (but <code>240</code> is not defined (used for ‘apple’ on macOS) and <code>160</code>, Euro, may not be present). </p> <h3>Note</h3> <p>A single-byte encoding may include the characters in <code>pch = 128:255</code>, and if it does, a font may not include all (or even any) of them. </p> <p>Not all negative numbers are valid as Unicode code points, and no check is done. A display device is likely to use a rectangle for (or omit) Unicode code points which are invalid or for which it does not have a glyph in the font used. </p> <p>What happens for very small or zero values of <code>cex</code> is device-dependent: symbols or characters may become invisible or they may be plotted at a fixed minimum size. Circles of zero radius will not be plotted. </p> <h3>References</h3> <p>Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) <em>The New S Language</em>. Wadsworth & Brooks/Cole. </p> <h3>See Also</h3> <p><code><a href="plot.formula.html">points.formula</a></code> for the formula method; <code><a href="plot.html">plot</a></code>, <code><a href="lines.html">lines</a></code>, and the underlying workhorse function <code><a href="plot.xy.html">plot.xy</a></code>. </p> <h3>Examples</h3> <pre> require(stats) # for rnorm plot(-4:4, -4:4, type = "n") # setting up coord. system points(rnorm(200), rnorm(200), col = "red") points(rnorm(100)/2, rnorm(100)/2, col = "blue", cex = 1.5) op <- par(bg = "light blue") x <- seq(0, 2*pi, len = 51) ## something "between type='b' and type='o'": plot(x, sin(x), type = "o", pch = 21, bg = par("bg"), col = "blue", cex = .6, main = 'plot(..., type="o", pch=21, bg=par("bg"))') par(op) ## Not run: ## The figure was produced by calls like png("pch.png", height = 0.7, width = 7, res = 100, units = "in") par(mar = rep(0,4)) plot(c(-1, 26), 0:1, type = "n", axes = FALSE) text(0:25, 0.6, 0:25, cex = 0.5) points(0:25, rep(0.3, 26), pch = 0:25, bg = "grey") ## End(Not run) ##-------- Showing all the extra & some char graphics symbols --------- pchShow <- function(extras = c("*",".", "o","O","0","+","-","|","%","#"), cex = 3, ## good for both .Device=="postscript" and "x11" col = "red3", bg = "gold", coltext = "brown", cextext = 1.2, main = paste("plot symbols : points (... pch = *, cex =", cex,")")) { nex <- length(extras) np <- 26 + nex ipch <- 0:(np-1) k <- floor(sqrt(np)) dd <- c(-1,1)/2 rx <- dd + range(ix <- ipch %/% k) ry <- dd + range(iy <- 3 + (k-1)- ipch %% k) pch <- as.list(ipch) # list with integers & strings if(nex > 0) pch[26+ 1:nex] <- as.list(extras) plot(rx, ry, type = "n", axes = FALSE, xlab = "", ylab = "", main = main) abline(v = ix, h = iy, col = "lightgray", lty = "dotted") for(i in 1:np) { pc <- pch[[i]] ## 'col' symbols with a 'bg'-colored interior (where available) : points(ix[i], iy[i], pch = pc, col = col, bg = bg, cex = cex) if(cextext > 0) text(ix[i] - 0.3, iy[i], pc, col = coltext, cex = cextext) } } pchShow() pchShow(c("o","O","0"), cex = 2.5) pchShow(NULL, cex = 4, cextext = 0, main = NULL) ## ------------ test code for various pch specifications ------------- # Try this in various font families (including Hershey) # and locales. Use sign = -1 asserts we want Latin-1. # Standard cases in a MBCS locale will not plot the top half. TestChars <- function(sign = 1, font = 1, ...) { MB <- l10n_info()$MBCS r <- if(font == 5) { sign <- 1; c(32:126, 160:254) } else if(MB) 32:126 else 32:255 if (sign == -1) r <- c(32:126, 160:255) par(pty = "s") plot(c(-1,16), c(-1,16), type = "n", xlab = "", ylab = "", xaxs = "i", yaxs = "i", main = sprintf("sign = %d, font = %d", sign, font)) grid(17, 17, lty = 1) ; mtext(paste("MBCS:", MB)) for(i in r) try(points(i%%16, i%/%16, pch = sign*i, font = font,...)) } TestChars() try(TestChars(sign = -1)) TestChars(font = 5) # Euro might be at 160 (0+10*16). # macOS has apple at 240 (0+15*16). try(TestChars(-1, font = 2)) # bold </pre> <hr /><div style="text-align: center;">[Package <em>graphics</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>