.-
help for ^keyplot^
.-

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@ 

