\HeaderA{plotmath}{Mathematical Annotation in R}{plotmath}
\aliasA{atop}{plotmath}{atop}
\aliasA{bar}{plotmath}{bar}
\aliasA{bgroup}{plotmath}{bgroup}
\aliasA{bold}{plotmath}{bold}
\aliasA{bolditalic}{plotmath}{bolditalic}
\aliasA{displaystyle}{plotmath}{displaystyle}
\aliasA{dot}{plotmath}{dot}
\aliasA{frac}{plotmath}{frac}
\aliasA{group}{plotmath}{group}
\aliasA{hat}{plotmath}{hat}
\aliasA{inf}{plotmath}{inf}
\aliasA{integral}{plotmath}{integral}
\aliasA{italic}{plotmath}{italic}
\aliasA{over}{plotmath}{over}
\aliasA{phantom}{plotmath}{phantom}
\aliasA{plain}{plotmath}{plain}
\aliasA{ring}{plotmath}{ring}
\aliasA{scriptscriptstyle}{plotmath}{scriptscriptstyle}
\aliasA{scriptstyle}{plotmath}{scriptstyle}
\aliasA{sup}{plotmath}{sup}
\aliasA{symbol}{plotmath}{symbol}
\aliasA{textstyle}{plotmath}{textstyle}
\aliasA{underline}{plotmath}{underline}
\aliasA{widehat}{plotmath}{widehat}
\aliasA{widetilde}{plotmath}{widetilde}
\keyword{aplot}{plotmath}
\begin{Description}\relax
If the \code{text} argument to one of the text-drawing functions
(\code{\LinkA{text}{text}}, \code{\LinkA{mtext}{mtext}}, \code{\LinkA{axis}{axis}},
\code{\LinkA{legend}{legend}}) in \R{} is an expression, the argument is
interpreted as a mathematical expression and the output will be
formatted according to TeX-like rules.  Expressions can also be used
for titles, subtitles and x- and y-axis labels (but not for axis
labels on \code{persp} plots).

In most cases other language objects (names and calls) are coerced to
expressions and so can also be used.
\end{Description}
\begin{Details}\relax
A mathematical expression must obey the normal rules of syntax for any
\R{} expression, but it is interpreted according to very different rules
than for normal \R{} expressions.

It is possible to produce many different mathematical symbols, generate
sub- or superscripts, produce fractions, etc.

The output from \code{demo(plotmath)} includes several tables which
show the available features.  In these tables, the columns of grey text
show sample \R{} expressions, and the columns of black text show the
resulting output.

The available features are also described in the tables below:

