Stata 15 help for added_text_options

[G-3] added_text_options -- Options for adding text to twoway graphs


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" ...]

text may contain Unicode characters and SMCL tags to render mathematical symbols, italics, etc.; see [G-4] 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.


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.


text(text_arg) and ttext(text_arg) specify the location and text to be displayed.


yaxis(#) and xaxis(#) specify how #_y and #_x are to be interpreted when there are multiple y, x, or t axis scales; see [G-3] 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-4] schemes intro and [G-3] 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-4] compassdirstyle, but that will just give you synonyms for c, n, ne, ..., nw.

textbox_options specifies the look of the text; see [G-3] textbox_options.


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-3] textbox_options and [G-4] 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.

© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index