\Header{axis}{Add an Axis to a Plot}
\keyword{aplot}{axis}
\begin{Description}\relax
Adds an axis to the current plot, allowing the
specification of the side, position, labels, and other options.\end{Description}
\begin{Usage}
\begin{verbatim}
axis(side, at = NULL, labels = TRUE, tick = TRUE, line = NA,
     pos = NA, outer = FALSE, font = NA, vfont = NULL,
     lty = "solid", lwd = 1, col = NULL, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{side}] an integer specifying which side of the plot the axis is
to be drawn on.  The axis is placed as follows: 1=below,
2=left, 3=above and 4=right.
\item[\code{at}] the points at which tick-marks are to be drawn.  Non-finite
(infinite, \code{NaN} or \code{NA}) values are omitted.  By default,
when \code{NULL}, tickmark locations are computed, see Details below.
\item[\code{labels}] this can either be a logical value specifying whether
(numerical) annotations are to be made at the tickmarks, or a vector
of character strings to be placed at the tickpoints.
\item[\code{tick}] a logical value specifying whether tickmarks should be
drawn
\item[\code{line}] the number of lines into the margin which the axis will
be drawn.  This overrides the value of the graphical parameter
\code{mgp[3]}.  The relative placing of tickmarks and tick labels
is unchanged.
\item[\code{pos}] the coordinate at which the axis line is to be drawn.
this overrides the value of both \code{line} and \code{mgp[3]}.
\item[\code{outer}] a logical value indicating whether the axis should be
drawn in the outer plot margin, rather than the standard plot
margin.
\item[\code{font}] font for text.
\item[\code{vfont}] vector font for text.
\item[\code{lty, lwd}] line type, width for the axis line and the tick marks.
\item[\code{col}] color for the axis line and the tick marks.  The default
\code{NULL} means to use \code{par("fg")}.
\item[\code{...}] other graphical parameters may also be passed as arguments to
this function, e.g., \code{las} for vertical/horizontal label
orientation, or \code{fg} instead of \code{col}, see
\code{\Link{par}} on these.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The axis line is drawn from the lowest to the highest value of
\code{at}, but will be clipped at the plot region. Only ticks which
are drawn from points within the plot region (up to a tolerance for
rounding error) are plotted, but the ticks and their labels may well
extend outside the plot region.

When \code{at = NULL}, pretty tick mark locations are computed internally,
the same \code{\Link{axTicks}(side)} would, from
\code{\Link{par}("usr","lab")}, and \code{\Link{par}("xlog")} (or
\code{ylog} respectively).\end{Details}
\begin{Value}
This function is invoked for its side effect, which is to add an axis
to an already existing plot.\end{Value}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.\end{References}
\begin{SeeAlso}\relax
\code{\Link{axTicks}} returns the axis tick locations
corresponding to \code{at=NULL}; \code{\Link{pretty}} is more flexible
for computing pretty tick coordinates and does \emph{not} depend on
(nor adapt to) the coordinate system in use.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
plot(1:4, rnorm(4), axes=FALSE)
axis(1, 1:4, LETTERS[1:4])
axis(2)
box() #- to make it look "as usual"

plot(1:7, rnorm(7), main = "axis() examples",
     type = "s", xaxt="n", frame = FALSE, col = "red")
axis(1, 1:7, LETTERS[1:7], col.axis = "blue")
# unusual options:
axis(4, col = "violet", col.axis="dark violet",lwd = 2)
axis(3, col = "gold", lty = 2, lwd = 0.5)
\end{ExampleCode}
\end{Examples}

