title                package:graphics                R Documentation

Plot Annotation

Description:

     This function can be used to add labels to a plot.  Its first four
     principal arguments can also be used as arguments in most
     high-level plotting functions.  They must be of type 'character'
     or 'expression'. In the latter case, quite a bit of mathematical
     notation is available such as sub- and superscripts, greek
     letters, fractions, etc: see plotmath

Usage:

     title(main = NULL, sub = NULL, xlab = NULL, ylab = NULL,
           line = NA, outer = FALSE, ...)

Arguments:

    main: The main title (on top) using font and size (character
          expansion) 'par("font.main")' and color 'par("col.main")'.

     sub: Sub-title (at bottom) using font and size 'par("font.sub")'
          and color 'par("col.sub")'.

    xlab: X axis label using font and character expansion
          'par("font.lab")' and color 'par("col.lab")'.

    ylab: Y axis label, same font attributes as 'xlab'.

    line: specifying a value for 'line' overrides the default placement
          of labels, and places them this many lines outwards from the
          plot edge.

   outer: a logical value.  If 'TRUE', the titles are placed in the
          outer margins of the plot.

     ...: further graphical parameters from 'par'.  Use e.g.,
          'col.main' or 'cex.sub' instead of just 'col' or 'cex'. 
          'adj' controls the justification of the titles. 'xpd' can be
          used to set the clipping region: this defaults to the figure
          region unless 'outer = TRUE', otherwise the device region and
          can only be increased.  'mgp' controls the default placing of
          the axis titles. 

Details:

     The labels passed to 'title' can be character strings or language
     objects (names, calls or expressions), or a list containing the
     string to be plotted, and a selection of the optional modifying
     graphical parameters 'cex=', 'col=' and 'font='.  Other objects
     will be coerced by 'as.graphicsAnnot'. 

     The position of 'main' defaults to being vertically centered in
     (outer) margin 3 and justified horizontally according to
     'par("adj")' on the plot region (device region for 'outer=TRUE').

     The positions of 'xlab', 'ylab' and 'sub' are 'line' (default for
     'xlab' and 'ylab' being 'par("mgp")[1]' and increased by '1' for
     'sub') lines (of height 'par("mex")') into the appropriate margin,
     justified in the text direction according to 'par("adj")' on the
     plot/device region.

References:

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

See Also:

     'mtext', 'text'; 'plotmath' for details on mathematical
     annotation.

Examples:

     plot(cars, main = "") # here, could use main directly
     title(main = "Stopping Distance versus Speed")

     plot(cars, main = "")
     title(main = list("Stopping Distance versus Speed", cex=1.5,
                       col="red", font=3))

     ## Specifying "..." :
     plot(1, col.axis = "sky blue", col.lab = "thistle")
     title("Main Title", sub = "sub title",
           cex.main = 2,   font.main= 4, col.main= "blue",
           cex.sub = 0.75, font.sub = 3, col.sub = "red")

     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))
     abline(h = 0, v = pi/2 * c(-1,1), lty = 2, lwd = .1, col = "gray70")

