sm.density {sm} | R Documentation |
Nonparametric density estimation in one, two or three dimensions.
Description
This function creates a density estimate from data in one, two or three
dimensions. In one dimension, an interactive panel can be activated
to control the smoothing parameter, in two dimensions a variety of
graphical displays can be selected, and in three dimensions a contour
surface can be plotted. A number of other features of the construction
of the estimate, and of its display, can be controlled.
Usage
sm.density(x, h, model = "none", weights = rep(1,nobs), ...)
Arguments
x |
a vector, or a matrix with two or three columns, containing the data.
|
h |
a vector of length one, two or three, defining the smoothing parameter.
A normal kernel function is used and h is its standard deviation.
If this parameter is omitted, a normal optimal smoothing parameter is used.
|
model |
This argument applies only with one-dimensional data. Its default value
is "none" . If it is set to "Normal" (or indeed any value other than
"none" ) then a reference band, indicating where a density estimate is
likely to lie when the data are normally distributed, will be superimposed
on any plot.
|
weights |
a vector which allows the kernel functions over the observations to take
different weights when they are averaged to produce a density estimate.
Use of this parameter is incompatible with binning; hence nbins must
then be set to 0 or left at its default value NA .
This argument does not apply with three-dimensional data.
|
... |
other optional parameters are passed to the sm.options function, through
a mechanism which limits their effect only to this call of the function;
those relevant for this function are the following:
- hmult
- a factor which can be used to multiply the normal smoothing parameter
before construction of the density estimate.
- h.weights
- a vector of weights which multiply the smoothing parameter used in the
kernel function at each observation. This argument does not apply with
three-dimensional data.
- band
- a logical value which controls whether the reference band appears on the plot.
Its default value is
TRUE .
This argument applies only with one-dimensional data.
- add
- a logical value which controls whether the density estimate is added to
the current plot. Its default value is
FALSE , which creates a new plot.
This argument applies only with one-dimensional data.
- lty
- the line type used to plot the density estimate. This argument applies only
with one-dimensional data.
- display
- This argument applies only with one- or two-dimensional data. The setting
"none" will prevent any graphical output from being produced. In one
dimensions, the default setting "estimate" will produce the density
estimate, while the setting "se" will in addition produce a variability
band, showing the variability, but not the bias, of the estimate. In two
dimensions, the default setting "persp" will produce a perspective plot
of the density estimate, while the settings "slice" and "image" will
produce slice (contour) or image plots.
- props
- a vector defining the proportions of the data to be included within each
contour in a slice plot, from two-dimensional data, or a contour surface
plot, from three-dimensional data. In the three-dimensional case only
the first element of the vector will be used. This argument does not apply
to one-dimensional data.
- xlab
- the label attached to the x-axis.
- ylab
- the label attached to the y-axis.
- zlab
- the label attached to the z-axis (three-dimensional plots only)
- xlim
- the range of the horizontal axis of the plot. This argument does not apply
with three-dimensional data.
- ylim
- the range of the vertical axis of the plot. This argument does not apply
with three-dimensional data.
- yht
- the upper limit of the vertical axis in a plot of a one-dimensional density
estimate. The lower limit is always set to 0. This argument does not apply
with two- or three-dimensional data.
- nbins
- The number of bins used in one-dimensional binning operations;
in two-dimensional cases,
nbins refers to the number of bins
formed along each axis. Bins with 0 observed frequencies are ignored.
If nbins=0 , binning is not performed; if nbins=NA (default),
binning is switched on when the number of observations divided by
the number of dimensions exceeds 500.
- ngrid
- the number of points in the regular grid used to plot the estimate.
For two- and three-dimensional data,
ngrid refers to the number of points
along the axis in each dimension.
Default: 100, 50 and 20 for 1-, 2- and 3-dimensional data, respectively.
- eval.points
- the points at which the density estimate should be evaluated, for the
values returned in the result of the function. This should be a vector
for one-dimensional data and a two-column matrix for two-dimensional data.
This argument does not apply with three-dimensional data.
- panel
- a logical value which controls the appearance of a panel display, in the
case of one- or two-dimensional data. The panel can be used to alter the
value of the smoothing parameter. For one-dimensional data it can also
launch an animation, and superimpose a normal reference band. This argument
does not apply with three-dimensional data.
- positive
- a logical value which indicates whether the data should be assumed to take
positive values only. When this argument is set to
TRUE , a log
transformation
is applied to the data before construction of a density estimate. The result
is transformed back to the original scale. This argument does not apply with
three-dimensional data.
- delta
- a value which will be added to the data before they are log transformed in
the procedure to handle positive data. The value of
delta is used only
when positive takes the value TRUE . The default value is
the smallest value
observed in each dimension. This argument does not apply with
three-dimensional data.
- theta
- the horizontal rotation (in radians) of the contour plot of the density
estimate from three-dimensional data. The default value is pi/4.
- phi
- the vertical rotation (in radians) of the contour plot of the density
estimate from three-dimensional data. The default value is pi/4.
|
Details
see Chapters 1, 2 and 6 of the reference below.
The code for drawing contours of a three-dimensional density estimate has
been amended from an original function written by Stuart Young.
Value
a list containing the values of the density estimate at the evaluation points,
the standard error of the estimate, the upper and lower ends of a variability
band, the smoothing parameter, the smoothing parameter weights and the kernel
weights. Less information is supplied when the smoothing parameter weights
or kernel weights are not all 1, or when positive
is set to TRUE
.
Side Effects
a plot on the current graphical device is produced, unless display="none"
.
References
Bowman, A.W. and Azzalini, A. (1997).
Applied Smoothing Techniques for Data Analysis:
the Kernel Approach with S-Plus Illustrations.
Oxford University Press, Oxford.
See Also
hnorm
, hsj
, hcv
, nise
, nmise
, sm
, sm.sphere
, sm.regression
,
sm.options
Examples
# A one-dimensional example
y <- rnorm(50)
sm.density(y, model = "Normal")
# A two-dimensional example
y <- cbind(rnorm(50), rnorm(50))
sm.density(y, display = "image")
# A three-dimensional example
y <- cbind(rnorm(50), rnorm(50), rnorm(50))
sm.density(y)
[Package
sm version 2.0-13
Index]