\Tabular{ll}{
\bold{Syntax} & \bold{Meaning} \\

\code{x + y}   & x plus y   \\
\code{x - y}   & x minus y \\
\code{x*y}    & juxtapose x and y \\
\code{x/y}    & x forwardslash y \\
\code{x \%+-\% y}   & x plus or minus y \\
\code{x \%/\% y}   & x divided by y \\
\code{x \%*\% y}   & x times y \\
\code{x \%.\% y}   & x cdot y \\
\code{x[i]}   & x subscript i \\
\code{x\textasciicircum{}2}    & x superscript 2 \\
\code{paste(x, y, z)} & juxtapose x, y, and z \\
\code{sqrt(x)}   & square root of x \\
\code{sqrt(x, y)}   & yth root of x \\
\code{x == y}   & x equals y \\
\code{x != y}   & x is not equal to y \\
\code{x < y}   & x is less than y \\
\code{x <= y}   & x is less than or equal to y \\
\code{x > y}   & x is greater than y \\
\code{x >= y}   & x is greater than or equal to y \\
\code{x \%\textasciitilde{}\textasciitilde{}\% y}   & x is approximately equal to y \\
\code{x \%=\textasciitilde{}\% y}   & x and y are congruent \\
\code{x \%==\% y}   & x is defined as y \\
\code{x \%prop\% y}  & x is proportional to y \\
\code{plain(x)}   & draw x in normal font \\
\code{bold(x)}   & draw x in bold font \\
\code{italic(x)}   & draw x in italic font \\
\code{bolditalic(x)} & draw x in bolditalic font \\
\code{symbol(x)} & draw x in symbol font \\
\code{list(x, y, z)} & comma-separated list \\
\code{...}    & ellipsis (height varies) \\
\code{cdots}   & ellipsis (vertically centred) \\
\code{ldots}   & ellipsis (at baseline) \\
\code{x \%subset\% y} & x is a proper subset of y \\
\code{x \%subseteq\% y} & x is a subset of y \\
\code{x \%notsubset\% y} & x is not a subset of y \\
\code{x \%supset\% y} & x is a proper superset of y \\
\code{x \%supseteq\% y} & x is a superset of y \\
\code{x \%in\% y}   & x is an element of y \\
\code{x \%notin\% y} & x is not an element of y \\
\code{hat(x)}   & x with a circumflex \\
\code{tilde(x)}   & x with a tilde \\
\code{dot(x)} & x with a dot \\
\code{ring(x)}   & x with a ring \\
\code{bar(xy)}   & xy with bar \\
\code{widehat(xy)}   & xy with a wide circumflex \\
\code{widetilde(xy)} & xy with a wide tilde \\
\code{x \%<->\% y}   & x double-arrow y \\
\code{x \%->\% y}   & x right-arrow y \\
\code{x \%<-\% y}   & x left-arrow y \\
\code{x \%up\% y}   & x up-arrow y \\
\code{x \%down\% y}  & x down-arrow y \\
\code{x \%<=>\% y}   & x is equivalent to y \\
\code{x \%=>\% y}   & x implies y \\
\code{x \%<=\% y}   & y implies x \\
\code{x \%dblup\% y}   & x double-up-arrow y \\
\code{x \%dbldown\% y} & x double-down-arrow y \\
\code{alpha} -- \code{omega} & Greek symbols \\
\code{Alpha} -- \code{Omega} & uppercase Greek symbols \\
\code{theta1, phi1, sigma1, omega1} & cursive Greek symbols\\
\code{Upsilon1} & capital upsilon with hook\\
\code{infinity}   & infinity symbol \\
\code{partialdiff} & partial differential symbol \\
\code{32*degree}   & 32 degrees \\
\code{60*minute}   & 60 minutes of angle \\
\code{30*second}   & 30 seconds of angle \\
\code{displaystyle(x)} & draw x in normal size (extra spacing) \\
\code{textstyle(x)}  & draw x in normal size \\
\code{scriptstyle(x)} & draw x in small size \\
\code{scriptscriptstyle(x)} & draw x in very small size \\
\code{underline(x)}   & draw x underlined\\
\code{x \textasciitilde{}\textasciitilde{} y}        & put extra space between x and y \\
\code{x + phantom(0) + y} & leave gap for "0", but don't draw it \\
\code{x + over(1, phantom(0))} & leave vertical gap for "0" (don't draw) \\
\code{frac(x, y)}   & x over y \\
\code{over(x, y)}   & x over y \\
\code{atop(x, y)}   & x over y (no horizontal bar) \\
\code{sum(x[i], i==1, n)} & sum x[i] for i equals 1 to n \\
\code{prod(plain(P)(X==x), x)} & product of P(X=x) for all values of x \\
\code{integral(f(x)*dx, a, b)} & definite integral of f(x) wrt x \\
\code{union(A[i], i==1, n)} & union of A[i] for i equals 1 to n \\
\code{intersect(A[i], i==1, n)} & intersection of A[i] \\
\code{lim(f(x), x \%->\% 0)} & limit of f(x) as x tends to 0 \\
\code{min(g(x), x > 0)} & minimum of g(x) for x greater than 0 \\
\code{inf(S)}        & infimum of S \\
\code{sup(S)}   & supremum of S \\
\code{x\textasciicircum{}y + z}   & normal operator precedence \\
\code{x\textasciicircum{}(y + z)}    & visible grouping of operands \\
\code{x\textasciicircum{}\{y + z\}}  & invisible grouping of operands \\
\code{group("(",list(a, b),"]")} & specify left and right delimiters \\
\code{bgroup("(",atop(x,y),")")} & use scalable delimiters \\
\code{group(lceil, x, rceil)} & special delimiters \\
}

The symbol font uses Adobe Symbol encoding so, for example, a lower
case mu can be obtained either by the special symbol \code{mu} or by
\code{symbol("m")}.  This provides access to symbols that have no
special symbol name, for example, the universal, or forall, symbol is
\code{symbol("\bsl{}042")}, and \emph{aleph} is \code{symbol("\bsl{}300")}.

Note to TeX users: TeX's \code{\bsl{}Upsilon} is \code{Upsilon1}, TeX's
\code{\bsl{}varepsilon} is close to \code{epsilon}, and there is no
equivalent of TeX's \code{\bsl{}epsilon}.  TeX's \code{\bsl{}varpi} is close to
\code{omega1}.  \code{vartheta}, \code{varphi} and \code{varsigma} are
allowed as synonyms for \code{theta1}, \code{phi1} and \code{sigma1}.

\code{sigma1} is also known as \code{stigma}, its Unicode name.

Control characters (e.g. \code{\bsl{}n}) are not interpreted in character
strings in plotmath, unlike normal plotting.
\end{Details}
\begin{References}\relax
Murrell, P. and Ihaka, R. (2000) An approach to providing
mathematical annotation in plots.
\emph{Journal of Computational and Graphical Statistics},
\bold{9}, 582--599.

The symbol codes can be found in octal in the Adobe reference manuals,
e.g. for Postscript
\url{http://www.adobe.com/products/postscript/pdfs/PLRM.pdf}
or PDF
\url{http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference_1-7.pdf}
and in decimal, octal and hex at
\url{http://www.stat.auckland.ac.nz/~paul/R/CM/AdobeSym.html}.
\end{References}
\begin{SeeAlso}\relax
\code{demo(plotmath)},
\code{\LinkA{axis}{axis}},
\code{\LinkA{mtext}{mtext}},
\code{\LinkA{text}{text}},
\code{\LinkA{title}{title}},
\code{\LinkA{substitute}{substitute}}
\code{\LinkA{quote}{quote}}, \code{\LinkA{bquote}{bquote}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(graphics)

x <- seq(-4, 4, len = 101)
y <- cbind(sin(x), cos(x))
matplot(x, y, type = "l", xaxt = "n",
        main = expression(paste(plain(sin) * phi, "  and  ",
                                plain(cos) * phi)),
        ylab = expression("sin" * phi, "cos" * phi), # only 1st is taken
        xlab = expression(paste("Phase Angle ", phi)),
        col.main = "blue")
axis(1, at = c(-pi, -pi/2, 0, pi/2, pi),
     labels = expression(-pi, -pi/2, 0, pi/2, pi))

## How to combine "math" and numeric variables :
plot(1:10, type="n", xlab="", ylab="", main = "plot math & numbers")
theta <- 1.23 ; mtext(bquote(hat(theta) == .(theta)))
for(i in 2:9)
    text(i,i+1, substitute(list(xi,eta) == group("(",list(x,y),")"),
                           list(x=i, y=i+1)))
## note that both of these use calls rather than expressions.

plot(1:10, 1:10)
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 = .8)
text(4, 7, expression(bar(x) == sum(frac(x[i], n), i==1, n)))
text(4, 6.4, "expression(bar(x) == sum(frac(x[i], n), i==1, n))",
     cex = .8)
text(8, 5, expression(paste(frac(1, sigma*sqrt(2*pi)), " ",
                            plain(e)^{frac(-(x-mu)^2, 2*sigma^2)})),
     cex = 1.2)
\end{ExampleCode}
\end{Examples}

