| % File src/library/graphics/man/axis.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{axis} |
| \alias{axis} |
| \title{Add an Axis to a Plot} |
| \description{Adds an axis to the current plot, allowing the |
| specification of the side, position, labels, and other options. |
| } |
| \usage{ |
| axis(side, at = NULL, labels = TRUE, tick = TRUE, line = NA, |
| pos = NA, outer = FALSE, font = NA, lty = "solid", |
| lwd = 1, lwd.ticks = lwd, col = NULL, col.ticks = NULL, |
| hadj = NA, padj = NA, gap.axis = NA, \dots) |
| } |
| \arguments{ |
| \item{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{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 |
| \sQuote{Details} below.} |
| \item{labels}{this can either be a logical value specifying whether |
| (numerical) annotations are to be made at the tickmarks, or a |
| character or expression vector of labels to be placed at the |
| tickpoints. (Other objects are coerced by \code{\link{as.graphicsAnnot}}.) |
| If this is not logical, \code{at} should also be supplied and of the |
| same length. If \code{labels} is of length zero after coercion, |
| it has the same effect as supplying \code{TRUE}.} |
| \item{tick}{a logical value specifying whether tickmarks and an axis line |
| should be drawn.} |
| \item{line}{the number of lines into the margin at which the axis line |
| will be drawn, if not \code{NA}.} |
| \item{pos}{the coordinate at which the axis line is to be drawn: |
| if not \code{NA} this overrides the value of \code{line}.} |
| \item{outer}{a logical value indicating whether the axis should be |
| drawn in the outer plot margin, rather than the standard plot |
| margin.} |
| \item{font}{font for text. Defaults to \code{par("font")}.} |
| \item{lty}{line type for both the axis line and the tick marks.} |
| \item{lwd, lwd.ticks}{line widths for the axis line and the tick |
| marks. Zero or negative values will suppress the line or ticks.} |
| \item{col, col.ticks}{colors for the axis line and the tick marks |
| respectively. \code{col = NULL} means to use \code{par("fg")}, |
| possibly specified inline, and \code{col.ticks = NULL} means to use |
| whatever color \code{col} resolved to.} |
| \item{hadj}{adjustment (see \code{\link{par}("adj")}) for all labels |
| \emph{parallel} (\sQuote{horizontal}) to the reading direction. If |
| this is not a finite value, the default is used (centring for |
| strings parallel to the axis, justification of the end nearest the |
| axis otherwise).} |
| \item{padj}{adjustment for each tick label \emph{perpendicular} to the |
| reading direction. For labels parallel to the axes, \code{padj = 0} |
| means right or top alignment, and \code{padj = 1} means left or bottom |
| alignment. This can be a vector given a value for each string, and |
| will be recycled as necessary. |
| |
| If \code{padj} is not a finite value (the default), the value of |
| \code{par("las")} determines the adjustment. For strings plotted |
| perpendicular to the axis the default is to centre the string.} |
| \item{gap.axis}{an optional (typically non-negative) numeric factor to |
| be multiplied with the size of an \sQuote{m} to determine the |
| minimal gap between labels that are drawn, see \sQuote{Details}. |
| The default, \code{NA}, corresponds to \code{1} for tick labels drawn |
| \emph{parallel} to the axis and \code{0.25} otherwise, i.e., the |
| default is equivalent to \preformatted{ perpendicular <- function(side, las) { |
| is.x <- (side \%\% 2 == 1) # is horizontal x-axis |
| ( is.x && (las \%in\% 2:3)) || |
| (!is.x && (las \%in\% 1:2)) |
| } |
| gap.axis <- if(perpendicular(side, las)) 0.25 else 1}% end{pre..} |
| |
| \code{gap.axis} may typically be relevant when \code{at = ..} |
| tick-mark positions are specified explicitly. |
| } |
| \item{\dots}{other \link{graphical parameters} may also be passed as |
| arguments to this function, particularly, \code{cex.axis}, \code{col.axis} |
| and \code{font.axis} for axis annotation, i.e. tick labels, \code{mgp} |
| and \code{xaxp} or \code{yaxp} for positioning, \code{tck} or |
| \code{tcl} for tick mark length and direction, \code{las} for |
| vertical/horizontal label orientation, or \code{fg} instead of |
| \code{col}, and \code{xpd} for clipping. See \code{\link{par}} on these. |
| |
| Parameters \code{xaxt} (sides 1 and 3) and \code{yaxt} (sides 2 and |
| 4) control if the axis is plotted at all. |
| |
| Note that \code{lab} will partial match to argument |
| \code{labels} unless the latter is also supplied. (Since the |
| default axes have already been set up by \code{\link{plot.window}}, |
| \code{lab} will not be acted on by \code{axis}.)} |
| } |
| \value{ |
| The numeric locations on the axis scale at which tick marks were drawn |
| when the plot was first drawn (see \sQuote{Details}). |
| |
| This function is usually invoked for its side effect, which is to add |
| an axis to an already existing plot. |
| } |
| \details{ |
| The axis line is drawn from the lowest to the highest value of |
| \code{at}, but will be clipped at the plot region. By default, 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. Use \code{xpd = TRUE} |
| or \code{xpd = NA} to allow axes to extend further. |
| |
| When \code{at = NULL}, pretty tick mark locations are computed internally |
| (the same way \code{\link{axTicks}(side)} would) from |
| \code{\link{par}("xaxp")} or \code{"yaxp"} and |
| \code{\link{par}("xlog")} (or \code{"ylog"}). Note that these |
| locations may change if an on-screen plot is resized (for example, if |
| the \code{plot} argument \code{asp} (see \code{\link{plot.window}}) is set.) |
| |
| If \code{labels} is not specified, the numeric values supplied or |
| calculated for \code{at} are converted to character strings as if they |
| were a numeric vector printed by \code{\link{print.default}(digits = 7)}. |
| |
| The code tries hard not to draw overlapping tick labels, and so will |
| omit labels where they would abut or overlap previously drawn labels. |
| This can result in, for example, every other tick being labelled. |
| The ticks are drawn left to right or bottom to top, and space at |
| least the size of an \sQuote{m}, multiplied by \code{gap.axis}, |
| is left between labels. In previous \R versions, this applied only |
| for labels written \emph{parallel} to the axis direction, hence not |
| for e.g., \code{las = 2}. Using \code{gap.axis = -1} restores that |
| (buggy) previous behaviour (in the perpendicular case). |
| |
| If either \code{line} or \code{pos} is set, they (rather than |
| \code{par("mgp")[3]}) determine the position of the axis line and tick |
| marks, and the tick labels are placed \code{par("mgp")[2]} further |
| lines into (or towards for \code{pos}) the margin. |
| |
| Several of the graphics parameters affect the way axes are drawn. The |
| vertical (for sides 1 and 3) positions of the axis and the tick labels |
| are controlled by \code{mgp[2:3]} and \code{mex}, the size and |
| direction of the ticks is controlled by \code{tck} and \code{tcl} and |
| the appearance of the tick labels by \code{cex.axis}, \code{col.axis} |
| and \code{font.axis} with orientation controlled by \code{las} (but |
| not \code{srt}, unlike S which uses \code{srt} if \code{at} is |
| supplied and \code{las} if it is not). Note that \code{adj} is not |
| supported and labels are always centered. See \code{\link{par}} for details. |
| } |
| \seealso{ |
| \code{\link{Axis}} for a generic interface. |
| |
| \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. |
| |
| Several graphics parameters affecting the appearance are documented |
| in \code{\link{par}}. |
| } |
| \references{ |
| Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) |
| \emph{The New S Language}. |
| Wadsworth & Brooks/Cole. |
| } |
| \examples{ |
| require(stats) # for rnorm |
| 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) |
| |
| # one way to have a custom x axis |
| plot(1:10, xaxt = "n") |
| axis(1, xaxp = c(2, 9, 7)) |
| |
| ## Changing default gap between labels: |
| plot(0:100, type="n", axes=FALSE, ann=FALSE) |
| title(quote("axis(1, .., gap.axis = f)," ~~ f >= 0)) |
| axis(2, at = 5*(0:20), las = 1, gap.axis = 1/4) |
| gaps <- c(4, 2, 1, 1/2, 1/4, 0.1, 0) |
| chG <- paste0(ifelse(gaps == 1, "default: ", ""), |
| "gap.axis=", formatC(gaps)) |
| jj <- seq_along(gaps) |
| linG <- -2.5*(jj-1) |
| for(j in jj) { |
| isD <- gaps[j] == 1 # is default |
| axis (1, at=5*(0:20), gap.axis = gaps[j], padj=-1, line = linG[j], |
| col.axis = if(isD) "forest green" else 1, font.axis= 1+isD) |
| } |
| mtext(chG, side=1, padj=-1, line = linG -1/2, cex=3/4, |
| col = ifelse(gaps == 1, "forest green", "blue3")) |
| ## now shrink the window (in x- and y-direction) and observe the axis labels drawn |
| } |
| \keyword{aplot} |