Text in the Margins of a Plot

DESCRIPTION:
Adds text in the margins of the current plot. Putting text in the outer margin can be used to give a title to a page containing a number of plots.

USAGE:
mtext(text, side=3, line=0, outer=F, at=<<see below>>)

REQUIRED ARGUMENTS:
text:
vector of text strings to be plotted. This should have length 1 unless at is specified.

OPTIONAL ARGUMENTS:
side:
integer indicating the side on which text is to be placed. 1 is the bottom, 2 is the left, 3 is the top and 4 is the right.
line:
distance of text from the plot (measured out from the plot in units of mex sized character heights). If line=0 and outer=F, the text is printed just outside the plot area; positive values put the text farther from the plot, negative values closer.
outer:
logical flag: should plotting be done in the outer margin?
at:
vector of positions at which text is to be plotted. If side is 1 or 3, at will represent x-coordinates. If side is 2 or 4, at will represent y-coordinates. By default, the text is centered on the axis. at can be used for constructing specialized axis labels, etc.

SIDE EFFECTS:
Adds text to the margins of the current plot if outer is FALSE. When outer is TRUE, the text is added to the outer margin.

DETAILS:
The default values of the graphical parameter mar allow characters to be placed at values of line less than or equal to 4 on the bottom, 3 on the left and top, and 1 on the right.

For multiple lines of text (there is at least one "\n" in the string), the first line of text is at line and subsequent lines are farther from the plot for sides 1 and 4 but nearer the plot area for sides 2 and 3.

If the at argument is not supplied, then mtext rotates the text to be parallel to the axis specified by the side argument. Otherwise, it uses the current value of the srt graphical parameter to determine the angle at which to rotate the text. If the at argument is not supplied, then mtext uses the current value of the adj graphical parameter to determine where along the axis to place the text: adj=0.5 centers the text at the center of the axis, adj=0 left justifies it to the left edge of the axis, and adj=1 right justifies it to the right edge of the axis. Otherwise, adj it used (as in the text function) to indicate the proportion of the text to be placed to the left of the position given by the at argument. (The current value of the srt and adj parameters may be given as arguments to mtext or as arguments to par.)


SEE ALSO:
text , par , plot , title .

EXAMPLES:
        # putting a title on a page of plots
par(oma=c(1, 1, 1, 1), mfrow=c(2, 2))
 # some plots ...
 mtext(outer=T, "The title for this page of plots", side=3)