Scatter plot with keys in user-chosen positions -----------------------------------------------
^keyplot^ varlist [^if^ exp] [^in^ range] [weight] [ ^,^ { ^varlbl^ | ^k^eys^(^key list^)^ } ^sep(^separator^)^ ^row^pos^(^row list^) col^pos^(^column list^) ktf^ont^(^#1 #2^)^ ^t1^title^(^text^) t1pos(^row col^) t1font(^#1 #2^)^ ^t2^title^(^text^) t2pos(^row col^) t2font(^#1 #2^)^ ^t1pen(^#^) t2pen(^#^)^ graph_options ]
Description -----------
^keyplot^ produces a standard scatter plot with between one and ten y variables and one x variable, except that it attempts a more flexible approach to placing symbol keys for the y variables, either in the top title space or elsewhere.
Remarks -------
When 5 or more y variables are given, ^graph, twoway^ will supply keys in the top title space (that accessible through ^t1( )^ and ^t2( )^) only for the first four variables.
^keyplot^ will provide keys for up to 10 y variables.
With ^keyplot^ by default variable names are given as keys for between 2 and 10 y variables. The variable label would often be too long to fit in the space available. If it is known or presumed to be short enough the ^varlbl^ option should be specified. Otherwise the alternative is to use the ^keys( )^ option to provide text as desired.
By default keys are placed in the top title space. The row and column positions of the symbols can be controlled by using ^rowpos( )^ and ^colpos( )^.
The ^t1title( )^ and ^t2title( )^ options of ^graph, twoway^ are in effect replaced by more general options allowing placement of left-to-right text anywhere on the graph. There is no default position and the position of such text must be specified by using ^t1pos( )^ and/or ^t2pos( )^.
For understanding placement of symbols and text, it helps to know that the graph space is defined by 23063 rows and 32000 columns with origin at top left. See help for @gph@. The default positions for the keys can be seen by following ^keyplot^ issued without ^rowpos( )^ or ^colpos( )^ by ^return list^.
The defaults for ^keyplot^ were chosen with ^textsize^ set at 100 and may not work well with different ^textsize^. ^textsize^ does not affect the font used either for the key text, which may be controlled separately using ^ktfont( )^, or for the ^t1title^ or the ^t2title^, which may be controlled separately using ^t1font( )^ or ^t2font( )^.
Options -------
^varlbl^ specifies use of variable labels for keys. If ^varlbl^ is specified and no variable label exists, the variable name will be used instead.
^keys(^key list^)^ supplies a list of keys, one for each y variable in turn. ^keys( )^ that are single `words' may be separated by spaces, except that an alternative separator can be specified by using ^sep( )^. ^sep(^separator^)^ specifies an alternative separator for interpreting the keys provided by the ^keys( )^ option. For example, if any key consists of two or more words, a symbol not otherwise used should be specified as separator.
^rowpos(^row list^)^ specifies row positions for the y variable symbols. The row list can be a numlist as explained in the help for @numlist@. One position should be specified for each y variable, except that any single position specified is repeated for each y variable. ^colpos(^col list^)^ specifies column positions for the y variable symbols. The column list can be a numlist as explained in the help for @numlist@. One position should be specified for each y variable, except that any single position specified is repeated for each y variable.
^ktfont(^#1 #2^)^ specifies two numbers controlling the row and column size of the font used for the key text. Default 570 290. See help for @gph@, but note that the choice of 923 444 recommended there is rather large for many tastes.
^t1title(^text^)^ places left-to-right horizontal text starting at the position > specified by ^t1pos( )^. Note that ^t1pos( )^ must be specified. ^t2title(^text^)^ places left-to-right horizontal text starting at the position > specified by ^t2pos( )^. Note that ^t2pos( )^ must be specified. If the keys are placed in the default position at the top of the graph, then it may still be desired to add text elsewhere on the graph. If the keys are placed elsewhere using ^rowpos( )^ or ^colpos( )^, then it may be desired to add text at the top of the graph. Thus ^t1title( )^ and ^t2title( )^ generalise the ^graph^ options of the same name.
^t1pos(^row col^)^ specifies a row and column position for ^t1title( )^.
^t2pos(^row col^)^ specifies a row and column position for ^t2title( )^.
Each is a required option whenever the associated title is specified. See above. ^t1font(^#1 #2^)^ and ^t2font(^#1 #2^)^ each specify two numbers controlling the row and column size of the font used for the ^t1title^ or ^t2title^. Default 570 290. See help for @gph@, but note that the choice of 923 444 recommended there is rather large for many tastes.
^t1pen(^#^)^ and ^t2pen(^#^)^ control the pens for the ^t1title( )^ and ^t2title(^ ^)^. Default 1. graph_options are options allowed with ^graph, twoway^, except that
^by( )^ is not allowed. ^t1title( )^ and ^t2title( )^ options do not behave in the same way as with ^graph^. See above. ^symbol(i)^, ^symbol([^varname^])^ and ^symbol([_n])^ are not supported. Note that with, for example, the maximum of 10 y variables some symbols must be repeated. The onus is on the user to differentiate them by colour and/or size.
Examples --------
. ^separate mpg, by(rep78)^ . ^keyplot mpg1-mpg5 weight, varlbl l2(Miles per gallon)^ . ^keyplot mpg1-mpg5 weight, k(1 2 3 4 5) l2(Miles per gallon)^ . ^keyplot mpg1-mpg5 weight, k(Very poor\Poor\Fair\Good\Very good)^ ^sep(\) l2(Miles per gallon)^ . ^keyplot mpg1-mpg5 weight, k(1 2 3 4 5) l2(Miles per gallon)^ ^row(2000(2000)10000) col(26000)^ . ^keyplot mpg1-mpg5 weight, k(1 2 3 4 5) l2(Miles per gallon)^ ^row(2000(2000)10000) col(26000) t1(Report record) t1pos(5000 25500)^
. ^use census^ . ^gen popm = pop / 1e6^ . ^label var popm "Population in millions"^ . ^keyplot death marriage divorce popm, varlbl^ ^row(17000 18000 19000) col(22000) xla(0.5 1 2 5 10 20) xlog^ ^yla(1000 2000 5000 10000 20000 50000 100000 200000) ylog^ ^t1(Which state is the outlier?) t1pos(1000 4000)^ ^t1font(800 400)^
Time series: . ^keyplot gdpgrUK gdpgrUSA gdpgrJap gdpgrGer gdpgrFr year,^ ^c(lllll) key(UK USA Japan Germany France)^
Author ------
Nicholas J. Cox, University of Durham, U.K. n.j.cox@@durham.ac.uk Acknowledgments ---------------
Ronan Conroy, Ian Evans and Zhiqiang Wang made very helpful comments.
Also see --------
On-line: help for @graph@, @gph@, @numlist@