-------------------------------------------------------------------------------
help for splitvallabels
-------------------------------------------------------------------------------


Split up value labels for multi-line graph labelling


        splitvallabels varname [if exp] [in range] [, length(#)
                 local(localname) nobreak vals(numlist) recode ]


Description

splitvallabels splits the value labels for a variable into multiple chunks, and
returns those chunks in a form appropriate for specification as part of a graph
command.

When the labels associated with axis labels are very long, these labels can
overlap each other in the graph.  This command breaks up these long labels and
packages them in a format appropriate for specification as part of a xlabel()
or relabel() option.  This will create multi-line labels on the graph.


Options

length() specifies maximum length of each "chunk" of labels--that is, the
    maximum width of the resulting multi-line labels.  The default is 15.

local() specifies the name of a local in the caller's namespace for the result.
    Note that the result is also returned in r(relabel).

nobreak specifies that words longer than length() not be broken.

vals() specifies the values of varname that are to be included.  By default all
    values are included.

recode specifies that the values 1, 2, 3, etc. be used to map the labels. This
    is useful if the labels are to be used with graph bar since graph bar
    always uses values 1, 2, 3, etc. to address the over() groups.


Examples

        . sysuse auto
        (1978 Automobile Data)
        
        . label define rep78 1 "Very low rating in 1978" ///
        >      2 "Mediocre - Low Rating in 1978" ///
        >      3 "Medium Rating in 1978" ///
        >      4 "Not bad rating in 1978, considering" ///
        >      5 "Excellent in 1978--the best of the year!"
        
        . label values rep78 rep78
        
        . splitvallabels rep78 , length(11)
        
        . graph bar mpg , over(rep78, relabel(`r(relabel)') )
        
        . splitvallabels rep78 , length(11) vals(1 3 4)
        
        . graph twoway scatter mpg rep78 , xlabel(`r(relabel)')
        
        . splitvallabels rep78 if rep78>=3, length(11) recode
        
        . graph bar mpg if rep78>=3, over(rep78, relabel(`r(relabel)') )
        

splitvallabels may also be used to overcome the problem of quotes in value
labels:

        . sysuse auto, clear
        (1978 Automobile Data)
        
        . label define rep78 1 "Low" 2 "Mediocre" 3 "Medium" ///
        >      4 `"Not "bad""' 5 "Excellent"
        
        . label values rep78 rep78
        
        . graph bar mpg , over(rep78)
        invalid syntax
        r(198);
        
        . splitvallabels rep78
        
        . label values rep78
        
        . graph bar mpg , over(rep78, relabel(`r(relabel)'))
        

Saved Results

splitvallabels saves in r(relabel) a string that may be used for graph option
specification.


Authors

    Nick Winter
    Cornell University
    nw53@cornell.edu

    Ben Jann
    ETH Zurich
    jann@soz.gess.ethz.ch