\inputencoding{latin1}
\HeaderA{text}{Add Text to a Plot}{text}
\methaliasA{text.default}{text}{text.default}
\keyword{aplot}{text}
\begin{Description}\relax
\code{text} draws the strings given in the vector \code{labels} at the
coordinates given by \code{x} and \code{y}.
\code{y} may be missing since \code{\LinkA{xy.coords}{xy.coords}(x,y)} is used for
construction of the coordinates.
\end{Description}
\begin{Usage}
\begin{verbatim}
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, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, y}] numeric vectors of coordinates where the text
\code{labels} should be written.  If the length of \code{x} and
\code{y} differs, the shorter one is recycled.
\item[\code{labels}] a character vector or \LinkA{expression}{expression} specifying
the \emph{text} to be written.  An attempt is made to coerce other
language objects (names and calls) to expressions, and vectors and
other classed objects to character vectors by \code{\LinkA{as.character}{as.character}}.
If \code{labels} is longer than \code{x} and
\code{y}, the coordinates are recycled to the length of \code{labels}.
\item[\code{adj}] one or two values in \eqn{[0,1]}{} which specify the x
(and optionally y) adjustment of the labels.  On most devices values
outside that interval will also work.
\item[\code{pos}] a position specifier for the text.  If specified this
overrides any \code{adj} value given.  Values of \code{1},
\code{2}, \code{3} and \code{4}, respectively indicate
positions below, to the left of, above and to the right of
the specified coordinates.
\item[\code{offset}] when \code{pos} is specified, this value gives the
offset of the label from the specified coordinate in fractions
of a character width.
\item[\code{vfont}] \code{NULL} for the current font family, or a character
vector of length 2 for Hershey vector fonts.  The first element of
the vector selects a typeface and the second element selects a
style.  Ignored if \code{labels} is an expression.
\item[\code{cex}] numeric \bold{c}haracter \bold{ex}pansion factor; multiplied
by \code{\LinkA{par}{par}("cex")} yields the final character size.
\code{NULL} and \code{NA} are equivalent to \code{1.0}.
\item[\code{col, font}] the color and (if \code{vfont = NULL}) font to be
used, possibly vectors. These default to the values of the global
graphical parameters in \code{\LinkA{par}{par}()}.
\item[\code{...}] further graphical parameters (from \code{\LinkA{par}{par}}),
such as \code{srt}, \code{family} and \code{xpd}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{labels} must be of type \code{\LinkA{character}{character}} or
\code{\LinkA{expression}{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.

\code{adj} allows \emph{adj}ustment of the text with respect to \code{(x,y)}.
Values of 0, 0.5, and 1 specify left/bottom, middle and
right/top alignment, respectively.  The default is for centered text, i.e.,
\code{adj = c(0.5, 0.5)}.  Accurate vertical centering needs
character metric information on individual characters which is
only available on some devices.  Vertical alignment is done slightly
differently for character strings and for expressions:
\code{adj=c(0,0)} means to left-justify and to align on the baseline
for strings but on the bottom of the bounding box for expressions.
This also affects vertical centering: for strings the centering
excludes any descenders whereas for expressions it includes them.

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

Text can be rotated by using graphical parameters \code{srt} (see
\code{\LinkA{par}{par}}); this rotates about the centre set by \code{adj}.

Graphical parameters \code{col}, \code{cex} and \code{font} can be
vectors and will then be applied cyclically to the \code{labels} (and
extra values will be ignored).  \code{NA} values of \code{font} are
replaced by \code{par("font")}.

Labels whose \code{x}, \code{y}, \code{labels}, \code{cex} or \code{col}
value is \code{NA} are omitted from the plot.

What happens when \code{font = 5} (the symbol font) is selected can be
both device- and locale-dependent.  Most often \code{labels} will be
interpreted in the Adobe symbol encoding, so e.g. \code{"d"} is delta,
and \code{"\bsl{}300"} is aleph.
\end{Details}
\begin{Section}{Euro symbol}
The Euro symbol was introduced relatively recently and may not be
available in older fonts.  In recent versions of Adobe symbol fonts it
is character 160, so \code{text(x, y, "\bsl{}xA0", font = 5)} may work.
People using Western European locales on Unix-alikes can probably
select ISO-8895-15 (Latin-9) which has the Euro as character 165: this
can also be used for \code{\LinkA{postscript}{postscript}} and \code{\LinkA{pdf}{pdf}}.
It is \samp{\u20ac} in Unicode, which can be used in UTF-8 locales.

The Euro should be rendered correctly by \code{\LinkA{X11}{X11}} in UTF-8
locales, but the corresponding single-byte encoding in
\code{\LinkA{postscript}{postscript}} and \code{\LinkA{pdf}{pdf}} will need to be selected
as \code{ISOLatin9.enc}.
\end{Section}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.

Murrell, P. (2005) \emph{R Graphics}. Chapman \& Hall/CRC Press.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{mtext}{mtext}}, \code{\LinkA{title}{title}},
\code{\LinkA{Hershey}{Hershey}} for details on Hershey vector fonts,
\code{\LinkA{plotmath}{plotmath}} for details and more examples on
mathematical annotation.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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("«Latin-1 accented chars»: éè øØ å<Å æ<Æ", 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)")
\end{ExampleCode}
\end{Examples}

