help added_text_options
-------------------------------------------------------------------------------
Title
[G] added_text_options -- Options for adding text to twoway graphs
Syntax
added_text_options description
---------------------------------------------------------------------
text(text_arg) add text at specified y x
ttext(text_arg) add text at specified y t
---------------------------------------------------------------------
The above options are merged-implicit; see repeated options.
where text_arg is
loc_and_text [loc_and_text ...] [, textoptions]
and where loc_and_text is
#_y #_x "text" ["text" ...]
textoptions description
---------------------------------------------------------------------
yaxis(#) how to interpret #_y
xaxis(#) how to interpret #_x
placement(compassdirstyle) where to locate relative to #_y #_x
textbox_options look of text
---------------------------------------------------------------------
placement() is also a textbox option, but ignore the description of
placement() found there in favor of the one below.
Description
text() adds the specified text to the specified location in the plot
region.
ttext() is an extension to text(), accepting a date in place of #_x when
the time axis has a time format; see datelist.
Options
text(text_arg) and ttext(text_arg) specify the location and text to be
displayed.
Suboptions
yaxis(#) and xaxis(#) specify how #_y and #_x are to be interpreted when
there are multiple y, x, or t axis scales; see [G]
axis_choice_options.
In the usual case, there is one y axis and one x axis, so options
yaxis() and xaxis() are not specified. #_y is specified in units of
the y scale and #_x in units of the x scale.
In the multiple-axis case, specify yaxis(#) and/or xaxis(#) to
specify which units you wish to use. yaxis(1) and xaxis(1) are the
defaults.
placement(compassdirstyle) specifies where the textbox is to be displayed
relative to #_y #_x. The default is usually placement(center). The
default is controlled both by the scheme and by the textbox_option
tstyle(textboxstyle); see [G] schemes intro and [G] textbox_options.
The available choices are
compassdirstyle location of text
------------------------------------------------------------------
c centered on the point, vertically and
horizontally
n above the point, centered
ne above and to the right of the point
e right of the point, vertically centered
se below and to the right of the point
s below point, centered
sw below and to the left of the point
w left of the point, vertically centered
nw above and to the left of the point
------------------------------------------------------------------
north northwest northeast
west X east X
south southwest southeast
You can see [G] compassdirstyle, but that will just give you synonyms
for c, n, ne, ..., nw.
textbox_options specifies the look of the text; see [G] textbox_options.
Remarks
Remarks are presented under the following headings:
Typical use
Advanced use
Use of the textbox option width()
Typical use
text() is used for placing annotations on graphs. One example is the
labeling of outliers. For instance, type
. sysuse auto
. twoway qfitci mpg weight, stdf || scatter mpg weight
(graph omitted)
There are four outliers. First, we find the outliers by typing
. quietly regress mpg weight
. predict hat
. predict s, stdf
. generate upper = hat + 1.96*s
. list make mpg weight if mpg>upper
+----------------------------+
| make mpg weight |
|----------------------------|
13. | Cad. Seville 21 4,290 |
42. | Plym. Arrow 28 3,260 |
57. | Datsun 210 35 2,020 |
66. | Subaru 35 2,050 |
71. | VW Diesel 41 2,040 |
+----------------------------+
Now we can remake the graph and label the outliers:
. twoway qfitci mpg weight, stdf ||
scatter mpg weight, ms(O)
text(41 2040 "VW Diesel", place(e))
text(28 3260 "Plymouth Arrow", place(e))
text(35 2050 "Datsun 210 and Subaru", place(e))
(click to run)
Advanced use
Another common use of text is to add an explanatory box of text inside
the graph:
. sysuse uslifeexp, clear
. twoway line le year ||
fpfit le year ||
, ytitle("Life Expectancy, years")
xlabel(1900 1918 1940(20)2000)
title("Life Expectancy at Birth")
subtitle("U.S., 1900-1999")
note("Source: National Vital Statistics Report, Vol. 50 No. 6")
legend(off)
text( 48.5 1923
"The 1918 Influenza Pandemic was the worst epidemic"
"known in the U.S."
"More citizens died than in all combat deaths of the"
"20th century."
, place(se) box just(left) margin(l+4 t+1 b+1) width(85) )
(click to run)
The only thing to note in the above command is the text() option:
text( 48.5 1923
"The 1918 Influenza Pandemic was the worst epidemic"
"known in the U.S."
"More citizens died than in all combat deaths of the"
"20th century."
, place(se) box just(left) margin(l+4 t+1 b+1) width(85) )
and, in particular, we want to draw your eye to the location of the text
and the suboptions:
text( 48.5 1923
...
, place(se) box just(left) margin(l+4 t+1 b+1) width(85) )
We placed the text at y=48.5, x=1923, place(se), meaning the box will be
placed below and to the right of y=48.5, x=1923.
The other suboptions, box just(left) margin(l+4 t+1 b+1) width(85), are
textbox_options. We specified box to draw a border around the textbox,
and we specified just(left) -- an abbreviation for justification(left) --
so that the text was left-justified inside the box. margin(l+4 t+1 b+1)
made the text in the box look better. On the left we added 4%, and on
the top and bottom we added 1%; see [G] textbox_options and [G]
relativesize. width(85) was specified to solve the problem described
below.
Use of the textbox option width()
Let us look at the results of the above command, omitting the width()
suboption. What you would see on your screen -- or in a printout --
might look virtually identical to the version we just drew, or it might
look like this
(click to run)
or like this:
(click to run)
That is, Stata might make the textbox too narrow or too wide. In the
above illustrations, we have exaggerated the extent of the problem, but
it is common for the box to run a little narrow or a little wide.
Moreover, with respect to this one problem, how the graph appears on your
screen is no guarantee of how it will appear when printed.
This problem arises because Stata uses an approximation formula to
determine the width of the text. This approximation is good for some
fonts and poorer for others.
When the problem arises, use the textbox_option width(relativesize) to
work around it. width() overrides Stata's calculation. In fact, we drew
the two examples above by purposely misstating the width(). In the first
case, we specified width(40), and in the second, width(95).
Getting the width() right is a matter of trial and error. The correct
width will nearly always be between 0 and 100.
Corresponding to width(relativesize), there is also the textbox_option
height(relativesize), but Stata never gets the height incorrect.
Also see
Manual: [G] added_text_options
Help: [G] textbox_options; [U] 11.1.9 datelist
