-------------------------------------------------------------------------------
help for bidensity
-------------------------------------------------------------------------------

Bivariate kernel density estimation

        bidensity varnameY varnameX [if exp] [in range] [, n(#)
                 kernel(kernelname) xwidth(#) ywidth(#) saving(name) replace
                 nograph scatter[(scatter_options)] contourline_options
                 mname(name)

Description

    bidensity produces bivariate kernel density estimates and graphs the result
    using a contourline plot.  The default kernel is an Epanechnikov.


Options

    n(#) specifies the number of points on the Y- and X-axes at which the
        density estimate is to be evaluated.  The default is min(_N,50).

    kernel(kernelname) specifies which kernel should be used.  The default is
        epanechnikov.  Other options are gaussian, rectangle, triangle, and
        epan2.  These kernels are bivariate products of the univariate kernels
        described in kdensity.

    xwidth(#) specifies the halfwidth of the kernel, the width of the density
        window around each point of varnameX.  If xwidth() is not specified,
        then the "optimal" width is used; see kdensity.

    ywidth(#) specifies the halfwidth of the kernel, the width of the density
        window around each point of varnameY.  If ywidth() is not specified,
        then the "optimal" width is used; see kdensity.

    saving(name) saves the density estimates to name.dta, along with the x and
        y point values at which the density is estimated.  If the file already
        exists, the replace option must be used to overwrite the previous data.
        The density estimates are saved in the variable "_d".

    scatter[(scatter_options)] superimposes a twoway scatter graph of varnameY
        and varnameX on the contourline graph of the density estimates.

    contourline_options are options to modify the contourline graph.

    nograph specifies that the contourline graph should not be drawn.

    mname(name) is a stub name for retaining the Mata matrices containing the
        density estimates ("name_d"), the X axis grid values ("name_x"), and
        the Y axis grid values ("name_y").  If mname is specified, these
        matrices can be seen after the bidensity with the command mata: mata
        describe.

Examples

    . webuse grunfeld, clear

    . gen linv = log(invest)

    . label var linv "Log[Investment]"

    . gen lmkt = log(mvalue)

    . label var lmkt "Log[Mkt value]"
 
    . bidensity linv lmkt

    . bidensity linv lmkt, n(100)

    . bidensity linv lmkt, xw(.5) yw(.5)

    . bidensity linv lmkt, scatter levels(10)

    . bidensity linv lmkt, saving(biden) replace

    . bidensity linv lmkt, mname(bid)
    . mata: mata describe

Authors

    John Luke Gallup, Portland State University, USA
    jlgallup@pdx.edu

    Christopher F. Baum, Boston College, USA{break} baum@bc.edu Also see {p 4