.- help for ^tpvar^ .-
Turning-point variable for labelling data points on scatter plots -----------------------------------------------------------------
^tpvar^ varname [^if^ exp] [^in^ range] [, ^g^enerate^(^newvar^) a^bove^(^#^) b^elow^(^#^)^ ]
Description -----------
^tpvar^ generates a variable for use in labelling data points on a scatter plot with appropriate text that appears near point symbols.
Given the current sort order, ^tpvar^ identifies observations in which the value of varname is either above both previous and following values or below both previous and following values. These are local maxima and minima, or turning points. A new variable newvar is generated for these turning points, which takes values of
varname + ^above^ * range of varname
and
varname - ^below^ * range of varname
for maxima and minima respectively. These values of newvar will often be good places to put text, just above and just below point symbols for varname.
Options -------
^generate(^newvar^)^ specifies newvar as the name for the new variable. newvar defaults to ^_^varname, where varname is trimmed to 7 characters if necessary, so long as ^_^varname does not already exist.
^above(^#^)^ and ^below(^#^)^ tune the differences between varname and newvar at turning points. ^above(0.016)^ and ^below(0.034)^ are default values. These are fractions of the range of varname (taking account of any ^if^ or ^in^ restrictions). The user may wish to change these, for example, if ^ylabel^ or ^yscale^ is used to change the vertical range greatly or if ^set textsize^ is used to change the textsize. The way Stata places text relative to a baseline means that ^below^ will normally be greater than ^above^.
Examples --------
1. All the peaks and troughs labelled:
. ^sort year^ . ^tpvar srunoff^ . ^graph srunoff _srunoff year, sy(i[year]) c(l.)^
2. Labelling outliers:
. ^graph weight displ^
This shows two outliers we want to label.
. ^sort displ^ . ^tpvar weight^ . ^gra weight _weight displ, sy(o[make])^
The outliers have ^make^ abbreviating to ^"Chev. Ch"^ and ^"Buick Op"^.
So we construct a text variable with just those names:
. ^gen str1 Make = ""^ . ^replace Make = make if substr(make,1,8) == "Chev. Ch"^ . ^replace Make = make if substr(make,1,8) == "Buick Op"^
. ^gra weight _weight displ, sy(o[Make])^
For a more presentable graph, we will increase ^below^, show ^Make^ in full, and fix top and left titles:
. ^tpvar weight, b(0.04) g(Weight)^ . ^gra weight Weight displ, sy(o[Make]) trim(18) t1(" ") yla xla^ ^l2("Weight (lb.)")^
Author ------ Nicholas J. Cox, University of Durham, U.K. n.j.cox@@durham.ac.uk