mtext                package:graphics                R Documentation

Write Text into the Margins of a Plot

Description:

     Text is written in one of the four margins of the current figure
     region or one of the outer margins of the device region.

Usage:

     mtext(text, side = 3, line = 0, outer = FALSE, at = NA,
           adj = NA, padj = NA, cex = NA, col = NA, font = NA, ...)

Arguments:

    text: a character or expression vector specifying the _text_ to be
          written.  Other objects are coerced by 'as.graphicsAnnot'.

    side: on which side of the plot (1=bottom, 2=left, 3=top, 4=right).

    line: on which MARgin line, starting at 0 counting outwards.

   outer: use outer margins if available.

      at: give location in user coordinates.  If 'length(at)==0' (the
          default), the location will be determined by 'adj'.

     adj: adjustment for each string in reading direction.  For strings
          parallel to the axes, 'adj = 0' means left or bottom
          alignment, and 'adj = 1' means right or top alignment.

          If 'adj' is not a finite value (the default), the value of
          'par("las")' determines the adjustment.  For strings plotted
          parallel to the axis the default is to centre the string.

    padj: adjustment for each string perpendicular to the reading
          direction (which is controlled by 'adj').  For strings
          parallel to the axes, 'padj = 0' means right or top
          alignment,  and 'padj = 1' means left or bottom alignment.

          If 'padj' is not a finite value (the default), the value of
          'par("las")' determines the adjustment.  For strings plotted
          perpendicular to the axis the default is to centre the
          string.

     cex: character expansion factor.  'NULL' and 'NA' are equivalent
          to '1.0'.  This is an absolute measure, not scaled by
          'par("cex")' or by setting 'par("mfrow")' or 'par("mfcol")'. 
          Can be a vector.

     col: color to use.  Can be a vector.  'NA' values (the default)
          mean use 'par("col")'.

    font: font for text.  Can be a vector.  'NA' values (the default)
          mean use 'par("font")'.

     ...: Further graphical parameters (see 'par'), including 'family',
          'las' and 'xpd'. (The latter defaults to the figure region
          unless 'outer = TRUE', otherwise the device region.  It can
          only be increased.)

Details:

     The user coordinates in the outer margins always range from zero
     to one, and are not affected by the user coordinates in the figure
     region(s) - R differs here from other implementations of S.

     All of the named arguments can be vectors, and recycling will take
     place to plot as many strings as the longest of the vector
     arguments.

     Note that a vector 'adj' has a different meaning from 'text'. 
     'adj = 0.5' will centre the string, but for 'outer=TRUE' on the
     device region rather than the plot region.

     Parameter 'las' will determine the orientation of the string(s).
     For strings plotted perpendicular to the axis the default
     justification is to place the end of the string nearest the axis
     on the specified line.  (Note that this differs from S, which uses
     'srt' if 'at' is supplied and 'las' if it is not.  Parameter 'srt'
     is ignored in R.)

     Note that if the text is to be plotted perpendicular to the axis,
     'adj' determines the justification of the string _and_ the
     position along the axis unless 'at' is specified.

Side Effects:

     The given text is written onto the current plot.

References:

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

See Also:

     'title', 'text', 'plot', 'par'; 'plotmath' for details on
     mathematical annotation.

Examples:

     plot(1:10, (-4:5)^2, main="Parabola Points", xlab="xlab")
     mtext("10 of them")
     for(s in 1:4)
         mtext(paste("mtext(..., line= -1, {side, col, font} = ",s,
               ", cex = ", (1+s)/2, ")"), line = -1,
               side=s, col=s, font=s, cex= (1+s)/2)
     mtext("mtext(..., line= -2)", line = -2)
     mtext("mtext(..., line= -2, adj = 0)", line = -2, adj =0)
     ##--- log axis :
     plot(1:10, exp(1:10), log='y', main="log='y'", xlab="xlab")
     for(s in 1:4) mtext(paste("mtext(...,side=",s,")"), side=s)

