text                package:graphics                R Documentation

Add Text to a Plot

Description:

     'text' draws the strings given in the vector 'labels' at the
     coordinates given by 'x' and 'y'. 'y' may be missing since
     'xy.coords(x,y)' is used for construction of the coordinates.

Usage:

     text(x, ...)

     ## Default S3 method:
     text (x, y = NULL, labels = seq(along = x), adj = NULL,
          pos = NULL, offset = 0.5, vfont = NULL,
          cex = 1, col = NULL, font = NULL, xpd = NULL, ...)

Arguments:

    x, y: numeric vectors of coordinates where the text 'labels' should
          be written.  If the length of 'x' and 'y' differs, the
          shorter one is recycled.

  labels: one or more character strings or expressions specifying the
          _text_ to be written.  An attempt is made to coerce other
          vectors to character, and other language objects to
          expressions.

     adj: one or two values in [0,1] which specify the x (and
          optionally y) adjustment of the labels.  On most devices
          values outside that interval will also work.

     pos: a position specifier for the text.  If specified this
          overrides any 'adj' value given.  Values of '1', '2', '3' and
          '4', respectively indicate positions below, to the left of,
          above and to the right of the specified coordinates.

  offset: when 'pos' is specified, this value gives the offset of the
          label from the specified coordinate in fractions of a
          character width.

   vfont: if a character vector of length 2 is specified, then Hershey
          vector fonts are used.  The first element of the vector
          selects a typeface and the second element selects a style.

     cex: numeric *c*haracter *ex*pansion factor; multiplied by
          'par("cex")' yields the final character size.

col, font: the color and font to be used; these default to the values
          of the global graphical parameters in 'par()'.

     xpd: (where) should clipping take place?  Defaults to
          'par("xpd")'.

     ...: further graphical parameters (from 'par').

Details:

     'labels' must be of type 'character' or 'expression' (or be
     coercible to such a type). In the latter case, quite a bit of
     mathematical notation is available such as sub- and superscripts,
     greek letters, fractions, etc.

     'adj' allows _adj_ustment of the text with respect to '(x,y)'.
     Values of 0, 0.5, and 1 specify left/bottom, middle and right/top,
     respectively.  The default is for centered text, i.e., 'adj =
     c(0.5, 0.5)'. Accurate vertical centering needs character metric
     information on individual characters, which is only available on
     some devices.

     The 'pos' and 'offset' arguments can be used in conjunction with
     values returned by 'identify' to recreate an interactively
     labelled plot.

     Text can be rotated by using graphical parameters 'srt' (see
     'par'); this rotates about the centre set by 'adj'.

     Graphical parameters 'col', 'cex' and 'font' can be vectors and
     will then be applied cyclically to the 'labels' (and extra values
     will be ignored).

     Labels whose 'x', 'y', 'labels', 'cex' or 'col' value is 'NA' are
     omitted from the plot.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'mtext', 'title', 'Hershey' for details on Hershey vector fonts,
     'plotmath' for details and more examples on mathematical
     annotation.

Examples:

     plot(-1:1,-1:1, type = "n", xlab = "Re", ylab = "Im")
     K <- 16; text(exp(1i * 2 * pi * (1:K) / K), col = 2)

     ## The following two examples use latin1 characters: these may not
     ## appear correctly (or be omitted entirely).
     plot(1:10, 1:10, main = "text(...) examples\n~~~~~~~~~~~~~~",
          sub = "R is GNU ©, but not ® ...")
     mtext("«ISO-accents»: ± éè øØ å<Å æ<Æ", side=3)
     points(c(6,2), c(2,1), pch = 3, cex = 4, col = "red")
     text(6, 2, "the text is CENTERED around (x,y) = (6,2) by default",
          cex = .8)
     text(2, 1, "or Left/Bottom - JUSTIFIED at (2,1) by 'adj = c(0,0)'",
          adj = c(0,0))
     text(4, 9, expression(hat(beta) == (X^t * X)^{-1} * X^t * y))
     text(4, 8.4, "expression(hat(beta) == (X^t * X)^{-1} * X^t * y)", cex = .75)
     text(4, 7, expression(bar(x) == sum(frac(x[i], n), i==1, n)))

     ## Two more latin1 examples
     text(5,10.2,
          "Le français, c'est façile: Règles, Liberté, Egalité, Fraternité...")
     text(5,9.8, "Jetz no chli züritüütsch: (noch ein bißchen Zürcher deutsch)")

