.-
help for ^binsm^                                                 (STB-37: gr26)
.-

Bin smoothing and summary on scatter plots
------------------------------------------

    ^binsm^ yvar xvar [^if^ exp] [^in^ range] [^, w^idth^(^#^) b^in^(^#^)^
            ^st^arts^(^str^) q^uantile^(^#^) sf(^str^) sonly^ graph_options]


Description
-----------

^binsm^ produces a scatter plot of yvar against xvar with one or more
summaries of yvar for bins of xvar. The smoothing or summary function
^sf^ is by default just the mean, but in general may be any
space-separated list of functions acceptable to ^egen^ that have syntax
of the form

^egen^ newvar = ^mean(^yvar^), by(^binned_version_of_xvar^)^

^count^, ^iqr^, ^max^, ^median^, ^min^, ^pctile^, ^sd^ and ^sum^ are all
legitimate, as is any similar user-written function. Note that ^p^#,
where # can be any integer from 1 to 99, is interpreted as a call to
^pctile^ function of ^egen^ with option ^p(^#^)^. The syntax ^sf(pctile)^
^p(^#^)^ is not permitted. ^sf(pctile)^ is equivalent to ^sf(median)^.


Options
-------

^width(^#^)^ means that xvar is to be rounded in bins of ^width^ #
    before calculating a summary for values that round to the same
    value. The default is 1, which would mean that bins are centered on
    multiples of 1 plus 0.5.

^bin(^#^)^ means that the range of xvar is to be divided into # bins of
   equal width. This overrides any setting of ^width^.

^starts(^str^)^ means that bins start at the values specified. If just
    one value is given, that is the first start and all bins have a
    ^width^ as specified. If two or more values are given, they define
    the starts of all the bins and ^width^ is ignored. However, if the
    lowest start is greater than the minimum value of xvar, that minimum
    will be used to start the lowest bin. ^starts^ overrides any setting
    of ^bin^. ^starts^ must be in increasing order, but may be separated
    by spaces or commas.

^quantile(^#^)^ means that bins have as far as possible equal
    frequencies as determined by # quantiles of xvar. For example ^q(4)^
    uses the quartiles of xvar to define the bins. This overrides any
    setting of ^bin^ or ^width^. # must not exceed 20.

^sf(^string^)^ defines the smoothing function.  The default is the mean, but
    ^count^, ^iqr^, ^max^, ^median^, ^min^, ^p^#, ^sd^, and ^sum^, and any similar user-
    written function may be used.

^sonly^ means that only summaries are to be plotted and that the data
    for yvar are to be suppressed. This may be useful if the numerical
    range (and possibly the units) of the summaries differ markedly from
    that of yvar or if the data set is very large.

graph_options are options allowed with ^graph, twoway^. The default
    values include

    ^xla yla c(.J) sy(oi) sort gap(6)^

    where ^c(J)^ and ^sy(i)^ are repeated for each summary;

    ^l1title^ describes yvar;

    ^b2title^ describes xvar.

Note especially that a sensible y-axis title is the responsibility of
the user.


Examples
--------

    . ^binsm logl logw, w(0.1)^
    . ^binsm logl logw, w(0.1) st(2.15)^
    . ^binsm logl logw, w(0.1) sf(median mean)^
    . ^binsm logl logw, w(0.1) sf(min p25 median p75 max)^
    . ^binsm logl logw, w(0.1) sf(sd iqr) sonly^
    . ^binsm logl logw, q(4)^


Author
------

         Nicholas J. Cox
         University of Durham, U.K.
         n.j.cox@@durham.ac.uk

Also see
--------

    STB:  STB-37 gr26
On-line:  help for @graph@, @egen@, @_pctile@