| Title: | Nonparametric Kernel Smoothing Methods for Mixed Data Types |
|---|---|
| Description: | Nonparametric (and semiparametric) kernel methods that seamlessly handle a mix of continuous, unordered, and ordered factor data types. We would like to gratefully acknowledge support from the Natural Sciences and Engineering Research Council of Canada (NSERC, <https://www.nserc-crsng.gc.ca/>), the Social Sciences and Humanities Research Council of Canada (SSHRC, <https://sshrc-crsh.canada.ca/en.aspx>), and the Shared Hierarchical Academic Research Computing Network (SHARCNET, <https://sharcnet.ca/>). We would also like to acknowledge the contributions of the GNU GSL authors. In particular, we adapt the GNU GSL B-spline routine gsl_bspline.c adding automated support for quantile knots (in addition to uniform knots), providing missing functionality for derivatives, and for extending the splines beyond their endpoints. |
| Authors: | Jeffrey S. Racine [aut, cre], Tristen Hayfield [aut] |
| Maintainer: | Jeffrey S. Racine <[email protected]> |
| License: | GPL |
| Version: | 0.80-1 |
| Built: | 2026-10-17 22:34:32 UTC |
| Source: | https://github.com/jeffreyracine/r-package-np |
b.star is a function which computes the optimal block length
for the continuous variable data using the method described in
Patton, Politis and White (2009).
b.star(data, Kn = NULL, mmax= NULL, Bmax = NULL, c = NULL, round = FALSE)b.star(data, Kn = NULL, mmax= NULL, Bmax = NULL, c = NULL, round = FALSE)
Time-series data used for automatic block-length selection.
data |
data, an n x k matrix, each column being a data series. |
Tuning constants from Politis and White (2004) and Patton, Politis, and White (2009).
Kn |
See footnote c, page 59, Politis and White (2004). Defaults
to |
mmax |
See Politis and White (2004). Defaults to
|
Bmax |
See Politis and White (2004). Defaults to
|
c |
See Politis and White (2004). Defaults to
|
Control for rounding the selected block lengths.
round |
whether to round the result or not. Defaults to FALSE. |
b.star is a function which computes optimal block lengths for
the stationary and circular bootstraps. This allows the use of
tsboot from the boot package to be fully
automatic by using the output from b.star as an input to the
argument l = in tsboot. See below for an example.
A kx2 matrix of optimal bootstrap block lengths computed from
data for the stationary bootstrap and circular bootstrap (column
1 is for the stationary bootstrap, column 2 the circular).
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Patton, A. and D.N. Politis and H. White (2009), “CORRECTION TO "Automatic block-length selection for the dependent bootstrap" by D. Politis and H. White”, Econometric Reviews 28(4), 372-375.
Politis, D.N. and J.P. Romano (1994), “Limit theorems for weakly dependent Hilbert space valued random variables with applications to the stationary bootstrap”, Statistica Sinica 4, 461-476.
Politis, D.N. and H. White (2004), “Automatic block-length selection for the dependent bootstrap”, Econometric Reviews 23(1), 53-70.
set.seed(12345) # Function to generate an AR(1) series ar.series <- function(phi,epsilon) { n <- length(epsilon) series <- numeric(n) series[1] <- epsilon[1]/(1-phi) for(i in 2:n) { series[i] <- phi*series[i-1] + epsilon[i] } return(series) } yt <- ar.series(0.1,rnorm(10000)) b.star(yt,round=TRUE) yt <- ar.series(0.9,rnorm(10000)) b.star(yt,round=TRUE)set.seed(12345) # Function to generate an AR(1) series ar.series <- function(phi,epsilon) { n <- length(epsilon) series <- numeric(n) series[1] <- epsilon[1]/(1-phi) for(i in 2:n) { series[i] <- phi*series[i-1] + epsilon[i] } return(series) } yt <- ar.series(0.1,rnorm(10000)) b.star(yt,round=TRUE) yt <- ar.series(0.9,rnorm(10000)) b.star(yt,round=TRUE)
Canadian cross-section wage data consisting of a random sample taken from the 1971 Canadian Census Public Use Tapes for male individuals having common education (grade 13). There are 205 observations in total.
data("cps71")data("cps71")
A data frame with 2 columns, and 205 rows.
the first column, of type numeric
the second column, of type integer
Aman Ullah
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
data("cps71", package = "np") if (interactive()) with(cps71, plot(age, logwage, xlab="Age", ylab="log(wage)"))data("cps71", package = "np") if (interactive()) with(cps71, plot(age, logwage, xlab="Age", ylab="log(wage)"))
dimBS returns the number of columns implied by an additive,
generalized local-polynomial, or tensor-product basis specification.
It is a compatibility wrapper around the internal dim_basis()
helper used by np.
dimBS(basis = "additive", kernel = TRUE, degree = NULL, segments = NULL, include = NULL, categories = NULL)dimBS(basis = "additive", kernel = TRUE, degree = NULL, segments = NULL, include = NULL, categories = NULL)
Basis family, continuous-kernel counting mode, polynomial degree, and segment controls.
basis |
basis family. One of |
kernel |
logical indicating whether only the continuous-kernel basis should
be counted. When |
degree |
non-negative integer vector of local-polynomial degrees. |
segments |
positive integer vector giving the number of segments for each continuous predictor. Defaults to one segment per degree entry. |
Optional categorical-component controls used when kernel = FALSE.
include |
non-negative integer vector indicating which categorical
components are included when |
categories |
non-negative integer vector giving category counts for included
categorical components when |
dimBS() is provided for compatibility with crs. In
np, the underlying implementation lives in
dim_basis(), which is used internally for LP basis-dimension
checks and safe NOMAD restart initialization. For kernel=TRUE,
basis="glp", and one segment per continuous predictor, the count is
the number of non-intercept multi-indices satisfying
and
. This unit-segment
rule is the local-polynomial contract; non-unit segment and categorical
augmentation semantics are unchanged. Counts beyond the supported
100,000-term native GLP capacity fail before basis allocation.
A numeric scalar giving the implied basis dimension.
dimBS(basis = "tensor", degree = c(2, 2)) dimBS(basis = "glp", degree = c(3, 1, 0))dimBS(basis = "tensor", degree = c(2, 2)) dimBS(basis = "glp", degree = c(3, 1, 0))
British cross-section data consisting of a random sample taken from the British Family Expenditure Survey for 1995. The households consist of married couples with an employed head-of-household between the ages of 25 and 55 years. There are 1655 household-level observations in total.
data("Engel95")data("Engel95")
A data frame with 10 columns, and 1655 rows.
expenditure share on food, of type numeric
expenditure share on catering, of type numeric
expenditure share on alcohol, of type numeric
expenditure share on fuel, of type numeric
expenditure share on motor, of type numeric
expenditure share on fares, of type numeric
expenditure share on leisure, of type numeric
logarithm of total expenditure, of type numeric
logarithm of total earnings, of type numeric
number of children, of type numeric
Richard Blundell and Dennis Kristensen
Blundell, R. and X. Chen and D. Kristensen (2007), “Semi-Nonparametric IV Estimation of Shape-Invariant Engel Curves,” Econometrica, 75, 1613-1669.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
## Not run: ## Example - compute nonparametric instrumental regression using ## Landweber-Fridman iteration of Fredholm integral equations of the ## first kind. ## We consider an equation with an endogenous regressor (`z') and an ## instrument (`w'). Let y = phi(z) + u where phi(z) is the function of ## interest. Here E(u|z) is not zero hence the conditional mean E(y|z) ## does not coincide with the function of interest, but if there exists ## an instrument w such that E(u|w) = 0, then we can recover the ## function of interest by solving an ill-posed inverse problem. data(Engel95) ## Sort on logexp (the endogenous regressor) for plotting purposes Engel95 <- Engel95[order(Engel95$logexp),] Engel95 <- Engel95[seq_len(min(120, nrow(Engel95))), ] with(Engel95, { model.iv <- npregiv(y=food, z=logexp, w=logwages, method="Landweber-Fridman", iterate.max=3, iterate.diff.tol=1.0e-04) phi <- model.iv$phi ## Compute the non-IV regression (i.e. regress y on z) ghat <- npreg(food~logexp,regtype="ll") ## For the plots, restrict focal attention to the bulk of the data ## (i.e. for the plotting area trim out 1/4 of one percent from each ## tail of y and z) trim <- 0.0025 plot(logexp,food, ylab="Food Budget Share", xlab="log(Total Expenditure)", xlim=quantile(logexp,c(trim,1-trim)), ylim=quantile(food,c(trim,1-trim)), main="Nonparametric Instrumental Kernel Regression", type="p", cex=.5, col="lightgrey") lines(logexp,phi,col="blue",lwd=2,lty=2) lines(logexp,fitted(ghat),col="red",lwd=2,lty=4) legend(quantile(logexp,trim),quantile(food,1-trim), c(expression(paste("Nonparametric IV: ",hat(varphi)(logexp))), "Nonparametric Regression: E(food | logexp)"), lty=c(2,4), col=c("blue","red"), lwd=c(2,2)) }) ## End(Not run)## Not run: ## Example - compute nonparametric instrumental regression using ## Landweber-Fridman iteration of Fredholm integral equations of the ## first kind. ## We consider an equation with an endogenous regressor (`z') and an ## instrument (`w'). Let y = phi(z) + u where phi(z) is the function of ## interest. Here E(u|z) is not zero hence the conditional mean E(y|z) ## does not coincide with the function of interest, but if there exists ## an instrument w such that E(u|w) = 0, then we can recover the ## function of interest by solving an ill-posed inverse problem. data(Engel95) ## Sort on logexp (the endogenous regressor) for plotting purposes Engel95 <- Engel95[order(Engel95$logexp),] Engel95 <- Engel95[seq_len(min(120, nrow(Engel95))), ] with(Engel95, { model.iv <- npregiv(y=food, z=logexp, w=logwages, method="Landweber-Fridman", iterate.max=3, iterate.diff.tol=1.0e-04) phi <- model.iv$phi ## Compute the non-IV regression (i.e. regress y on z) ghat <- npreg(food~logexp,regtype="ll") ## For the plots, restrict focal attention to the bulk of the data ## (i.e. for the plotting area trim out 1/4 of one percent from each ## tail of y and z) trim <- 0.0025 plot(logexp,food, ylab="Food Budget Share", xlab="log(Total Expenditure)", xlim=quantile(logexp,c(trim,1-trim)), ylim=quantile(food,c(trim,1-trim)), main="Nonparametric Instrumental Kernel Regression", type="p", cex=.5, col="lightgrey") lines(logexp,phi,col="blue",lwd=2,lty=2) lines(logexp,fitted(ghat),col="red",lwd=2,lty=4) legend(quantile(logexp,trim),quantile(food,1-trim), c(expression(paste("Nonparametric IV: ",hat(varphi)(logexp))), "Nonparametric Regression: E(food | logexp)"), lty=c(2,4), col=c("blue","red"), lwd=c(2,2)) }) ## End(Not run)
gradients is a generic function which extracts gradients
from objects.
gradients(x, ...) ## S3 method for class 'condensity' gradients(x, se = FALSE, gradient.order = NULL, ...) ## S3 method for class 'condistribution' gradients(x, se = FALSE, gradient.order = NULL, ...) ## S3 method for class 'lsqregression' gradients(x, se = FALSE, gradient.order = NULL, ...) ## S3 method for class 'npregression' gradients(x, se = FALSE, gradient.order = NULL, ...) ## S3 method for class 'qregression' gradients(x, se = FALSE, ...) ## S3 method for class 'conmode' gradients(x, level = NULL, se = FALSE, ...) ## S3 method for class 'singleindex' gradients(x, se = FALSE, ...)gradients(x, ...) ## S3 method for class 'condensity' gradients(x, se = FALSE, gradient.order = NULL, ...) ## S3 method for class 'condistribution' gradients(x, se = FALSE, gradient.order = NULL, ...) ## S3 method for class 'lsqregression' gradients(x, se = FALSE, gradient.order = NULL, ...) ## S3 method for class 'npregression' gradients(x, se = FALSE, gradient.order = NULL, ...) ## S3 method for class 'qregression' gradients(x, se = FALSE, ...) ## S3 method for class 'conmode' gradients(x, level = NULL, se = FALSE, ...) ## S3 method for class 'singleindex' gradients(x, se = FALSE, ...)
Object to interrogate and whether gradient standard errors are requested.
x |
an object for which the extraction of gradients is meaningful. |
se |
a logical value specifying whether or not standard
errors of gradients are desired. Defaults to |
level |
for |
Optional local-polynomial derivative order controls.
gradient.order |
for |
Further method-specific arguments.
... |
other arguments. |
This function provides a generic interface for extraction of gradients
from objects. For npregression, condensity,
condistribution, and lsqregression objects fitted with
regtype="lp",
gradient.order identifies the stored continuous-predictor
derivative order to extract; it is not a post-fit recomputation control.
For lsqregression, the requested order must exactly match the stored
order. For qregression objects,
se=TRUE returns
asymptotic standard errors for the quantile gradients when the object was
fitted with gradients=TRUE.
Gradients extracted from the model object x.
This method currently only supports objects from the np library.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
See the references for the method being interrogated via
gradients in the appropriate help file. For example, for
the particulars of the gradients for nonparametric regression see the
references in npreg
fitted, residuals, coef,
and se, for related methods;
np for supported objects.
x <- runif(10) y <- x + rnorm(10, sd = 0.1) gradients(npreg(y~x, gradients=TRUE))x <- runif(10) y <- x + rnorm(10, sd = 0.1) gradients(npreg(y~x, gradients=TRUE))
Italian GDP growth panel for 21 regions covering the period 1951-1998 (millions of Lire, 1990=base). There are 1008 observations in total.
data("Italy")data("Italy")
A data frame with 2 columns, and 1008 rows.
the first column, of type ordered
the second column, of type numeric: millions of
Lire, 1990=base
Giovanni Baiocchi
Baiocchi, G. (2006), “Economic Applications of Nonparametric Methods,” Ph.D. Thesis, University of York.
data("Italy") with(Italy, { plot(ordered(year), gdp, xlab="Year (ordered factor)", ylab="GDP (millions of Lire, 1990=base)") })data("Italy") with(Italy, { plot(ordered(year), gdp, xlab="Year (ordered factor)", ylab="GDP (millions of Lire, 1990=base)") })
This package provides a variety of nonparametric and semiparametric
kernel methods that seamlessly handle a mix of continuous, unordered,
and ordered factor data types (unordered and ordered factors are often
referred to as ‘nominal’ and ‘ordinal’ categorical
variables respectively). A getting-started vignette containing a
short introduction to the np package can be accessed via
vignette("np_getting_started", package = "np"). It includes
prediction, no-search uncertainty/gradient refitting, and a migration guide
for users updating from 0.70-5. An installed
vignette for the entropy-based test family can be accessed via
vignette("np_entropy_tests", package = "np").
For a listing of all routines in the np package type: ‘library(help="np")’.
Bandwidth selection is a key aspect of sound nonparametric and
semiparametric kernel estimation. np is designed from the
ground up to make bandwidth selection the focus of attention. To this
end, one typically begins by creating a ‘bandwidth object’
which embodies all aspects of the method, including specific kernel
functions, data names, data types, and the like. One then passes these
bandwidth objects to other functions, and those functions can grab the
specifics from the bandwidth object thereby removing potential
inconsistencies and unnecessary repetition. Furthermore, many
functions such as plot (via class-specific S3 methods)
can work with the bandwidth object directly without
having to do the subsequent companion function evaluation.
The user may also combine these steps. If the first step (bandwidth
selection) is not performed explicitly then the second step will
automatically call the omitted first-step bandwidth selector using
defaults unless otherwise specified, and the bandwidth object can be
retrieved retroactively if so desired via objectname$bws.
Furthermore, options for bandwidth selection will be passed directly
to the bandwidth selector function. Note that the combined approach
would not be a wise choice for certain applications such as when
bootstrapping (as it would involve unnecessary computation since the
bandwidths would properly be those for the original sample and not the
bootstrap resamples) or when conducting quantile regression (as it
would involve unnecessary computation when different quantiles are
computed from the same conditional cumulative distribution estimate).
There are two ways in which you can interact with functions in
np, either i) using data frames, or ii) using a formula
interface, where appropriate.
To some, it may be natural to use the data frame interface. The R
data.frame function preserves a variable's type once it
has been cast (unlike cbind, which we avoid for this
reason). If you find this most natural for your project, you first
create a data frame casting data according to their type (i.e., one of
continuous (default, numeric), factor,
ordered). Then you would simply pass this data frame to
the appropriate np function, for example
npudensbw(dat=data).
To others, however, it may be natural to use the formula interface
that is used for the regression examples, among others. For
nonparametric regression functions such as npreg, you
would proceed as you would using lm (e.g., bw <-
npregbw(y~factor(x1)+x2)) except that you would of course not need to
specify, e.g., polynomials in variables, interaction terms, or create
a number of dummy variables for a factor. Every function in np
supports both interfaces, where appropriate.
Bandwidth objects for regression, unconditional and conditional density/distribution, single-index, partially linear and smooth-coefficient methods retain their training values. Formula objects retain the prepared model frame and NA policy; native objects retain the supplied training values. Fitting with replacement training data records that sample in the returned fit's bandwidth object, without modifying the original bandwidth object. Evaluation or prediction grids do not replace training data. Objects created without retained samples still require their original data bindings or explicit training inputs. New evaluation data involving custom formula transformations still require those transformation functions.
Estimator formulas do not support right-hand-side offset() special
terms; these are rejected rather than silently omitted. A variable named
offset is not an offset special. This restriction does not change
offset handling by a separately supplied parametric model in a specification
test. Conditional density/distribution formulas require response variable
names (separated by + for multiple responses). To transform a
conditional response, first create an explicit transformed variable in
data, or supply the transformed values through the native data
interface. Supported response transformations in other estimator families,
such as npreg(log(y) ~ x), retain their existing meaning.
Note that if your factor is in fact a character string such as, say,
X being either "MALE" or "FEMALE", np will handle
this directly, i.e., there is no need to map the string values into
unique integers such as (0,1). Once the user casts a variable as a
particular data type (i.e., factor,
ordered, or continuous (default,
numeric)), all subsequent methods automatically detect
the type and use the appropriate kernel function and method where
appropriate.
Estimators support multivariate data subject to each method's documented requirements and available computational resources. Runtime and memory depend on sample size, evaluation points, dimension, polynomial basis, kernel support, bandwidth type and search settings. Large datasets and high-dimensional fits can be expensive; there is no single exponential sample-size cost rule shared by all routines.
Nonparametric methods include unconditional density (distribution), conditional density (distribution), regression, mode, and quantile estimators along with gradients where appropriate, while semiparametric methods include single index, partially linear, and smooth (i.e., varying) coefficient models.
A number of tests are included such as consistent specification tests for parametric regression and quantile regression models along with tests of significance for nonparametric regression.
A variety of bootstrap methods for computing standard errors, nonparametric confidence bounds, and bias-corrected bounds are implemented.
A variety of bandwidth methods are implemented including fixed, nearest-neighbor, and adaptive nearest-neighbor.
A variety of data-driven methods of bandwidth selection are implemented, while the user can specify their own bandwidths should they so choose (either a raw bandwidth or scaling factor).
A flexible plotting utility, via class-specific S3
plot methods, facilitates graphing of multivariate
objects. An example for creating postscript graphs and pulling this
into a LaTeX document is provided.
The function npksum allows users to create or implement
their own kernel estimators or tests should they so desire.
The underlying functions are written in C for computational efficiency. Despite this, due to their nature, data-driven bandwidth selection methods involving multivariate numerical search can be time-consuming, particularly for large datasets. For MPI-oriented workflows on larger jobs, see the companion package npRmpi, which extends the same mixed-data kernel methodology to clustered computing environments.
To cite the np package, type citation("np") from within
R for details.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
The kernel methods in np employ the so-called
‘generalized product kernels’ found in Hall, Racine,
and Li (2004), Li, Lin, and Racine (2013), Li, Ouyang, and
Racine (2013), Li and Racine (2003), Li and Racine (2004), Li
and Racine (2007), Li and Racine (2010), Ouyang, Li, and
Racine (2006), and Racine and Li (2004), among others. For
details on a particular method, kindly refer to the original
references listed above.
We briefly describe the particulars of various univariate kernels used
to generate the generalized product kernels that underlie the kernel
estimators implemented in the np package. In a nutshell, the
generalized kernel functions that underlie the kernel estimators in
np are formed by taking the product of univariate kernels such
as those listed below. When you cast your data as a particular type
(continuous, factor, or ordered factor) in a data frame or formula,
the routines will automatically recognize the type of variable being
modelled and use the appropriate kernel type for each variable in the
resulting estimator.
where ,
and .
if , otherwise, where
, and .
if , otherwise, where
, and .
if , and
if ,
where is the number of (discrete) outcomes assumed by the
factor .
Note that must lie between and
.
if , and
if .
Note that must lie between and
.
if , and
if .
Note that must lie between and
.
if , and
if .
Note that must lie between and
.
if
, and
if .
Note that must lie between and
.
if
, and
if .
Note that must lie between and
.
,
where is the ordered support.
Note that must lie between and
.
So, if you had two variables, and
, and was continuous while
was, say, binary (0/1), and you created a data
frame of the form X <- data.frame(x1,x2=factor(x2)), then the
kernel function used by np would be
where the
particular kernel functions and
would be, say, the second order Gaussian
(ckertype="gaussian") and Aitchison and Aitken
(ukertype="aitchisonaitken") kernels by default, respectively
(note that for conditional density and distribution objects we can
specify kernels for the left-hand side and right-hand side variables
in this manner using cykertype="gaussian",
cxkertype="gaussian" and uykertype="aitchisonaitken",
uxkertype="aitchisonaitken").
Note that higher order continuous kernels (i.e., fourth, sixth, and eighth order) are derived from the second order kernels given above (see Li and Racine (2007) for details).
For particulars on any given method, kindly see the references listed for the method in question.
Tristen Hayfield <[email protected]>, Jeffrey S. Racine <[email protected]>
Maintainer: Jeffrey S. Racine <[email protected]>
We are grateful to John Fox and Achim Zeleis for their valuable input and encouragement. We would like to gratefully acknowledge support from the Natural Sciences and Engineering Research Council of Canada (NSERC:www.nserc.ca), the Social Sciences and Humanities Research Council of Canada (SSHRC:www.sshrc.ca), and the Shared Hierarchical Academic Research Computing Network (SHARCNET:www.sharcnet.ca)
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Hall, P. and J.S. Racine and Q. Li (2004), “Cross-validation and the estimation of conditional probability densities,” Journal of the American Statistical Association, 99, 1015-1026.
Li, Q. and J. Lin and J.S. Racine (2013), “Optimal bandwidth selection for nonparametric conditional distribution and quantile functions”, Journal of Business and Economic Statistics, 31, 57-65.
Li, Q. and D. Ouyang and J.S. Racine (2013), “Categorical Semiparametric Varying-Coefficient Models,” Journal of Applied Econometrics, 28, 551-589.
Li, Q. and J.S. Racine (2003), “Nonparametric estimation of distributions with categorical and continuous data,” Journal of Multivariate Analysis, 86, 266-292.
Li, Q. and J.S. Racine (2004), “Cross-validated local linear nonparametric regression,” Statistica Sinica, 14, 485-512.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2010), “Smooth varying-coefficient estimation and inference for qualitative and quantitative data,” Econometric Theory, 26, 1-31.
Ouyang, D. and Q. Li and J.S. Racine (2006), “Cross-validation and the estimation of probability distributions with categorical data,” Journal of Nonparametric Statistics, 18, 69-100.
Racine, J.S. and Q. Li (2004), “Nonparametric estimation of regression functions with both categorical and continuous data,” Journal of Econometrics, 119, 99-130.
Racine, J.S., Q. Li, and K.X. Yan (2020), “Kernel Smoothed Probability Mass Functions for Ordered Datatypes,” Journal of Nonparametric Statistics, 32(3), 563-586.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Scott, D.W. (1992), Multivariate Density Estimation: Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot
np.options
Constructors for detailed plot controls used by the redesigned
np plotting interface. Common choices such as errors,
band, alpha, bootstrap, and B remain direct
plot arguments; these helpers collect less common options.
np_boot_control(nonfixed = c("exact", "frozen"), wild = c("rademacher", "mammen"), blocklen = NULL) np_grid_control(xtrim = NULL, xq = NULL, slices = NULL) np_render_control(style = c("band", "bar"), bar = c("|", "I"), bar.num = NULL)np_boot_control(nonfixed = c("exact", "frozen"), wild = c("rademacher", "mammen"), blocklen = NULL) np_grid_control(xtrim = NULL, xq = NULL, slices = NULL) np_render_control(style = c("band", "bar"), bar = c("|", "I"), bar.num = NULL)
nonfixed |
Bootstrap behavior for non-fixed bandwidth routes.
|
wild |
Wild-bootstrap multiplier distribution. |
blocklen |
Optional block length for block bootstrap methods. |
xtrim |
Optional two-element trim range for evaluation grids. |
xq |
Optional evaluation quantiles. |
slices |
Optional slice specification for routes that support it. |
style |
Interval display style. |
bar |
Bar style when |
bar.num |
Optional number of bars. |
Gaussian simultaneous variability bands use the Gaussian-multiplier framework
of Chernozhukov, Chetverikov and Kato (2013, 2015). For the density/distribution
families, related simultaneous-inference research is due to Cattaneo, Jansson
and Ma (2024) and Cattaneo, Chandak, Jansson and Ma (2024). See
plot.np for the full published references, implementation scope
and estimator-specific qualifications.
These helpers validate names and values early. Raw lists are deliberately not accepted as substitutes, so misspelled detailed controls fail before plot computation begins.
Compound public plot arguments use dots, consistently with the package API.
Constructor function names and returned object fields are unchanged. Common rendering
controls such as data.overlay, data.rug, layout, and
output are supplied directly to plot(...) rather than through
np_render_control().
Gaussian simultaneous variability bands use the direct plot argument
gaussian.draws (default 9999), including supported density and
distribution plots. This controls Gaussian calibration only; B and
np_boot_control() continue to control bootstrap resampling. See
plot.np for supported targets, covariance contracts and
the references to Chernozhukov, Chetverikov and Kato (2013, 2015).
Conditional density and distribution level bootstraps permit different
supported continuous kernel families and orders on the X and Y sides,
including beta on either side. Beta-containing routes remain limited to
continuous X and Y with local-constant fitting and retain the resolved
support bounds stored in the bandwidth object. The nonfixed choice
changes nearest-neighbour bandwidth replay, not those fitted support bounds.
A small classed list consumed by plot methods.
## Not run: plot(fit, errors = "bootstrap", bootstrap = "inid", B = 9999, band = "pointwise", boot.control = np_boot_control(nonfixed = "exact")) ## End(Not run)## Not run: plot(fit, errors = "bootstrap", bootstrap = "inid", B = 9999, band = "pointwise", boot.control = np_boot_control(nonfixed = "exact")) ## End(Not run)
The role of data depends on the selected interface. It is never a
request to silently ignore a supplied training sample.
Formula calls use data for model-frame construction. Supported refits
through a bandwidth object retaining a formula also accept replacement
data; their established omitted-data and data = NULL behavior
is unchanged.
Native interfaces use explicitly supplied vectors, matrices or data frames.
Where data is not a native input, even explicitly supplying
data = NULL is an error. Omit it, supply inputs such as
xdat = d["x"] and ydat = d$y, or evaluate the native call inside
with(d, ...). Native inputs use ordinary R evaluation, not a data mask.
Existing argument evaluation and method dispatch are preserved. An error in
a supplied expression may therefore occur before the native-data diagnostic;
MPI methods retain their normal error context.
This includes the native IV interfaces: use with(d, npregiv(y, z, w))
or the supported formula interface.
Some functions genuinely consume a native argument called data.
In particular, npcopula(bws, data = observations), b.star,
npsdeptest and npsymtest retain their documented data inputs.
This policy does not change newdata, native evaluation arguments, or
which input takes precedence during prediction.
Plotting does not generally provide a replacement-data interface. A supplied
data argument is rejected when the selected plot route does not consume
it, including explicit NULL. Refit with the intended data and plot the
result, or use supported explicit plotting inputs. The existing partially
linear formula-bandwidth plot route retains its replacement-data support when
its explicit training inputs are omitted.
The diagnostic for unsupported native data is:
`data=` is supported only with the formula interface. For native calls, supply vectors, matrices or data frames directly, or use `with(data, ...)`.
Summary of continuous, unordered-categorical, and ordered-categorical kernels used by np (including higher-order continuous kernels and compact-support variants used in C-level code paths).
Documentation guide: see np.options for global options
and plot for plotting options.
Kernel option names used in np:
Continuous kernels:
ckertype (and ckerorder, ckerbound where applicable).
Unordered kernels:
ukertype.
Ordered kernels:
okertype.
Conditional density/distribution bandwidth objects split kernel
choices by response and regressor blocks:
cykertype/cxkertype,
uykertype/uxkertype,
oykertype/oxkertype
(with matching order/bound options for continuous kernels).
Let for continuous variables.
Continuous kernels (called via ckertype):
where is the standard normal density.
ckertype="gaussian" with ckerorder=2,4,6,8.
The compact-support Epanechnikov-family kernels implemented in C use
support :
ckertype="epanechnikov" with ckerorder=2,4,6,8.
Uniform (rectangular) kernel:
via ckertype="uniform" (order ignored).
With nearest-neighbor bandwidths, the uniform kernel compares the absolute distance directly with the computed radius: points at the radius are excluded. Tree search uses a conservative candidate box and the same final distance comparison, so rounding of standardized distances or tree endpoints cannot change this boundary convention.
For generalized- and adaptive-nearest-neighbor modes, each continuous
bandwidth is the literal th admitted distance after any occurrence
exclusion required by the route. Exact ties can therefore make the radius
zero. A zero continuous radius does not define a positive metric bandwidth
and is rejected rather than widened to a more distant observation or
replaced by a numerical floor. Fixed bandwidths (bwtype="fixed",
the default) avoid this nearest-neighbor radius limitation. Alternatively,
choose a larger or correct an unintended continuously coded tie.
Repeated values alone are not an error: only a requested radius that is
actually zero is rejected. Training fits and external evaluations can
differ at a tie boundary because their occurrence exclusions differ.
Any represented strictly positive
radius, including a positive subnormal value, is distinct from this
zero-radius condition.
The beta associated-kernel family is available for continuous data with
finite support. For an
evaluation point , observation , fixed support
, , and public metric bandwidth , define
The implemented PDF contribution is Chen's simple beta kernel
Thus ckertype="beta" uses the evaluation-centered associated-kernel
orientation: the beta shape parameters depend on , and the density
is evaluated at . The bandwidth convention is deliberately
metric-compatible with other continuous kernels: Chen's smoothing
parameter is . The factor is already included,
so callers must not apply either an additional factor or the
generic bounded-kernel normalization below.
Orders 4, 6, and 8 use the additive higher-order construction of Igarashi
and Kakizawa (2020). For public order ,
The coefficient vectors for orders 2, 4, 6, and 8 are respectively
, , , and
. The construction preserves unit mass and the original
support while deliberately producing signed kernels above order 2.
The Igarashi–Kakizawa higher-order bias result is a deterministic/fixed-
bandwidth result. The generalized- and adaptive-nearest-neighbour routes
below implement the same validated multiscale construction conditional on
their realized bandwidths; their availability is an implementation and
numerical-validation contract, not a claim that the fixed-bandwidth bias
theorem automatically extends to random NN bandwidths.
In the present implementation orders 2, 4, 6, and 8 are available through
npksum, npudens, npudist, npreg,
and the conditional density/distribution families. Regression and the
conditional families support local-constant, local-linear and
local-polynomial fits; categorical coordinates retain their categorical
kernels alongside continuous beta coordinates. Manual and cross-validated bandwidth objects support
bwtype="fixed", "generalized_nn", and
"adaptive_nn". Bounds may be explicit
(ckerbound="fixed") or inferred from the training sample
(ckerbound="range"); all active beta bounds must be finite.
For sorted distinct values , beta range bounds are
Consequently, beta ckerbound="range" is not equivalent to
ckerbound="fixed" at the raw sample minima and maxima; its exact
fixed-bound equivalent uses the coordinatewise padded bounds and
.
Thus every training value is strictly inside the fitted support, including
tied extrema, and raw-extremum PDF derivatives are finite. At least two
distinct finite values are required per continuous coordinate. This is an
empirical continuity convention, not an estimate of physical support: it
may extend beyond a known population bound. Use ckerbound="fixed"
when bounds are known; fixed bounds are always used literally and retain the
documented extended-real derivative convention when observations equal an
endpoint. Non-beta ckerbound="range" continues to use exact sample
minima and maxima. Rounded or atomic variables should be modelled with the
package's discrete kernels rather than made continuous by range padding.
Automatic univariate order-2 fixed-bandwidth beta range searches have an
additional basin certificate for density CVLS and distribution CDF
criteria when Powell is the selected solver. If , the
official criterion is evaluated once at
, where the beta concentration
equals .Machine$double.eps. If this uniform-
limit candidate materially improves the ordinary result, one deterministic
Powell refinement starts at ; the best materially distinct
official objective among the ordinary, tail, and refined candidates is
returned. The ordinary search uses the user's unchanged nmulti; the
certification and any refinement are separately counted in the bandwidth
summary. Cold starts and automatic restarts from a beta range bandwidth
object use this same single-certification contract. This safeguard does not
apply to explicit fixed bounds, CVML,
orders 4–8, nearest-neighbour or multivariate searches, or non-Powell
solvers.
Beta continuous coordinates can be combined with unordered and ordered
categorical coordinates in kernel sums and supported estimators. Automatic
mixed-data bandwidth selection is available for unconditional density,
conditional density/distribution, and regression. Regression supports automatic cv.ls/cv.aic
selection with fixed, generalized-NN, and adaptive-NN bandwidths; see
npregbw. Consult each family's bandwidth help page for its
supported beta selection criteria and configurations.
Regression and conditional fitting support the canonical scalar and general
local-polynomial engines. With regtype="ll" or regtype="lp",
regression gradients=TRUE reports the fitted local-polynomial slope
coefficient, as for the other supported kernels; it is not the derivative
of the entire fitted smoother with respect to the evaluation point.
npksum supports categorical products,
integer powers, normal, integral, convolution, and one-coordinate
PDF-derivative operators; permutation.operator="derivative" returns
every continuous first derivative. Unsupported score, OCG, or mixed
derivative requests fail explicitly rather than entering a legacy kernel
code.
For scale component , put ,
, and . At an interior
observation , its evaluation-coordinate derivative is
where is the digamma function. Higher-order derivatives use the
same signed multiscale coefficients as the PDF. Bandwidths are held fixed
while differentiating: this includes the evaluation bandwidth selected by a
generalized-NN rule and each observation bandwidth selected by an
adaptive-NN rule. These are derivatives of the fitted smoother conditional
on its realized bandwidths, not derivatives of the NN selection map.
Density CVLS quadrature integrates with respect to the continuous support measure. At a boundary observation, it therefore uses the interior-limit PDF contribution rather than assigning integration mass to an isolated endpoint value. This is applied separately to each multiscale component; zero-concentration uniform components remain included. Ordinary PDF point evaluations and the leave-one-out cross term retain their point values. This integration convention alone does not guarantee a finite optimum when an automatic search permits bandwidths tending to zero and the data contain repeated boundary observations. Existing positive search bounds are unchanged.
An observation exactly equal to the lower (upper) support endpoint makes
its matching scalar PDF contribution jump downward (upward) when the target
crosses that endpoint. The scalar derivative is consequently reported as
at a matching lower endpoint and at a matching
upper endpoint. An observation at the opposite endpoint contributes zero;
observations strictly inside the support have finite one-sided derivatives.
Local-constant regression and conditional estimators cancel numerator and
denominator jumps before classifying their gradient, so a normalized ratio
may still have a finite derivative (and a constant response or constant Y
factor gives exactly zero). A genuine ratio jump is returned as a signed
infinity. Numerically indeterminate cancellation is returned as NA
with a warning. Derivative hat matrices cannot encode response-specific
cancellation and therefore mark an affected endpoint row NA.
These distinctions follow R's numeric semantics: signed infinity denotes a
proper mathematical limit, whereas NA_real_ denotes an unavailable
value. Plot methods preserve the returned values and replace non-finite
coordinates only in their temporary drawing geometry; see
plot.np.
For nearest-neighbor modes, the
existing observation-support nearest-neighbor engine supplies the
evaluation-specific metric bandwidth or observation-specific
metric bandwidth , after which the same beta concentration
mapping is used.
For unconditional density and distribution fits, a generalized-NN query
identified as a training observation excludes that occurrence when selecting
its radius, for beta as for other continuous kernels. The full fit still
averages all donor contributions. Explicit external evaluation data remain
external even when their values equal training data.
For overlap, generalized bandwidths are evaluated at both centers;
adaptive bandwidths remain attached to training centers, while a genuinely
new evaluation center receives the established generalized-NN auxiliary
bandwidth. PDF, CDF, and overlap operators support both NN modes. See
npksum for the exact kernel-sum normalization and
npudens and npudist for estimator-specific
standard errors and examples.
The implemented beta CDF factor intentionally uses the complementary observation-centered orientation. With the notation above,
where is the regularized incomplete beta function.
It is evaluated as an analytic incomplete-beta probability, with a
symmetry transformation in the upper tail. Thus every order-2
contribution is in , and with fixed or adaptive bandwidth is
nondecreasing in ; it is exactly
zero at , exactly one at , and tends to
as . Multivariate CDFs use products of
these factors; npksum may also mix beta PDF and CDF factors across
dimensions.
This observation-centered beta CDF is not the integral, with respect to
, of the evaluation-centered Chen PDF contribution. It is also not
the target-centered bounded-CDF estimator of Mansouri, Rastin, and Mombeni
(2024). The orientation was selected because it preserves the essential
empirical-CDF contribution limit as , exact endpoint behavior,
monotonicity for order 2, and a direct analytic implementation suitable for
the existing kernel-sum architecture. Orders 4, 6, and 8 apply the same
signed multiscale coefficients to these incomplete-beta factors. The
Igarashi–Kakizawa density theorem does not establish a corresponding CDF
bias order; the public order identifies the construction. Signed
higher-order beta CDFs may overshoot or be locally nonmonotone,
just as existing higher-order distribution kernels may. Values are not
silently clipped or monotonized.
With bwtype="generalized_nn", the CDF bandwidth changes with the
target. Every returned order-2 contribution remains an incomplete-beta
probability in with exact support endpoints, but the resulting
curve need not be monotone. A deterministic boundary-heavy comparison was
monotone across the recorded chi-square(1), beta-boundary, U-shaped, and
uniform designs, while a seeded 300-design adversarial search found local
decreases as large as approximately . The
implementation neither clips nor monotonizes those values. Inversion-based
uses therefore remain outside this generalized-NN CDF contract.
The beta derivative operator differentiates the PDF contribution with respect to its evaluation coordinate. It does not differentiate the observation-centered CDF factor with respect to Y, and it is not a bandwidth score. As with existing higher-order kernels and local-polynomial derivatives, signed kernels can yield non-proper density or distribution estimates; derivative output is not clipped, monotonized, or otherwise repaired.
The beta "convolution" operator is the analytic overlap of two
associated beta density weights in their common observation coordinate. If
the two centers and bandwidths give shapes
and , then
The diagonal is the exact location- and bandwidth-dependent roughness.
This is an overlap, is symmetric, has units , and is
evaluated analytically in C with stable log-gamma ratios. It is not a
translation convolution and is not Chen's target-coordinate integrated
square. In particular, bounded cv.ls density and conditional-density
objectives continue to integrate the actual bounded estimator by their
existing quadrature route; they do not substitute this public overlap.
Bounded continuous-kernel normalization (ckerbound and, for
conditional objects, cxkerbound/cykerbound) reuses the
selected continuous kernel and renormalizes it on the declared support.
For a base kernel and support , the bounded kernel is
with . For bounded adaptive-nearest-neighbor
regression, each donor carries its own radius and
normalization mass . Its weight at evaluation point
is .
Regression fitting and bandwidth objectives use this donor-centred
convention, as do the corresponding adaptive density and conditional
density/distribution kernel factors. Delete-one objectives use radii from the corresponding
deleted sample. Fixed and generalized-neighbor regression use the
query-centred mass associated with their query bandwidth.
Option ckerbound="range" uses
sample bounds for ; ckerbound="fixed" uses user-supplied
bounds via ckerlb/ckerub (or the corresponding
cx*/cy* arguments). Infinite bounds recover the unbounded
kernel. This support-normalization strategy follows the same Racine-Li-Yan
finite-support normalization principle and is useful when data exhibit
non-negligible probability mass near boundaries.
Computationally, let
and
, with the continuous value
. For finite bounds the implementation evaluates the scaled
normalization mass directly as
Each supported kernel uses its analytic centered primitive. This avoids
subtracting nearly equal whole-kernel CDF values and avoids constructing a
normalization mass that vanishes numerically as grows. Consequently,
on finite the bounded density kernel converges to the uniform
density as . One-sided infinite bounds use the
corresponding exact half-mass term; two infinite bounds retain the ordinary
unbounded kernel path.
For distribution estimation, finite bounds use the distinct observation-centered truncated-kernel CDF
Thus , , and
as . The implementation
evaluates centered analytic interval masses rather than subtracting
nearly equal whole-kernel CDF values. This distribution operator is not the
integral of the evaluation-centered bounded density kernel above. For
nonnegative second-order kernels each contribution is monotone and lies in
; higher-order signed kernels retain their usual possible interior
nonmonotonicity or overshoot.
Typical bounded-kernel calls:
## Unconditional density on [0,1]
bw <- npudensbw(dat=data.frame(x),
ckertype="gaussian",
ckerbound="fixed", ckerlb=0, ckerub=1)
## Regression with automatic sample-range bounds
bw <- npregbw(xdat=data.frame(x), ydat=y, ckerbound="range")
## Conditional density with separate x/y support controls
bw <- npcdensbw(xdat=data.frame(x), ydat=data.frame(y),
cxkerbound="fixed", cxkerlb=0, cxkerub=1,
cykerbound="range")
Unordered-categorical kernels (called via ukertype; for category
count ):
(Aitchison-Aitken)
via ukertype="aitchisonaitken".
(normalized Li-Racine unordered kernel returned by npksum)
via ukertype="liracine".
Ratio estimators may equivalently use the proportional unnormalized weights,
since this common factor cancels in their numerator and denominator.
Ordered-categorical kernels (called via okertype):
Numeric ordered-factor levels retain their numeric distances, including
gaps. They must be finite and increasing with a finite numeric span.
Li-Racine weights and Racine-Li-Yan kernels accept fractional distances in
the original units; there is no inferred lattice spacing, rescaling, or
arbitrary denominator cap. Wang-van Ryzin and normalized Li-Racine retain
unit-lattice definitions: they require integer distances and total span
less than .Machine$integer.max. Nonnumeric ordered labels use their
declared ordinal ranks: for ordered(c("a","b","c","d","e")), the
distance from a to e is four, from c to d one.
Use explicit nonnumeric labels when rank distance, not numeric distance,
is intended.
Lattice admission is deliberately conservative: decimal labels at large
magnitudes can lose enough precision that integer distances cannot be
established reliably. Such lattice-dependent requests report an error;
they do not round the labels or substitute another kernel. Select
okertype="racineliyan" explicitly for retained-support smoothing.
(Wang-van Ryzin)
via okertype="wangvanryzin".
(Li-Racine ordered kernel)
via okertype="liracine".
(normalized Li-Racine ordered kernel; used internally)
(Racine-Li-Yan ordered kernel, normalized on support ).
exposed as okertype="racineliyan".
Here the support is the retained set of factor levels, including unused
levels, not an integer interval filling its gaps. The normalizer is indexed
by the training value , so weights need not be symmetric in training
and evaluation values. Cumulative kernels, overlap integrals, scores and
paired regression computations use that same support and direction.
For density/distribution roles, the public spelling "liracine"
denotes normalized Li-Racine and therefore still requires a unit lattice;
select "racineliyan" for fractional response/density support.
Conditional explanatory roles and regression use raw Li-Racine weights.
On nonlattice support, the raw Li-Racine cumulative operator sums these
unnormalized weights over retained levels at or below the evaluation
point; it is not a probability CDF. On a unit lattice, its cumulative
operator instead sums over every lattice point between the smallest and
largest retained levels up to the evaluation cutoff, including points in
gaps. Its convolution sums products over the retained levels, not the
gap-filled lattice interval. These are distinct incumbent operator
conventions. A fractional evaluation cutoff does not change the retained
integration support or turn a lattice cumulative into a nonlattice sum.
If a near-integer numeric support is ambiguous at its floating-point
precision, the raw Li-Racine cumulative operator reports an error rather
than silently selecting a different integration convention. Clearly
fractional support remains supported. Racine-Li-Yan provides an explicit
retained-support cumulative definition in either case.
At , bandwidth scores with positive
distances below one have non-finite elementwise one-sided derivatives and
report a condition; use an interior bandwidth when requesting such scores.
Kernel values at zero and one remain supported.
These univariate kernels are combined as generalized product kernels over mixed data types in the estimators and cross-validation criteria.
Aitchison, J. and Aitken, C. G. G. (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413–420.
Wang, M. C. and Van Ryzin, J. (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301–309.
Li, Q. and Racine, J. S. (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Racine, J. S. and Li, Q. (2004), “Nonparametric estimation of regression functions with both categorical and continuous data,” Journal of Econometrics, 119, 99–130.
Racine, J. S., Li, Q., and Yan, K. X. (2020), “Kernel Smoothed Probability Mass Functions for Ordered Datatypes,” Journal of Nonparametric Statistics, 32(3), 563–586. doi:10.1080/10485252.2020.1759595
Chen, S. X. (1999), “Beta kernel estimators for density functions,” Computational Statistics & Data Analysis, 31(2), 131–145. doi:10.1016/S0167-9473(99)00010-9
Jones, M. C. and Henderson, D. A. (2007), “Kernel-type density estimation on the unit interval,” Biometrika, 94(4), 977–984. doi:10.1093/biomet/asm068
Igarashi, G. and Kakizawa, Y. (2020), “Higher-order bias corrections for asymmetric kernel density estimators,” Journal of Nonparametric Statistics, 32(3), 716–752. doi:10.1080/10485252.2020.1770754
Mansouri, B., Rastin, A., and Allah Mombeni, H. (2024), “Beta Kernel Estimator for a Cumulative Distribution Function with Bounded Support,” Journal of Sciences, Islamic Republic of Iran, 34(4), 349–361 (volume dated 2023; accepted and DOI registered in 2024). doi:10.22059/jsciences.2024.367933.1007836
Hall, P., Racine, J. S., and Li, Q. (2004), “Cross-validation and the estimation of conditional probability densities,” Journal of the American Statistical Association, 99, 1015–1026.
np.options, plot
npregbw,
npudensbw,
npudistbw,
npcdensbw,
npcdistbw,
npksum,
np.options.
Global options controlling selected computational and display behavior for the np package.
Documentation guide: see np.kernels for kernels and
plot for plotting options.
The following options are recognized by np.
np.messages (logical): controls console/progress output.
Default is TRUE.
np.plot.progress (logical): controls bounded
plot/bootstrap progress heartbeats. Default is TRUE.
np.progress.interval.sec (numeric): package-wide minimum
elapsed time between visible progress heartbeats. The default is
2.0 seconds. When set, this canonical option takes precedence over
the older surface-specific interval options.
np.plot.progress.start.grace.sec (numeric): delay before
the first plot/bootstrap progress line is shown. Default is
0.75.
np.plot.progress.interval.sec (numeric): minimum elapsed
time between plot/bootstrap heartbeat lines once progress reporting has
started when np.progress.interval.sec is unset. Default is
2.0.
np.plot.progress.max.intermediate (integer): maximum
number of mid-run plot/bootstrap heartbeat lines emitted between the
initial start notice and final completion line. Default is 3.
np.tree (logical or "auto"): controls kd-tree
acceleration for continuous variables. TRUE forces eligible tree
routes on, FALSE disables them, and "auto" enables trees
only when active continuous kernels are bounded support
("epanechnikov" or "uniform"). Default is "auto".
Conditional-distribution generalized-neighbor bandwidth selection admits
explicit TRUE for second-order Epanechnikov and uniform kernels
without boundary normalization. The same explicit selection is available
for local-constant and linear/polynomial conditional density/distribution
fitting from generalized-neighbor CVLS bandwidth objects. Linear/polynomial
adaptive-neighbor fitting reuses bounded evaluation-tree batches.
Automatic-selection policies are unchanged.
The same explicit compact-kernel selection is available for linear and
polynomial regression generalized- and adaptive-neighbor
cv.ls/cv.aic bandwidth selection, and for generalized-neighbor
linear/polynomial regression fitting and its hat/apply operators.
Adaptive-neighbor linear/polynomial regression fitting also supports
this explicit selection, using donor-radius evaluation-tree batches.
GNN fitting may use dense accumulation when an exact support certificate
proves that tree traversal cannot prune any donor; kernel weights remain
varying, and no occupancy or conditioning threshold is used.
Fixed-bandwidth regression fitting and regression automatic-selection
policies are unchanged. Tree and dense accumulation can differ numerically on
nearly singular local-polynomial designs; enabling trees does not change
the basis, ridge or rank policies.
np.categorical.compress (logical): enables exact
unique-profile compression for eligible all-categorical routes. This is
distinct from np.tree: no continuous kd-tree is requested merely
because categorical compression is enabled. The default is TRUE.
Set options(np.categorical.compress = FALSE, np.tree = FALSE) to
force the historical dense categorical route for debugging or timing
comparisons.
np.macMseries.accelerate (logical or "auto"):
controls macOS arm64 Accelerate/vDSP/vForce fast paths for eligible
Gaussian-kernel and weighted-reduction computations. "auto"
enables these paths only when they were compiled for macOS arm64 with
Accelerate support; TRUE requests them when available; and
FALSE disables them exactly. Default is "auto". On
non-macOS, non-arm64, or non-Accelerate builds, this option falls back to
the ordinary portable code path. Accelerated and portable paths may use
different math-library kernels or summation orders, so platform or option
comparisons should use numerical tolerances; reserve exact equality for
controlled runs using the same acceleration setting.
np.objective.cache (logical): enables package-side evaluation
caching for eligible repeated bandwidth-search candidates. For all Powell
routes using the shared C optimizer wrapper, exact repeated raw candidate
vectors within one bandwidth solve reuse the previous objective value,
including repeated candidates reached by later Powell restarts. For
eligible continuous-only generalized/adaptive nearest-neighbor routes,
this also enables the existing integer nearest-neighbor objective cache.
Mixed continuous/categorical rows use only the exact full-candidate cache,
so categorical smoothing parameters remain part of the cache key. Default
is TRUE. Eligible continuous npscoefbw and npindexbw
routes also use package-side caches around their family-native R
optim evaluations. Set
options(np.objective.cache = FALSE) to force repeated eligible
candidates through the evaluator for diagnostic timing comparisons.
Each native Powell-side cache has an independent 64 MiB peak workspace
ceiling, including replacement storage during growth. If the ceiling or
an allocation prevents growth, existing entries remain available and
the selected search continues without inserting new entries; bandwidth
cache diagnostics report this through allocation.failed.
MADS/NOMAD solver caching is separate and is not
controlled by this option, and the saturated extended-NN distance cache is
governed by np.extendednn. Bandwidth summaries keep
Number of Function Evaluations as the established cumulative
optimizer evaluation count and report NOMAD, Powell, R-optim,
nearest-neighbor,
degree-search, guarded-evaluation, and other fast-CV diagnostics on
separate lines when the corresponding counters are available. These
diagnostics describe their own optimizer/cache layer and are not intended
to decompose the function-evaluation count arithmetically.
np.nomad.degree.start.policy (character): controls automatic
polynomial-degree starting values for NOMAD local-polynomial searches when
degree.start is not supplied. The default,
"low_first_full_random", uses degree.min for the first start
and draws later starts over the full user-specified
degree.min/degree.max range. Other accepted values are
"mid_first_full_random", "anchor_then_random",
"spread_then_random", and "random_full_only". Explicit
degree.start values remain the first start.
np.largeh (logical): enables continuous large-
shortcut evaluations. Default is TRUE. Set
options(np.largeh = FALSE) to keep tree/dense routing unchanged
while forcing continuous large-bandwidth objective rows through the
ordinary kernel-summation machinery for diagnostic timing comparisons.
np.extendednn (logical): enables extended nearest-neighbor
bandwidth search and manually supplied nearest-neighbor bandwidths above
the ordinary neighbor-count limit for eligible
generalized/adaptive nearest-neighbor routes. When TRUE, a
nearest-neighbor search parameter above scales the saturated
nearest-neighbor bandwidth. Default is TRUE.
np.largeh.rel.tol (numeric): relative tolerance used by the
continuous large- shortcut. When all standardized distances for a
continuous predictor are sufficiently close to zero, the corresponding
kernel factor is approximated by to reduce repeated kernel
evaluations. Default is 1e-3. Valid range is (0, 0.1).
np.largelambda (logical): enables discrete near-upper
bandwidth shortcut evaluations. Default is TRUE. Set
options(np.largelambda = FALSE) to keep categorical routing
unchanged while forcing near-upper discrete bandwidth rows through the
ordinary category-comparison machinery for diagnostic timing comparisons.
np.disc.upper.rel.tol (numeric): relative tolerance used by
the discrete upper-bound shortcut for bandwidths near their feasible upper
bounds. The near-upper check is applied relative to each kernel's own
feasible upper bound (e.g., Aitchison-Aitken depends on category
cardinality), with a tiny machine-precision floor for numerical
robustness. When same/different-category kernel values are numerically
close, the corresponding discrete kernel factor is treated as constant to
reduce repeated category comparisons. Default is 1e-2. Valid range
is (0, 0.5).
plot.par.mfrow (logical): used by plot to
determine whether plotting layout is automatically managed via
par(mfrow=...). If NULL (default behavior), np uses
its internal plotting defaults.
Option values can be set globally via options and restored
with on.exit in scripts/functions for reproducibility.
Jeffrey S. Racine [email protected]
np.kernels, plot
np, plot, options
## Not run: old <- options( np.tree = "auto", np.categorical.compress = TRUE, np.macMseries.accelerate = "auto", np.objective.cache = TRUE, np.largeh = TRUE, np.extendednn = TRUE, np.largelambda = TRUE, np.messages = FALSE, np.largeh.rel.tol = 1e-3, np.disc.upper.rel.tol = 1e-2 ) on.exit(options(old), add = TRUE) ## ... run bandwidth selection / estimation ... ## End(Not run)## Not run: old <- options( np.tree = "auto", np.categorical.compress = TRUE, np.macMseries.accelerate = "auto", np.objective.cache = TRUE, np.largeh = TRUE, np.extendednn = TRUE, np.largelambda = TRUE, np.messages = FALSE, np.largeh.rel.tol = 1e-3, np.disc.upper.rel.tol = 1e-2 ) on.exit(options(old), add = TRUE) ## ... run bandwidth selection / estimation ... ## End(Not run)
Compute pairwise nonparametric regressions and densities for a set of variables, then plot a pairs-style display with fitted smoothers.
np.pairs(y.vars, y.dat, ...) np.pairs.plot(pair.list)np.pairs(y.vars, y.dat, ...) np.pairs.plot(pair.list)
These arguments identify the variables, data, and pair specifications to plot.
pair.list |
list returned by |
y.dat |
data frame containing the variables listed in |
y.vars |
character vector of column names in |
Further graphical arguments are passed through to plotting methods.
... |
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
On the diagonal, npudens is used to compute kernel density
estimates. Off-diagonal panels use npreg with residuals to draw
scatterplots and smoothers.
np.pairs returns a list with components
y_vars, pair_names, and pair_kerns.
np.pairs.plot returns NULL (invisibly).
np.kernels, np.options, plotnpudens, npreg
## Not run: data("USArrests") y.vars <- c("Murder", "UrbanPop") names(y.vars) <- c("Murder Arrests per 100K", "Pop. Percent Urban") pair.list <- np.pairs( y.vars = y.vars, y.dat = USArrests, ckertype = "epanechnikov", bwscaling = TRUE ) np.pairs.plot(pair.list) ## End(Not run)## Not run: data("USArrests") y.vars <- c("Murder", "UrbanPop") names(y.vars) <- c("Murder Arrests per 100K", "Pop. Percent Urban") pair.list <- np.pairs( y.vars = y.vars, y.dat = USArrests, ckertype = "epanechnikov", bwscaling = TRUE ) np.pairs.plot(pair.list) ## End(Not run)
npcdens computes kernel conditional density estimates on
-variate evaluation data, given a set of training data (both
explanatory and dependent) and a bandwidth specification (a
conbandwidth object or a bandwidth vector, bandwidth type, and
kernel type) using the method of Hall, Racine, and Li (2004).
The data may be continuous, discrete (unordered and ordered
factors), or some combination thereof.
npcdens(bws, ...) ## S3 method for class 'formula' npcdens(bws, data = NULL, newdata = NULL, ...) ## S3 method for class 'conbandwidth' npcdens(bws, txdat = stop("invoked without training data 'txdat'"), tydat = stop("invoked without training data 'tydat'"), exdat, eydat, gradients = FALSE, gradient.order = 1L, proper = FALSE, proper.method = c("project"), proper.control = list(), ..., se = FALSE) ## Default S3 method: npcdens(bws, txdat, tydat, nomad = FALSE, ...)npcdens(bws, ...) ## S3 method for class 'formula' npcdens(bws, data = NULL, newdata = NULL, ...) ## S3 method for class 'conbandwidth' npcdens(bws, txdat = stop("invoked without training data 'txdat'"), tydat = stop("invoked without training data 'tydat'"), exdat, eydat, gradients = FALSE, gradient.order = 1L, proper = FALSE, proper.method = c("project"), proper.control = list(), ..., se = FALSE) ## Default S3 method: npcdens(bws, txdat, tydat, nomad = FALSE, ...)
These arguments identify the bandwidth specification, formula/data interface, and training data.
bws |
a bandwidth specification. This can be set as a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
txdat |
a |
tydat |
a |
This argument controls the recommended automatic local-polynomial NOMAD route, which jointly selects continuous polynomial degree and bandwidths when these are computed inside npcdens.
nomad |
logical shortcut passed through to |
These arguments control where the fitted conditional density is evaluated and which estimates are returned.
exdat |
a |
eydat |
a |
se |
logical scalar, default |
gradients |
a logical value specifying whether to return estimates of the
gradients at the evaluation points. Defaults to |
gradient.order |
derivative order for continuous explanatory-variable gradients when
|
newdata |
An optional data frame in which to look for evaluation data. If omitted, the training data are used. |
These arguments control optional post-estimation properization of the fitted conditional density.
proper |
a logical value specifying whether to apply post-estimation
properization to the conditional density estimate. Defaults to
|
proper.control |
a list of controls for properization. Supported entries are
|
proper.method |
a character string specifying the properization method. Currently
|
Further arguments are passed to npcdensbw when bandwidths are computed internally, or used to interpret a numeric bws vector.
... |
additional arguments supplied to |
Conditional fitting and replay use the literal categorical kernels for
both explanatory and response variables. Near-upper categorical bandwidths
are not replaced by approximate constant factors. The same target is used
for levels, gradients, standard errors, conditional hats, and reconstructed
plot uncertainty. This conditional-family policy does not change direct
regression or unconditional kernel-sum evaluation and does not modify the
caller's np.largelambda option.
With generalized nearest-neighbor bandwidths, query identity matters when
selecting a radius: a training observation excludes its own occurrence,
whereas explicit evaluation data remain external queries even if their
values equal training observations. Consequently,
predict(fit, newdata = training.data) can differ from
fitted(fit). This does not omit the training contribution from the
fitted estimator. See np.kernels for the radius convention.
With a formula-derived bandwidth object, supplying only tydat
replaces the evaluated response in retained-training-sample order: one row
per observation retained after the original subset and missing-value selection.
Original excluded rows are not restored; row names or equal lengths do not
imply original-data order. The effective na.action is then applied
jointly to the retained predictors and replacement response; any new omission
indices refer to this retained sample. The selected bandwidths remain fixed,
and the returned object retains the replacement sample for subsequent refits.
Use data for full formula-data replacement, not together with a partial
response replacement. Explicit native training arguments retain their separate
positional contract.
For native (non-formula) objects, named newdata columns are matched
to the retained variable names and reordered as needed. Extra columns are
ignored; missing, duplicate or ambiguous names are errors. An unnamed
matrix or vector remains positional for a single evaluation role.
Explicit native evaluation arguments retain their positional contract and
take precedence over newdata.
For a native bandwidth object, newdata is split into
exdat and eydat using the retained predictor and response
column names. Names must identify both roles unambiguously;
explicitly supplied native evaluation arguments take precedence. This
evaluates at the requested rows without repeating bandwidth selection.
For explicit external evaluation rows, a completed explanatory-kernel row
whose weights are all zero has no conditional estimate. Such rows return
NA for the fitted value and requested uncertainty or derivatives,
with one notice. A missing categorical counterfactual affects only its
contrast; it does not invalidate an otherwise supported base estimate.
A zero response-kernel contribution is not a missing explanatory row.
Supported rows retain their usual computation. Required internal evaluations
remain strict. With proper = TRUE, complete unsupported fixed-X
slices retain NA; projection still applies to supported slices.
Documentation guide: see npcdensbw for bandwidth selection and search controls, np.kernels for kernels, np.options for global options, and plot, plot.np for plotting options.
When bws is omitted, the formula and default methods call
npcdensbw first and pass bandwidth-selection arguments
from ... to that call. When bws is already a
conbandwidth object, npcdens estimates with the stored
bandwidth metadata in that object.
Beta associated kernels may be selected independently for explanatory X
coordinates (cxkertype="beta") and response Y coordinates
(cykertype="beta"). Orders 2, 4, 6, and 8, fixed/generalized-NN/
adaptive-NN bandwidths, explicit finite bounds, sample-range bounds, and
automatic cv.ml/cv.ls bandwidth selection are supported.
Beta kernels act on continuous coordinates and can coexist with
supported categorical X or Y coordinates using their respective categorical kernels.
Local-constant, local-linear and local-polynomial fits are supported. For local-constant fits, analytic first derivatives with respect to the
continuous X coordinates are available with gradients=TRUE, including
beta-X/legacy-Y, legacy-X/beta-Y, fixed, generalized-NN, and adaptive-NN
combinations. NN bandwidths are held fixed while differentiating. Exact
beta-X endpoint jumps are cancelled in the normalized ratio before a
gradient is classified; genuine jumps are signed infinities, while
indeterminate cancellation is NA, both with an explanatory warning.
Returned infinities retain that extended-real meaning. Plot methods convert
them to missing geometry only in a temporary drawing copy, leaving fitted
and plot-data objects unchanged.
For ordinary conditional-density level plots, bootstrap intervals support
different continuous X- and Y-side kernel families or orders, including
beta on either side. Beta-containing bootstrap levels use the same signed
log-domain conditional ratio as the fitted estimator. With non-fixed
bandwidths, np_boot_control(nonfixed="exact") reconstructs each
duplicate-row resample and recomputes its nearest-neighbour bandwidths,
while nonfixed="frozen" keeps the original fitted bandwidths. In both
modes, resolved beta "range" support bounds are replayed from the
bandwidth object rather than recomputed from bootstrap counts. This
mixed-family level-bootstrap support does not alter the separate restrictions on gradient, quantile, or bias-corrected centers.
Higher-order fits
are signed and need not be proper densities; no positivity repair is
applied. Bounded beta-response cv.ls integrates the actual
conditional estimator over the Y support and does not replace that integral
by the public observation-coordinate beta overlap.
Argument groups for bandwidth selection are documented on
npcdensbw. The most common workflow is to choose data
and bandwidth inputs first, then bandwidth criterion and
representation, then kernel/support controls, numerical search
controls, bounded cv.ls quadrature controls if relevant, and
finally local-polynomial/NOMAD controls for polynomial-adaptive fits.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
npcdens implements a variety of methods for estimating
multivariate conditional distributions (-variate) defined
over a set of possibly continuous and/or discrete (unordered, ordered)
data. The approach is based on Li and Racine (2004) who employ
‘generalized product kernels’ that admit a mix of continuous
and discrete data types.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating
the density at the point . Generalized nearest-neighbor
bandwidths change with the point at which the density is estimated,
. Fixed bandwidths are constant over the support of .
Training and evaluation input data may be a
mix of continuous (default), unordered discrete (to be specified in
the data frames using factor), and ordered discrete (to be
specified in the data frames using ordered). Data can be
entered in an arbitrary order and data types will be detected
automatically by the routine (see np for details).
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth order Gaussian and Epanechnikov kernels, and the uniform kernel. Unordered discrete data types use a variation on Aitchison and Aitken's (1976) kernel, while ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
For practitioners who want the recommended automatic local-polynomial degree-and-bandwidth NOMAD route
without spelling out all LP tuning arguments,
npcdens(..., nomad=TRUE) and npcdensbw(..., nomad=TRUE)
expand missing settings to the same documented preset. Explicit
incompatible settings fail fast rather than being silently rewritten.
With a raw polynomial basis, high powers of poorly scaled continuous
predictors (such as uncentred calendar years) can produce severely
ill-conditioned systems. Conditional local-polynomial fits do not apply
the design-conditioning rejection used by npreg; they may return
inaccurate finite values without a warning, with or without a ridge
adjustment. Centre or scale such predictors before fitting and apply the
same transformation to all evaluation or prediction data. The explicit
bernstein.basis = TRUE representation is another option for
improving conditioning. Check numerical stability for the chosen data,
degree and bandwidths. proper = TRUE enforces probability-shape
constraints; it does not repair an ill-conditioned polynomial solve.
With regtype = "lp", gradients = TRUE and
gradient.order greater than one expose higher-order derivative
estimates with respect to continuous explanatory variables. These
derivatives use the same local-polynomial basis, degree, Bernstein
option, bandwidths, and kernels as the fitted conditional density. See
npreg for the complete heterogeneous GLP multi-index and
Bernstein-representation definitions shared by these routes.
With se = TRUE, available higher-order derivative columns for
fixed and adaptive nearest-neighbour bandwidths also have standard
errors. These combine the existing local pseudo-response variance with
the squared norm of the actual derivative weighting row, including its
accepted ridge adjustment. They condition on the selected bandwidths,
neighbour radii and local-polynomial map; they do not account for their
selection uncertainty. Generalized nearest-neighbour higher-order point
derivatives remain subject to the existing hat-operator restriction.
Bootstrap inference remains recommended.
With positive-degree local-polynomial fits (including local-linear fits),
numerical ridging follows the policies described in npreg
(Seifert and Gasser, 2000). The conditional pseudo-response uncertainty
formulas here are distinct from ordinary regression's residual normalization.
With positive-degree local-polynomial fits (including local-linear fits),
categorical first-difference standard errors use paired endpoint influence
calculations. The covariance between the two category endpoints is retained,
not replaced by the sum of their marginal variances. These calculations
condition on the selected basis, smoothing parameters and realized neighbour
radii for all three bandwidth types. They run only when both
gradients = TRUE and se = TRUE request them. A nonsmooth
regularization boundary or nonfinite influence gives NA uncertainty
with a notice, without changing the point contrast.
For ordinary scalar fits, leading interior standard errors use the squared X-kernel moment; conditional density errors additionally use the independent Y-kernel moment. Analytic first-derivative errors for fixed and generalized nearest-neighbour bandwidths with Gaussian or Epanechnikov kernels use the squared derivative-kernel moment and the X bandwidth. These formulas do not establish uniform-kernel derivative inference or full adaptive-NN inference with estimated random radii. Positive-degree local-polynomial fits use their separate covariance calculation.
For fixed and generalized nearest-neighbour scalar fits with categorical variables, these leading moments retain squared categorical kernel factors and the joint training-category frequencies. Conditional distributions, and conditional densities with no continuous response, retain the numerator–denominator covariance of the ratio estimator. In particular, a constant response-kernel contribution has zero conditional variance. Purely categorical fits use this ratio covariance without a continuous bandwidth factor, including nearest-neighbour-labelled bandwidth objects. Beta-kernel and positive-degree local-polynomial covariance calculations retain their separate targets.
For scalar adaptive nearest-neighbour fits with any continuous variable,
requested level and available continuous first-derivative standard errors
use the complete empirical influence of the conditional ratio. They retain
the actual normalized X weights and continuous/categorical Y contributions,
including numerator and denominator derivatives. This working covariance
holds the selected model, observed X geometry and realized response
nearest-neighbour radii fixed; it does not account for their sampling or
selection uncertainty. Local-constant-equivalent degree-zero fits share
this calculation, including continuous responses with categorical-only X.
Positive-degree local-polynomial, beta-kernel and paired categorical-
contrast errors retain their separate covariance calculations. With
se = FALSE, the additional uncertainty pass is not performed.
The se component records whether uncertainty was requested.
conderr and congerr are NULL when se = FALSE.
se() and gradients(..., se = TRUE) only extract stored
results and give a no-search refit message when the errors were omitted.
predict(..., se.fit = TRUE) explicitly requests the needed errors.
npcdens returns a condensity object. The generic
accessor functions fitted, se, and
gradients, extract estimated values, asymptotic standard
errors on estimates, and gradients, respectively, from the returned
object. Furthermore, the functions predict,
summary and plot support objects of both
classes. The returned objects have the following components:
xbw |
bandwidth(s), scale factor(s) or nearest neighbours for the
explanatory data, |
ybw |
bandwidth(s), scale factor(s) or nearest neighbours for the
dependent data, |
xeval |
the evaluation points of the explanatory data |
yeval |
the evaluation points of the dependent data |
condens |
estimates of the conditional density at the evaluation
points. An evaluation row whose required explanatory normalization is
exactly zero or non-finite is returned as |
conderr |
when |
congrad |
if invoked with |
congerr |
if invoked with |
log_likelihood |
aggregate fitted conditional-density log likelihood.
Every represented strictly positive estimate, including a positive
subnormal value, contributes its literal logarithm. An exact zero or
negative estimate has no mathematical logarithm and is represented in this
aggregate by the established computational placeholder
|
The conditional density target is . In the
product-kernel formulation this can be viewed as estimating the joint
mixed-data density of and normalizing by the marginal
density of , with local-polynomial routes using the selected
continuous-coordinate polynomial degree in the conditional fit. The
requested standard errors are asymptotic standard errors for the fitted
conditional density values, and gradient standard errors are returned
when gradients are requested and defined.
Scalar conditional fits involving beta kernels use the empirical
observation-influence covariance. For normalized explanatory weights
, response-kernel contributions , and fitted value
, the level variance is
, using the full training count
. Supported continuous-derivative errors use the corresponding
differentiated influence. Categorical contrasts use the difference of the
two endpoints' observation influences inside the same squared norm, thereby
retaining their covariance; self-contrasts have zero variance.
These calculations hold the selected bandwidth
state fixed; they do not add bandwidth-selection or random-NN-radius
uncertainty, and do not replace positive-degree LP covariance.
For book-length derivations, see Li and Racine (2007), Chapter 5 Conditional Density Estimation, especially Sections 5.1-5.4, and Chapter 4 Kernel Estimation with Mixed Data. The later workflow treatment is Racine (2019), Chapter 4 Conditional Probability Density and Cumulative Distribution Functions.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Chen, S.X. (1999), “Beta kernel estimators for density functions,” Computational Statistics & Data Analysis, 31(2), 131–145. doi:10.1016/S0167-9473(99)00010-9.
Igarashi, G. and Kakizawa, Y. (2020), “Higher-order bias corrections for asymmetric kernel density estimators,” Journal of Nonparametric Statistics, 32(3), 716–752. doi:10.1080/10485252.2020.1770754.
Hall, P. and J.S. Racine and Q. Li (2004), “Cross-validation and the estimation of conditional probability densities,” Journal of the American Statistical Association, 99, 1015-1026.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Scott, D.W. (1992), Multivariate Density Estimation. Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np
npudens
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), and compute the # likelihood cross-validated bandwidths (default) using a second-order # Gaussian kernel (default). Note - this may take a minute or two # depending on the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { # First, compute the bandwidths... note that this may take a minute or # two depending on the speed of your computer. bw <- npcdensbw(formula=gdp~ordered(year), nmulti=1) # Next, compute the condensity object... fhat <- npcdens(bws=bw) # The object fhat now contains results such as the estimated conditional # density function (fhat$condens) and so on... summary(fhat) # Call the plot() function to visualize the results (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), and compute the # likelihood cross-validated bandwidths (default) using a second-order # Gaussian kernel (default). Note - this may take a minute or two # depending on the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { # First, compute the bandwidths... note that this may take a minute or # two depending on the speed of your computer. # Note - we cast `X' and `y' as data frames so that plot() can # automatically grab names (this looks like overkill, but in # multivariate settings you would do this anyway, so may as well get in # the habit). X <- data.frame(year=ordered(year)) y <- data.frame(gdp) bw <- npcdensbw(xdat=X, ydat=y, nmulti=1) # Next, compute the condensity object... fhat <- npcdens(bws=bw) # The object fhat now contains results such as the estimated conditional # density function (fhat$condens) and so on... summary(fhat) # Call the plot() function to visualize the results (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=FORMULA): For this example, we load the old # faithful geyser data from the R `datasets' library and compute the # conditional density function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npcdensbw(formula=eruptions~waiting, nmulti=1) summary(bw) # Plot the density function (<ctrl>-C will interrupt on *NIX systems, # <esc> will interrupt on MS Windows systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=DATA FRAME): For this example, we load the old # faithful geyser data from the R `datasets' library and compute the # conditional density function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... # Note - we cast `X' and `y' as data frames so that plot() can # automatically grab names (this looks like overkill, but in # multivariate settings you would do this anyway, so may as well get in # the habit). X <- data.frame(waiting) y <- data.frame(eruptions) bw <- npcdensbw(xdat=X, ydat=y, nmulti=1) summary(bw) # Plot the density function (<ctrl>-C will interrupt on *NIX systems, # <esc> will interrupt on MS Windows systems) if (interactive()) plot(bw) }) # EXAMPLE 3 (INTERFACE=FORMULA): Replicate the DGP of Klein & Spady # (1993) (see their description on page 405, pay careful attention to # footnote 6 on page 405). set.seed(123) n <- 300 # x1 is chi-squared having 3 df truncated at 6 standardized by # subtracting 2.348 and dividing by 1.511 x <- rchisq(n, df=3) x1 <- (ifelse(x < 6, x, 6) - 2.348)/1.511 # x2 is normal (0, 1) truncated at +- 2 divided by 0.8796 x <- rnorm(n) x2 <- ifelse(abs(x) < 2 , x, 2) / 0.8796 # y is 1 if y* > 0, 0 otherwise. y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) data.train <- data.frame(y = factor(y), x1 = x1, x2 = x2) # Generate data-driven bandwidths (likelihood cross-validation). Note - # this may take a few minutes depending on the speed of your computer... bw <- npcdensbw(formula=y~x1+x2, data=data.train, nmulti=1) # Next, create the evaluation data in order to generate a perspective # plot x1.seq <- seq(min(x1), max(x1), length=30) x2.seq <- seq(min(x2), max(x2), length=30) X.eval <- expand.grid(x1=x1.seq,x2=x2.seq) data.eval <- data.frame( y=factor(rep(1, nrow(X.eval)), levels=levels(data.train$y)), x1=X.eval[,1], x2=X.eval[,2] ) # Now evaluate the conditional probability for y=1 and for the # evaluation Xs fit <- fitted(npcdens(bws=bw,newdata=data.eval)) # Finally, coerce the data into a matrix for plotting with persp() fit.mat <- matrix(fit, 30, 30) # Generate a perspective plot similar to Figure 2 b of Klein and Spady # (1993) persp(x1.seq, x2.seq, fit.mat, col="white", ticktype="detailed", expand=0.5, axes=FALSE, box=FALSE, main="Estimated Nonparametric Probability Perspective", theta=310, phi=25) # EXAMPLE 3 (INTERFACE=DATA FRAME): Replicate the DGP of Klein & Spady # (1993) (see their description on page 405, pay careful attention to # footnote 6 on page 405). set.seed(123) n <- 300 # x1 is chi-squared having 3 df truncated at 6 standardized by # subtracting 2.348 and dividing by 1.511 x <- rchisq(n, df=3) x1 <- (ifelse(x < 6, x, 6) - 2.348)/1.511 # x2 is normal (0, 1) truncated at +- 2 divided by 0.8796 x <- rnorm(n) x2 <- ifelse(abs(x) < 2 , x, 2) / 0.8796 # y is 1 if y* > 0, 0 otherwise. y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) # Create the X matrix X <- cbind(x1, x2) y.factor <- factor(y) # Generate data-driven bandwidths (likelihood cross-validation). Note - # this may take a few minutes depending on the speed of your computer... bw <- npcdensbw(xdat=X, ydat=y.factor, nmulti=1) # Next, create the evaluation data in order to generate a perspective # plot x1.seq <- seq(min(x1), max(x1), length=30) x2.seq <- seq(min(x2), max(x2), length=30) X.eval <- expand.grid(x1=x1.seq,x2=x2.seq) # Now evaluate the conditional probability for y=1 and for the # evaluation Xs fit <- fitted(npcdens(exdat=X.eval, eydat=factor(rep(1, nrow(X.eval)), levels=levels(y.factor)), bws=bw)) # Finally, coerce the data into a matrix for plotting with persp() fit.mat <- matrix(fit, 30, 30) # Generate a perspective plot similar to Figure 2 b of Klein and Spady # (1993) persp(x1.seq, x2.seq, fit.mat, col="white", ticktype="detailed", expand=0.5, axes=FALSE, box=FALSE, main="Estimated Nonparametric Probability Perspective", theta=310, phi=25) # EXAMPLE 4: Variations on local polynomial conditional density # estimation with proper = TRUE. data("Italy") # Work in years relative to 1975 to condition the raw polynomial basis. # Calendar year = model year + year.offset, also for prediction data. year.offset <- 1975 Italy2 <- within(Italy, { year <- as.numeric(as.character(year)) - year.offset }) # Plot only: make the plotted surface proper on the plot evaluation grid. fhat <- npcdens(gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1) plot(fhat, proper = TRUE) # Fit an object whose fitted values are themselves proper. ctrl_fit <- list( mode = "slice", apply = "fitted", slice.grid.size = 101L, slice.extend.factor = 0.1 ) fhat_fit <- npcdens( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_fit ) fit_proper <- fitted(fhat_fit) fit_raw <- fhat_fit$condens.raw # Display the repaired and raw fitted values for cases where the raw # fitted density is negative. head(cbind(fit_proper, fit_raw)[which(fit_raw < 0), ]) # Predict on a common explicit y-grid for several years, and render # those predictions proper. g.grid <- seq(min(Italy2$gdp), max(Italy2$gdp), length.out = 200) nd_grid <- expand.grid( gdp = g.grid, year = c(1955, 1975, 1995) - year.offset ) pred_grid <- predict(fhat, newdata = nd_grid, proper = TRUE) # Predict on paired rows with different gdp grids by year, and still # make the predictions proper via slice mode. g1 <- seq(quantile(Italy2$gdp, 0.10), quantile(Italy2$gdp, 0.60), length.out = 60) g2 <- seq(quantile(Italy2$gdp, 0.30), quantile(Italy2$gdp, 0.90), length.out = 35) nd_slice <- rbind( data.frame(gdp = g1, year = rep(1960 - year.offset, length(g1))), data.frame(gdp = g2, year = rep(1985 - year.offset, length(g2))) ) pred_slice <- predict( fhat, newdata = nd_slice, proper = TRUE, proper.control = list(mode = "slice") ) # One object that carries properization for fitted values and for later # predict() calls. ctrl_both <- list( mode = "slice", apply = "both", slice.grid.size = 101L, slice.extend.factor = 0.1 ) fhat_both <- npcdens( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_both ) fit_both <- fitted(fhat_both) pred_both <- predict( fhat_both, newdata = nd_slice, proper.control = ctrl_both ) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), and compute the # likelihood cross-validated bandwidths (default) using a second-order # Gaussian kernel (default). Note - this may take a minute or two # depending on the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { # First, compute the bandwidths... note that this may take a minute or # two depending on the speed of your computer. bw <- npcdensbw(formula=gdp~ordered(year), nmulti=1) # Next, compute the condensity object... fhat <- npcdens(bws=bw) # The object fhat now contains results such as the estimated conditional # density function (fhat$condens) and so on... summary(fhat) # Call the plot() function to visualize the results (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), and compute the # likelihood cross-validated bandwidths (default) using a second-order # Gaussian kernel (default). Note - this may take a minute or two # depending on the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { # First, compute the bandwidths... note that this may take a minute or # two depending on the speed of your computer. # Note - we cast `X' and `y' as data frames so that plot() can # automatically grab names (this looks like overkill, but in # multivariate settings you would do this anyway, so may as well get in # the habit). X <- data.frame(year=ordered(year)) y <- data.frame(gdp) bw <- npcdensbw(xdat=X, ydat=y, nmulti=1) # Next, compute the condensity object... fhat <- npcdens(bws=bw) # The object fhat now contains results such as the estimated conditional # density function (fhat$condens) and so on... summary(fhat) # Call the plot() function to visualize the results (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=FORMULA): For this example, we load the old # faithful geyser data from the R `datasets' library and compute the # conditional density function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npcdensbw(formula=eruptions~waiting, nmulti=1) summary(bw) # Plot the density function (<ctrl>-C will interrupt on *NIX systems, # <esc> will interrupt on MS Windows systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=DATA FRAME): For this example, we load the old # faithful geyser data from the R `datasets' library and compute the # conditional density function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... # Note - we cast `X' and `y' as data frames so that plot() can # automatically grab names (this looks like overkill, but in # multivariate settings you would do this anyway, so may as well get in # the habit). X <- data.frame(waiting) y <- data.frame(eruptions) bw <- npcdensbw(xdat=X, ydat=y, nmulti=1) summary(bw) # Plot the density function (<ctrl>-C will interrupt on *NIX systems, # <esc> will interrupt on MS Windows systems) if (interactive()) plot(bw) }) # EXAMPLE 3 (INTERFACE=FORMULA): Replicate the DGP of Klein & Spady # (1993) (see their description on page 405, pay careful attention to # footnote 6 on page 405). set.seed(123) n <- 300 # x1 is chi-squared having 3 df truncated at 6 standardized by # subtracting 2.348 and dividing by 1.511 x <- rchisq(n, df=3) x1 <- (ifelse(x < 6, x, 6) - 2.348)/1.511 # x2 is normal (0, 1) truncated at +- 2 divided by 0.8796 x <- rnorm(n) x2 <- ifelse(abs(x) < 2 , x, 2) / 0.8796 # y is 1 if y* > 0, 0 otherwise. y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) data.train <- data.frame(y = factor(y), x1 = x1, x2 = x2) # Generate data-driven bandwidths (likelihood cross-validation). Note - # this may take a few minutes depending on the speed of your computer... bw <- npcdensbw(formula=y~x1+x2, data=data.train, nmulti=1) # Next, create the evaluation data in order to generate a perspective # plot x1.seq <- seq(min(x1), max(x1), length=30) x2.seq <- seq(min(x2), max(x2), length=30) X.eval <- expand.grid(x1=x1.seq,x2=x2.seq) data.eval <- data.frame( y=factor(rep(1, nrow(X.eval)), levels=levels(data.train$y)), x1=X.eval[,1], x2=X.eval[,2] ) # Now evaluate the conditional probability for y=1 and for the # evaluation Xs fit <- fitted(npcdens(bws=bw,newdata=data.eval)) # Finally, coerce the data into a matrix for plotting with persp() fit.mat <- matrix(fit, 30, 30) # Generate a perspective plot similar to Figure 2 b of Klein and Spady # (1993) persp(x1.seq, x2.seq, fit.mat, col="white", ticktype="detailed", expand=0.5, axes=FALSE, box=FALSE, main="Estimated Nonparametric Probability Perspective", theta=310, phi=25) # EXAMPLE 3 (INTERFACE=DATA FRAME): Replicate the DGP of Klein & Spady # (1993) (see their description on page 405, pay careful attention to # footnote 6 on page 405). set.seed(123) n <- 300 # x1 is chi-squared having 3 df truncated at 6 standardized by # subtracting 2.348 and dividing by 1.511 x <- rchisq(n, df=3) x1 <- (ifelse(x < 6, x, 6) - 2.348)/1.511 # x2 is normal (0, 1) truncated at +- 2 divided by 0.8796 x <- rnorm(n) x2 <- ifelse(abs(x) < 2 , x, 2) / 0.8796 # y is 1 if y* > 0, 0 otherwise. y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) # Create the X matrix X <- cbind(x1, x2) y.factor <- factor(y) # Generate data-driven bandwidths (likelihood cross-validation). Note - # this may take a few minutes depending on the speed of your computer... bw <- npcdensbw(xdat=X, ydat=y.factor, nmulti=1) # Next, create the evaluation data in order to generate a perspective # plot x1.seq <- seq(min(x1), max(x1), length=30) x2.seq <- seq(min(x2), max(x2), length=30) X.eval <- expand.grid(x1=x1.seq,x2=x2.seq) # Now evaluate the conditional probability for y=1 and for the # evaluation Xs fit <- fitted(npcdens(exdat=X.eval, eydat=factor(rep(1, nrow(X.eval)), levels=levels(y.factor)), bws=bw)) # Finally, coerce the data into a matrix for plotting with persp() fit.mat <- matrix(fit, 30, 30) # Generate a perspective plot similar to Figure 2 b of Klein and Spady # (1993) persp(x1.seq, x2.seq, fit.mat, col="white", ticktype="detailed", expand=0.5, axes=FALSE, box=FALSE, main="Estimated Nonparametric Probability Perspective", theta=310, phi=25) # EXAMPLE 4: Variations on local polynomial conditional density # estimation with proper = TRUE. data("Italy") # Work in years relative to 1975 to condition the raw polynomial basis. # Calendar year = model year + year.offset, also for prediction data. year.offset <- 1975 Italy2 <- within(Italy, { year <- as.numeric(as.character(year)) - year.offset }) # Plot only: make the plotted surface proper on the plot evaluation grid. fhat <- npcdens(gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1) plot(fhat, proper = TRUE) # Fit an object whose fitted values are themselves proper. ctrl_fit <- list( mode = "slice", apply = "fitted", slice.grid.size = 101L, slice.extend.factor = 0.1 ) fhat_fit <- npcdens( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_fit ) fit_proper <- fitted(fhat_fit) fit_raw <- fhat_fit$condens.raw # Display the repaired and raw fitted values for cases where the raw # fitted density is negative. head(cbind(fit_proper, fit_raw)[which(fit_raw < 0), ]) # Predict on a common explicit y-grid for several years, and render # those predictions proper. g.grid <- seq(min(Italy2$gdp), max(Italy2$gdp), length.out = 200) nd_grid <- expand.grid( gdp = g.grid, year = c(1955, 1975, 1995) - year.offset ) pred_grid <- predict(fhat, newdata = nd_grid, proper = TRUE) # Predict on paired rows with different gdp grids by year, and still # make the predictions proper via slice mode. g1 <- seq(quantile(Italy2$gdp, 0.10), quantile(Italy2$gdp, 0.60), length.out = 60) g2 <- seq(quantile(Italy2$gdp, 0.30), quantile(Italy2$gdp, 0.90), length.out = 35) nd_slice <- rbind( data.frame(gdp = g1, year = rep(1960 - year.offset, length(g1))), data.frame(gdp = g2, year = rep(1985 - year.offset, length(g2))) ) pred_slice <- predict( fhat, newdata = nd_slice, proper = TRUE, proper.control = list(mode = "slice") ) # One object that carries properization for fitted values and for later # predict() calls. ctrl_both <- list( mode = "slice", apply = "both", slice.grid.size = 101L, slice.extend.factor = 0.1 ) fhat_both <- npcdens( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_both ) fit_both <- fitted(fhat_both) pred_both <- predict( fhat_both, newdata = nd_slice, proper.control = ctrl_both ) ## End(Not run)
npcdensbw computes a conbandwidth object for
estimating the conditional density of a -variate kernel
density estimator defined over mixed continuous and discrete
(unordered, ordered) data using either the normal-reference
rule-of-thumb, likelihood cross-validation, or least-squares cross
validation using the method of Hall, Racine, and Li (2004).
npcdensbw(...) ## S3 method for class 'formula' npcdensbw(formula, data, subset, na.action, call, ...) ## S3 method for class 'conbandwidth' npcdensbw(xdat = stop("data 'xdat' missing"), ydat = stop("data 'ydat' missing"), bws, bandwidth.compute = TRUE, cfac.dir = 2.5*(3.0-sqrt(5)), scale.factor.init = 0.5, dfac.dir = 0.25*(3.0-sqrt(5)), dfac.init = 0.375, dfc.dir = 3, ftol = 1.490116e-07, scale.factor.init.upper = 2.0, hbd.dir = 1, hbd.init = 0.9, initc.dir = 1.0, initd.dir = 1.0, invalid.penalty = c("baseline","dbmax"), itmax = 10000, lbc.dir = 0.5, scale.factor.init.lower = 0.1, lbd.dir = 0.1, lbd.init = 0.1, memfac = 500, nmulti, penalty.multiplier = 10, nomad.remin = FALSE, powell.remin = TRUE, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample = FALSE, scale.factor.search.lower = NULL, cvls.quadrature.grid = NULL, cvls.quadrature.extend.factor = NULL, cvls.quadrature.points = NULL, cvls.quadrature.ratios = NULL, small = 1.490116e-05, tol = 1.490116e-04, transform.bounds = FALSE, ..., nomad.opts = list()) ## Default S3 method: npcdensbw(xdat = stop("data 'xdat' missing"), ydat = stop("data 'ydat' missing"), bws, bandwidth.compute = TRUE, bwmethod, bwscaling, bwtype, cfac.dir, scale.factor.init, cxkerbound, cxkerlb, cxkerorder, cxkertype, cxkerub, cykerbound, cykerlb, cykerorder, cykertype, cykerub, dfac.dir, dfac.init, dfc.dir, ftol, scale.factor.init.upper, hbd.dir, hbd.init, initc.dir, initd.dir, invalid.penalty, itmax, lbc.dir, scale.factor.init.lower, lbd.dir, lbd.init, memfac, nmulti, oxkertype, oykertype, penalty.multiplier, nomad.remin = FALSE, powell.remin, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample, scale.factor.search.lower = NULL, cvls.quadrature.grid = c("hybrid", "uniform", "sample"), cvls.quadrature.extend.factor = 1, cvls.quadrature.points = c(100L, 50L), cvls.quadrature.ratios = c(0.20, 0.55, 0.25), small, tol, transform.bounds, uxkertype, uykertype, regtype = c("lc", "ll", "lp"), basis = c("glp", "additive", "tensor"), degree = NULL, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, bernstein.basis = FALSE, ..., nomad.opts = list())npcdensbw(...) ## S3 method for class 'formula' npcdensbw(formula, data, subset, na.action, call, ...) ## S3 method for class 'conbandwidth' npcdensbw(xdat = stop("data 'xdat' missing"), ydat = stop("data 'ydat' missing"), bws, bandwidth.compute = TRUE, cfac.dir = 2.5*(3.0-sqrt(5)), scale.factor.init = 0.5, dfac.dir = 0.25*(3.0-sqrt(5)), dfac.init = 0.375, dfc.dir = 3, ftol = 1.490116e-07, scale.factor.init.upper = 2.0, hbd.dir = 1, hbd.init = 0.9, initc.dir = 1.0, initd.dir = 1.0, invalid.penalty = c("baseline","dbmax"), itmax = 10000, lbc.dir = 0.5, scale.factor.init.lower = 0.1, lbd.dir = 0.1, lbd.init = 0.1, memfac = 500, nmulti, penalty.multiplier = 10, nomad.remin = FALSE, powell.remin = TRUE, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample = FALSE, scale.factor.search.lower = NULL, cvls.quadrature.grid = NULL, cvls.quadrature.extend.factor = NULL, cvls.quadrature.points = NULL, cvls.quadrature.ratios = NULL, small = 1.490116e-05, tol = 1.490116e-04, transform.bounds = FALSE, ..., nomad.opts = list()) ## Default S3 method: npcdensbw(xdat = stop("data 'xdat' missing"), ydat = stop("data 'ydat' missing"), bws, bandwidth.compute = TRUE, bwmethod, bwscaling, bwtype, cfac.dir, scale.factor.init, cxkerbound, cxkerlb, cxkerorder, cxkertype, cxkerub, cykerbound, cykerlb, cykerorder, cykertype, cykerub, dfac.dir, dfac.init, dfc.dir, ftol, scale.factor.init.upper, hbd.dir, hbd.init, initc.dir, initd.dir, invalid.penalty, itmax, lbc.dir, scale.factor.init.lower, lbd.dir, lbd.init, memfac, nmulti, oxkertype, oykertype, penalty.multiplier, nomad.remin = FALSE, powell.remin, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample, scale.factor.search.lower = NULL, cvls.quadrature.grid = c("hybrid", "uniform", "sample"), cvls.quadrature.extend.factor = 1, cvls.quadrature.points = c(100L, 50L), cvls.quadrature.ratios = c(0.20, 0.55, 0.25), small, tol, transform.bounds, uxkertype, uykertype, regtype = c("lc", "ll", "lp"), basis = c("glp", "additive", "tensor"), degree = NULL, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, bernstein.basis = FALSE, ..., nomad.opts = list())
These arguments identify the data, formula interface, and whether bandwidths are supplied or computed.
bandwidth.compute |
a logical value which specifies whether to do a numerical search for
bandwidths or not. If set to |
bws |
a bandwidth specification. This can be set as a |
call |
the original function call. This is passed internally by
|
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
formula |
a symbolic description of variables on which bandwidth selection is to be performed. The details of constructing a formula are described below. |
na.action |
a function which indicates what should happen when the data contain
|
subset |
an optional vector specifying a subset of observations to be used in the fitting process. |
xdat |
a |
ydat |
a |
These arguments control automatic local-polynomial degree search when regtype="lp".
degree.max |
optional scalar or integer vector giving upper bounds for automatic
degree search over continuous |
degree.max.cycles |
positive integer giving the maximum number of coordinate-search
sweeps over the degree vector. Ignored for |
degree.min |
optional scalar or integer vector giving lower bounds for automatic
degree search over continuous |
degree.restarts |
non-negative integer giving the number of additional deterministic
coordinate-search restarts. Ignored for |
degree.select |
character string controlling local-polynomial degree handling when
|
degree.start |
optional starting degree vector for automatic coordinate search. If
omitted, the search starts from the degree-zero local-constant
baseline on the continuous |
degree.verify |
logical value indicating whether a coordinate-search solution should
be exhaustively verified over the admissible degree grid after the
heuristic phase completes. Available only for
|
These arguments choose the selection criterion and the way continuous bandwidths are represented.
bwmethod |
which method to use to select
bandwidths. |
bwscaling |
a logical value that when set to |
bwtype |
character string used for the continuous variable bandwidth type,
specifying the type of bandwidth to compute and return in the
|
These controls set categorical search starts and categorical direction-set initialization.
dfac.dir |
stretch factor for direction set search for Powell's algorithm for categorical variables. See Details |
dfac.init |
non-random initial values for scale factors for categorical variables for Powell's algorithm. See Details |
hbd.dir |
upper bound for direction set search for Powell's algorithm for categorical variables. See Details |
hbd.init |
upper bound for scale factors for categorical variables for Powell's algorithm. See Details |
initd.dir |
initial non-random values for direction set search for Powell's algorithm for categorical variables. See Details |
lbd.dir |
lower bound for direction set search for Powell's algorithm for categorical variables. See Details |
lbd.init |
lower bound for scale factors for categorical variables for Powell's algorithm. See Details |
scale.init.categorical.sample |
a logical value that when set
to |
These controls set Powell direction-set initialization for continuous variables.
cfac.dir |
stretch factor for direction set search for Powell's algorithm for |
dfc.dir |
chi-square degrees of freedom for direction set search for Powell's algorithm for |
initc.dir |
initial non-random values for direction set search for Powell's algorithm for |
lbc.dir |
lower bound for direction set search for Powell's algorithm for |
These controls choose and parameterize bounded support for continuous kernels.
cxkerbound |
character string controlling continuous-kernel support handling for
|
cxkerlb |
numeric scalar/vector of lower bounds for continuous |
cxkerub |
numeric scalar/vector of upper bounds for continuous |
cykerbound |
character string controlling continuous-kernel support handling for
|
cykerlb |
numeric scalar/vector of lower bounds for continuous |
cykerub |
numeric scalar/vector of upper bounds for continuous |
These controls define deterministic and random continuous scale-factor starts and the lower admissibility floor for fixed-bandwidth search.
scale.factor.init |
deterministic initial scale factor for continuous fixed-bandwidth
search. Defaults to |
scale.factor.init.lower |
lower endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.init.upper |
upper endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.search.lower |
optional nonnegative scalar giving the hard lower admissibility
bound for continuous fixed-bandwidth search candidates. Defaults to
|
These controls choose continuous, unordered, and ordered kernels for xdat and ydat.
cxkerorder |
numeric value specifying kernel order for
|
cxkertype |
character string used to specify the continuous kernel type for
|
cykerorder |
numeric value specifying kernel order for
|
cykertype |
character string used to specify the continuous kernel type for
|
oxkertype |
character string used to specify the ordered categorical kernel
type for |
oykertype |
character string used to specify the ordered categorical kernel
type for |
uxkertype |
character string used to specify the unordered categorical kernel
type for |
uykertype |
character string used to specify the unordered categorical kernel
type for |
These controls tune quadrature for bounded continuous-response least-squares cross-validation.
cvls.quadrature.extend.factor |
a positive finite scalar controlling the finite numerical integration
window used by bounded conditional-density |
cvls.quadrature.grid |
character string specifying the one-dimensional bounded |
cvls.quadrature.points |
a two-element integer vector giving the bounded |
cvls.quadrature.ratios |
a three-element non-negative numeric vector summing to one, giving the
uniform, ranked sample- |
When response-side bounds are set explicitly to fixed infinite endpoints,
bounded cv.ls uses a finite numerical quadrature surrogate over the
data range extended by cvls.quadrature.extend.factor. In that edge
case, callers who want tighter agreement with the ordinary unbounded
convolution route should set cvls.quadrature.points explicitly.
These arguments control the local-polynomial estimator, basis, and fixed degree specification.
basis |
character string specifying the polynomial basis used when
|
bernstein.basis |
logical value controlling the stabilized representation for
|
degree |
integer scalar or integer vector of polynomial degrees for
continuous |
regtype |
character string specifying the conditional local method used for
the |
These arguments control the optional NOMAD direct-search route for local-polynomial degree and bandwidth search.
nomad |
logical or character shortcut for the recommended automatic local-polynomial
NOMAD route. When |
nomad.nmulti |
non-negative integer controlling the inner
the native crs NOMAD C API multistart count used within each outer
NOMAD restart when |
nomad.opts |
optional named list of native NOMAD parameters forwarded to the
crs NOMAD C API for NOMAD-backed bandwidth searches.
|
nomad.remin |
logical flag controlling the optional second NOMAD hot start. When
|
search.engine |
character string controlling the automatic local-polynomial search
backend when |
These controls set optimizer tolerances, restart behavior, invalid-candidate penalties, memory blocking, and bounded search transformations.
ftol |
fractional tolerance on the value of the cross-validation function
evaluated at located minima (of order the machine precision or
perhaps slightly larger so as not to be diddled by
roundoff). Defaults to |
invalid.penalty |
a character string specifying the penalty
used when the optimizer encounters invalid bandwidths.
|
itmax |
integer number of iterations before failure in the numerical
optimization routine. Defaults to |
memfac |
The algorithm to compute the least-squares objective function uses a block-based algorithm to eliminate or minimize redundant kernel evaluations. Due to memory, hardware and software constraints, a maximum block size must be imposed by the algorithm. This block size is roughly equal to memfac*10^5 elements. Empirical tests on modern hardware find that a memfac of 500 performs well. If you experience out of memory errors, or strange behaviour for large data sets (>100k elements) setting memfac to a lower value may fix the problem. |
nmulti |
integer number of times to restart the process of finding extrema of the cross-validation function from different (random) initial points |
penalty.multiplier |
a numeric multiplier applied to the
baseline penalty when |
powell.remin |
logical flag controlling Powell restart-from-minimum behavior. For
ordinary fixed-degree Powell-style search, |
bwsolver |
bandwidth optimizer for fixed-degree searches. The default
|
small |
a small number used to bracket a minimum (it is hopeless to ask for
a bracketing interval of width less than sqrt(epsilon) times its
central value, a fractional width of only about 10-04 (single
precision) or 3x10-8 (double precision)). Defaults to |
tol |
tolerance on the position of located minima of the cross-validation
function (tol should generally be no smaller than the square root of
your machine's floating point precision). Defaults to |
transform.bounds |
a logical value that when set to |
These arguments collect remaining controls passed through S3 methods.
... |
additional arguments supplied to specify the bandwidth type, kernel types, selection methods, and so on, detailed below. |
Formula bandwidth objects retain the prepared training sample (after alignment,
subsetting and missing-value handling) and the resolved missing-value policy.
Later refits use that sample even if constructor variables are rebound.
Supplying explicit training data to the estimator replaces the training data;
evaluation via newdata does not. Retention requires storage proportional
to the sample size times the number of variables, not a pairwise weight matrix.
Older saved objects without this retained state still rely on their original
data bindings; rebuild their bandwidth object from the intended data before
changing those bindings. User-defined transformation and missing-value
functions should not rely on subsequently modified closure state.
Beta associated kernels may be selected independently with
cxkertype="beta" and cykertype="beta". Orders 2, 4, 6,
and 8, fixed/generalized-NN/adaptive-NN bandwidths,
cxkerbound/cykerbound equal to "fixed" or
"range", explicit bandwidth objects, and automatic
cv.ml/cv.ls search are supported. Normal-reference selection
is not. Beta kernels act on continuous coordinates alongside the
kernels for categorical coordinates. Local-constant, local-linear and
local-polynomial fits are supported. Local-constant gradients with respect to X are
available: a beta X coordinate uses its analytic evaluation-coordinate PDF
derivative, while the beta or legacy Y density factor is held fixed. Exact
matching beta-X endpoints use structural cancellation in the normalized
ratio and can yield signed infinity or NA when a finite derivative
does not exist. Bounded
beta-response cv.ls uses Y-support quadrature of the actual estimator
with cached X weights. Signed orders 4, 6, and 8 are not positivity-repaired.
The scale.factor.* controls are dimensionless search
controls. The package converts scale factors to bandwidths using the
estimator-specific scaling encoded in the bandwidth object, including
kernel order and the number of continuous variables relevant for the
estimator. Users should not pre-multiply these controls by sample-size
or standard-deviation factors.
scale.factor.init controls the deterministic first search
start. scale.factor.init.lower and
scale.factor.init.upper define the random multistart interval.
scale.factor.search.lower is the lower admissibility bound for
continuous fixed-bandwidth search candidates. The effective first
start is max(scale.factor.init, scale.factor.search.lower),
and the effective random-start lower endpoint is
max(scale.factor.init.lower, scale.factor.search.lower).
scale.factor.init.upper must be at least that effective lower
endpoint; the package errors rather than silently expanding the user's
interval.
When scale.factor.search.lower is NULL, an existing
bandwidth object's stored floor is inherited when available;
otherwise the package default 0.1 is used. Explicit bandwidths
supplied for storage with bandwidth.compute = FALSE are not
rewritten by the search floor.
For automatic fixed-bandwidth CVLS with a beta response kernel,
repeated complete observations at a declared response endpoint require an
explicitly positive resolved scale.factor.search.lower. The default
0.1 already satisfies this requirement. Endpoint repetitions can
cause the criterion to prefer vanishing bandwidths; this is a conservative
search-admissibility policy, not a claim that every such sample has a
divergent criterion. Manual bandwidth evaluation and nearest-neighbor
searches remain available. No positive floor is silently substituted for
an explicitly requested zero.
A selected scale factor at this floor is a boundary solution of the
constrained search, not evidence of an interior optimum. In particular,
endpoint observations can make beta CVLS sensitive to the chosen floor.
For a returned fixed-bandwidth object bw, inspect
bw$sfactor$x[bw$ixcon] and bw$sfactor$y[bw$iycon] alongside
bw$scale.factor.search.lower; physical bandwidths are on a
different scale and should not be compared directly with this dimensionless
bound. Near-bound solutions merit the same sensitivity consideration, but
proximity alone does not prove that the unconstrained criterion diverges.
Changing the floor changes the admissible search problem.
Categorical search-start controls such as dfac.init,
lbd.init, and hbd.init have separate semantics and are
not affected by scale.factor.search.lower.
For bwmethod="cv.ml", the ordinary contribution is based on
. Compact-support kernels can yield
zero leave-one-out conditional-density estimates, and local-polynomial
or higher-order-kernel fits can yield negative estimates. In those
cases the package optimizes a guarded CVML criterion rather than the
literal log likelihood. Every represented strictly positive fitted value,
including a positive subnormal value retained in log form, uses the
ordinary branch . Let
denote the positive machine floor used only to
encode an invalid nonpositive contribution. Exact zero and negative values
with magnitude no greater than use
; negative values of larger magnitude
use the smooth penalty
.
The guarded count reported in bandwidth summaries records
objective evaluations containing an invalid nonpositive contribution; a
positive value is not guarded merely because it is small. The
bwmethod="cv.ls" criterion remains well defined for negative
kernel density estimates and is not modified by this CVML guard.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot, plot.np for plotting options.
The bandwidth-selection argument surface is easiest to read by
decision group. Start with the data and bandwidth inputs
(xdat, ydat, bws, and
bandwidth.compute), then choose the bandwidth criterion and
representation (bwmethod, bwscaling, and
bwtype). Next choose continuous kernel and support controls
(cxker* and cyker*), categorical kernel controls
(uxkertype, uykertype, oxkertype, and
oykertype), and numerical search controls including
nmulti, tolerances, penalties, and the scale.factor.*
search-start and admissibility controls. Bounded continuous-response
cv.ls fits may also use the cvls.quadrature.*
controls. Local-polynomial and NOMAD controls
(regtype, basis, degree*,
search.engine, nomad, nomad.nmulti, and
bernstein.basis) are relevant when using the explicit
local-polynomial route.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
npcdensbw implements a variety of methods for choosing
bandwidths for multivariate distributions (-variate) defined
over a set of possibly continuous and/or discrete (unordered, ordered)
data. The approach is based on Li and Racine (2004) who employ
‘generalized product kernels’ that admit a mix of continuous
and discrete data types.
The cross-validation methods employ multivariate numerical search
algorithms. For fixed local-constant/local-linear fits, and for
local-polynomial fits with degree.select="manual", bandwidth
search uses multidimensional Powell direction-set optimization.
Bandwidths can (and will) differ for each variable which is, of course, desirable.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating
the density at the point . Generalized nearest-neighbor
bandwidths change with the point at which the density is estimated,
. Fixed bandwidths are constant over the support of .
For unbounded Gaussian, Epanechnikov, and uniform kernels,
bwmethod="cv.ls" with bwtype="generalized_nn" integrates
the squared leave-one-out conditional density over the full response
support, allowing response bandwidths to vary with the response evaluation
point. This requires additional integration work compared with the
analytical convolutions available for fixed and adaptive nearest-neighbor
bandwidths.
This whole-response criterion also applies to beta predictor kernels and bounded Gaussian predictor kernels when the response domain is unbounded. Predictor boundary correction does not make the response bandwidth constant.
Ambiguous local QR rank in a conditional local-polynomial design uses the existing original-coordinate rank/ridge admission. If a numerical evaluation remains unusable, including a failed coefficient accuracy check or exhausted integration limits, it receives the existing invalid-evaluation penalty and search continues. A penalty is not a verified cross-validation score; the final selected bandwidth must pass the existing raw-objective validation.
Computation time depends on the kernels, nearest-neighbor counts, predictor
and response dimensions, and local-polynomial specification. Some
configurations can be substantially more expensive. Second-order kernels
are the usual practical choice; higher-order kernels remain supported.
The cvls.quadrature.* controls described above apply to bounded
response integration, not this unbounded generalized-neighbor calculation.
Exact ties can make the literal th continuous nearest-neighbor
radius zero. Such a bandwidth is undefined and is rejected; see
np.kernels for the precise contract and remedies.
npcdensbw may be invoked either with a formula-like
symbolic
description of variables on which bandwidth selection is to be
performed or through a simpler interface whereby data is passed
directly to the function via the xdat and ydat
parameters. Use of these two interfaces is mutually exclusive.
Data contained in the data frames xdat and ydat may be a
mix of continuous (default), unordered discrete (to be specified in
the data frames using factor), and ordered discrete (to be
specified in the data frames using ordered). Data can be
entered in an arbitrary order and data types will be detected
automatically by the routine (see np for details).
Data for which bandwidths are to be estimated may be specified
symbolically. A typical description has the form dependent data
~ explanatory data,
where dependent data and explanatory data are both
series of variables specified by name, separated by
the separation character '+'. For example, y1 + y2 ~ x1 + x2
specifies that the bandwidths for the joint distribution of variables
y1 and y2 conditioned on x1 and x2 are to
be estimated. See below for further examples.
Response expressions such as log(y) or I(y^2) are not
supported on the left-hand side and are rejected. Instead create, for
example, data$log_y <- log(data$y) and use log_y ~ x, or
supply the transformed response through ydat. Right-hand-side
offset() special terms are also unsupported and are rejected rather
than omitted. These checks do not evaluate response expressions, alter
stored/dynamically constructed formulas, or change supported explanatory
transformations.
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth order Gaussian and Epanechnikov kernels, and the uniform kernel. Unordered discrete data types use a variation on Aitchison and Aitken's (1976) kernel, while ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
When regtype="lp" and degree.select != "manual",
npcdensbw can jointly determine the xdat-side local
polynomial degree vector and the fixed bandwidth coordinates entering
the conditional density criterion. With
search.engine="cell", the criterion is profiled over the
admissible degree grid using cached coordinate-wise or exhaustive
search. With search.engine="nomad" or
"nomad+powell", the criterion is optimized directly over the
joint degree/bandwidth space using the native crs NOMAD C API;
"nomad+powell" then performs one Powell hot start from the
NOMAD solution and keeps the better of the direct NOMAD and polished
answers. This polynomial-adaptive joint-search route is motivated by
Hall and Racine (2015) together with Li, Li, and Racine (under
revision). When bernstein.basis is not explicitly supplied,
the automatic search route defaults to bernstein.basis=TRUE
for numerical stability.
Setting nomad=TRUE is a convenience preset for this automatic
LP route, not a generic optimizer alias. For conditional density
bandwidth selection it expands any missing values to the equivalent
long-form call
npcdensbw(...,
regtype = "lp",
search.engine = "nomad+powell",
degree.select = "coordinate",
bernstein.basis = TRUE,
degree.min = 0L,
degree.max = 10L,
degree.verify = FALSE,
bwtype = "fixed")
Compatible explicit tuning arguments are respected. Incompatible
explicit settings fail fast so the shortcut never silently changes
user-selected semantics.
The character value nomad="auto" applies the same LP
shortcut but leaves search.engine and degree.select
eligible for data-driven resolution when both were not supplied
explicitly: scalar continuous degree searches use the exhaustive
degree-grid route, while higher-dimensional degree searches keep the
NOMAD/Powell route. Explicit search.engine or
degree.select choices are honored.
The optimizer invoked for search is Powell's conjugate direction
method which requires the setting of (non-random) initial values and
search directions for bandwidths, and, when restarting, random values
for successive invocations. Bandwidths for numeric variables
are scaled by robust measures of spread, the sample size, and the
number of numeric variables where appropriate. Two sets of
parameters for bandwidths for numeric can be modified, those
for initial values for the parameters themselves, and those for the
directions taken (Powell's algorithm does not involve explicit
computation of the function's gradient). The default values are set by
considering search performance for a variety of difficult test cases
and simulated cases. We highly recommend restarting search a large
number of times to avoid the presence of local minima (achieved by
modifying nmulti). Further refinement for difficult cases can
be achieved by modifying these sets of parameters. However, these
parameters are intended more for the authors of the package to enable
‘tuning’ for various methods rather than for the user themselves.
npcdensbw returns a conbandwidth object, with the
following components:
xbw |
bandwidth(s), scale factor(s) or nearest neighbours for the
explanatory data, |
ybw |
bandwidth(s), scale factor(s) or nearest neighbours for the
dependent data, |
fval |
objective function value at minimum |
if bwtype is set to fixed, an object containing
bandwidths (or scale factors if bwscaling = TRUE) is
returned. If it is set to generalized_nn or adaptive_nn,
then instead the th nearest neighbors are returned for the
continuous variables while the discrete kernel bandwidths are returned
for the discrete variables.
Prediction follows a two-stage contract. Calling predict(bw)
on the returned bandwidth object is a convenience forwarder for
npcdens(bws = bw) and returns a fitted condensity
object; it does not return a numeric vector of conditional-density
estimates. Call fitted(fit) or
predict(fit, newdata = ...) on that fitted object to obtain
numeric results. The canonical workflow is
bw <- npcdensbw(y ~ x, data = mydata)
fit <- predict(bw) # equivalent to npcdens(bws = bw)
fitted(fit)
predict(fit, newdata = newdata)
The functions summary and plot also
support conbandwidth objects.
Local-polynomial search uses the numerical-ridging policies described in
npreg; see Seifert and Gasser (2000) there.
npcdensbw selects response and conditioning bandwidths, and
when requested local-polynomial degree/search metadata, for the
conditional density target estimated by
npcdens.
For book-length derivations, see Li and Racine (2007), Chapter 5 Conditional Density Estimation, especially Sections 5.1-5.4, and Chapter 4 Kernel Estimation with Mixed Data. The later workflow treatment is Racine (2019), Chapter 4 Conditional Probability Density and Cumulative Distribution Functions.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Caution: multivariate data-driven bandwidth selection methods are, by
their nature, computationally intensive. Virtually all methods
require dropping the th observation from the data set, computing an
object, repeating this for all observations in the sample, then
averaging each of these leave-one-out estimates for a given
value of the bandwidth vector, and only then repeating this a large
number of times in order to conduct multivariate numerical
minimization/maximization. Furthermore, due to the potential for local
minima/maxima, restarting this procedure a large number of times may
often be necessary. This can be frustrating for users possessing
large datasets. For exploratory purposes, you may wish to override the
default search tolerances, say, setting ftol=.01 and tol=.01 and
conduct multistarting (the default is to restart min(2, ncol(xdat,ydat))
times) as is done for a number of examples. Once the procedure
terminates, you can restart search with default tolerances using those
bandwidths obtained from the less rigorous search (i.e., set
bws=bw on subsequent calls to this routine where bw is
the initial bandwidth object). A version of this package using the
Rmpi wrapper is under development that allows one to deploy
this software in a clustered computing environment to facilitate
computation involving large datasets.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Hall, P. and J.S. Racine and Q. Li (2004), “Cross-validation and the estimation of conditional probability densities,” Journal of the American Statistical Association, 99, 1015-1026.
Hall, P. and J.S. Racine (2015), “Infinite Order Cross-Validated Local Polynomial Regression,” Journal of Econometrics, 185, 510-525.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, A. and Q. Li and J.S. Racine (under revision), “Boundary Adjusted, Polynomial Adaptive, Nonparametric Kernel Conditional Density Estimation,” Econometric Reviews.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Scott, D.W. (1992), Multivariate Density Estimation. Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np
bw.nrd, bw.SJ, hist,
npudens, npudist
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we compute the # likelihood cross-validated bandwidths (default) using a second-order # Gaussian kernel (default). Note - this may take a minute or two # depending on the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { bw <- npcdensbw(formula=gdp~ordered(year), nmulti=1) # The object bw can be used for further estimation using # npcdens(), plotting using plot() etc. Entering the name of # the object provides useful summary information, and names() will also # provide useful information. summary(bw) # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we compute the # likelihood cross-validated bandwidths (default) using a second-order # Gaussian kernel (default). Note - this may take a minute or two # depending on the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { bw <- npcdensbw(xdat=ordered(year), ydat=gdp, nmulti=1) # The object bw can be used for further estimation using # npcdens(), plotting using plot() etc. Entering the name of # the object provides useful summary information, and names() will also # provide useful information. summary(bw) # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. }) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we compute the # likelihood cross-validated bandwidths (default) using a second-order # Gaussian kernel (default). Note - this may take a minute or two # depending on the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { bw <- npcdensbw(formula=gdp~ordered(year), nmulti=1) # The object bw can be used for further estimation using # npcdens(), plotting using plot() etc. Entering the name of # the object provides useful summary information, and names() will also # provide useful information. summary(bw) # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we compute the # likelihood cross-validated bandwidths (default) using a second-order # Gaussian kernel (default). Note - this may take a minute or two # depending on the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { bw <- npcdensbw(xdat=ordered(year), ydat=gdp, nmulti=1) # The object bw can be used for further estimation using # npcdens(), plotting using plot() etc. Entering the name of # the object provides useful summary information, and names() will also # provide useful information. summary(bw) # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. }) ## End(Not run)
Constructs the conditional density hat operator associated with
npcdens bandwidth objects. The returned operator maps a
right-hand side y to ; with y = 1 this reproduces the
fitted conditional density.
npcdenshat(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), exdat, eydat, y = NULL, output = c("matrix", "apply"), deriv = NULL, s = NULL)npcdenshat(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), exdat, eydat, y = NULL, output = c("matrix", "apply"), deriv = NULL, s = NULL)
These arguments identify the fitted bandwidth object, training data, and evaluation data.
bws |
A fitted conditional density bandwidth object of class |
exdat |
Optional evaluation conditioning data. If omitted, the operator is built on the training conditioning data. |
eydat |
Optional evaluation response data. If omitted, the operator is built on the training response data. |
txdat |
Training conditioning data used to construct the operator. |
tydat |
Training response data used to construct the operator. |
These arguments control whether the operator is returned as a matrix or applied directly.
deriv |
Convenience alias for |
output |
Either |
s |
Optional first-derivative multi-index over continuous conditioning variables. By default the conditional-density operator itself is returned. When |
y |
Optional right-hand side vector or matrix with one row per training observation. |
For the adaptive-nearest-neighbour local-constant (including degree-zero
local-polynomial) ratio, every finite nonzero conditioning-weight sum is used
without an epsilon floor. If all computed conditioning weights at an external
evaluation row are zero, that row is returned as NA with a warning.
This describes computed weights, not necessarily absence of geometric support.
Zero response weights still give a valid zero numerator when the conditioning
denominator is defined. Required internal and bootstrap ratios remain strict.
For output = "matrix", the return value is a matrix with class
c("npcdenshat", "matrix") and attributes storing the bandwidth object,
training data, evaluation data, and call metadata.
For output = "apply", the function returns H y directly. Matrix
right-hand sides are applied column-wise.
The optional s argument follows the derivative multi-index convention
used by npreghat for continuous conditioning variables. The
default s = NULL returns the ordinary conditional-density hat operator.
Supplying one first derivative, for example s = 1L in a univariate
continuous- problem or s = c(x2 = 1L) in a multivariate problem,
returns the hat operator for that component of the conditional-density
gradient. This derivative route is intended to match
npcdens(..., gradients = TRUE)$congrad.
For local-constant beta X kernels, first derivatives use the analytic beta
PDF derivative. Exact support-endpoint rows whose raw weights jump are
returned as NA, because a response-free hat matrix cannot perform the
response-specific numerator/denominator cancellation available to the fitted
conditional-density estimator.
This helper is intended for object-fed repeated evaluation once a bandwidth object has already been constructed. It does not perform bandwidth selection.
Either a hat matrix of class "npcdenshat" or the applied result
H y, depending on output.
## Not run: data(cps71) tx <- data.frame(age = cps71$age) ty <- data.frame(logwage = cps71$logwage) bw <- npcdensbw(xdat = tx, ydat = ty, bwtype = "fixed", bandwidth.compute = FALSE, bws = c(1.0, 1.0)) H <- npcdenshat(bws = bw, txdat = tx, tydat = ty) dens.hat <- npcdenshat(bws = bw, txdat = tx, tydat = ty, y = rep(1, nrow(tx)), output = "apply") dens.core <- fitted(npcdens(bws = bw, txdat = tx, tydat = ty)) head(cbind(dens.core, dens.hat), n = 2L) grad.hat <- npcdenshat(bws = bw, txdat = tx, tydat = ty, y = rep(1, nrow(tx)), output = "apply", s = 1L) grad.core <- gradients(npcdens(bws = bw, txdat = tx, tydat = ty, gradients = TRUE))[, 1L] head(cbind(grad.core, grad.hat), n = 2L) ## End(Not run)## Not run: data(cps71) tx <- data.frame(age = cps71$age) ty <- data.frame(logwage = cps71$logwage) bw <- npcdensbw(xdat = tx, ydat = ty, bwtype = "fixed", bandwidth.compute = FALSE, bws = c(1.0, 1.0)) H <- npcdenshat(bws = bw, txdat = tx, tydat = ty) dens.hat <- npcdenshat(bws = bw, txdat = tx, tydat = ty, y = rep(1, nrow(tx)), output = "apply") dens.core <- fitted(npcdens(bws = bw, txdat = tx, tydat = ty)) head(cbind(dens.core, dens.hat), n = 2L) grad.hat <- npcdenshat(bws = bw, txdat = tx, tydat = ty, y = rep(1, nrow(tx)), output = "apply", s = 1L) grad.core <- gradients(npcdens(bws = bw, txdat = tx, tydat = ty, gradients = TRUE))[, 1L] head(cbind(grad.core, grad.hat), n = 2L) ## End(Not run)
npcdist computes kernel cumulative conditional distribution
estimates on -variate evaluation data, given a set of
training data (both explanatory and dependent) and a bandwidth
specification (a condbandwidth object or a bandwidth vector,
bandwidth type, and kernel type) using the method of Li and Racine
(2008) and Li, Lin, and Racine (2013). The data may be continuous,
discrete (unordered and ordered factors), or some combination thereof.
npcdist(bws, ...) ## S3 method for class 'formula' npcdist(bws, data = NULL, newdata = NULL, ...) ## S3 method for class 'condbandwidth' npcdist(bws, txdat = stop("invoked without training data 'txdat'"), tydat = stop("invoked without training data 'tydat'"), exdat, eydat, gradients = FALSE, gradient.order = 1L, proper = FALSE, proper.method = c("isotonic"), proper.control = list(), ..., se = FALSE) ## Default S3 method: npcdist(bws, txdat, tydat, nomad = FALSE, ...)npcdist(bws, ...) ## S3 method for class 'formula' npcdist(bws, data = NULL, newdata = NULL, ...) ## S3 method for class 'condbandwidth' npcdist(bws, txdat = stop("invoked without training data 'txdat'"), tydat = stop("invoked without training data 'tydat'"), exdat, eydat, gradients = FALSE, gradient.order = 1L, proper = FALSE, proper.method = c("isotonic"), proper.control = list(), ..., se = FALSE) ## Default S3 method: npcdist(bws, txdat, tydat, nomad = FALSE, ...)
These arguments identify the bandwidth specification, formula/data interface, and training data.
bws |
a bandwidth specification. This can be set as a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object coercible to
a data frame by |
txdat |
a |
tydat |
a |
This argument controls the recommended automatic local-polynomial NOMAD route, which jointly selects continuous polynomial degree and bandwidths when these are computed inside npcdist.
nomad |
logical shortcut passed through to |
These arguments control where the fitted conditional distribution is evaluated and which estimates are returned.
exdat |
a |
eydat |
a |
se |
logical scalar, default |
gradients |
a logical value specifying whether to return estimates of the
gradients at the evaluation points. Defaults to |
gradient.order |
derivative order for continuous explanatory-variable gradients when
|
newdata |
An optional data frame in which to look for evaluation data. If omitted, the training data are used. |
These arguments control optional post-estimation properization of the fitted conditional distribution.
proper |
a logical value specifying whether to apply post-estimation
properization to the conditional distribution estimate. Defaults to
|
proper.control |
a list of controls for properization. Supported entries are
|
proper.method |
a character string specifying the properization method. Currently
|
Further arguments are passed to npcdistbw when bandwidths are computed internally, or used to interpret a numeric bws vector.
... |
additional arguments supplied to |
Conditional fitting and replay use the literal categorical kernels for
both explanatory and response variables. Near-upper categorical bandwidths
are not replaced by approximate constant factors. The same target is used
for levels, gradients, standard errors, conditional hats, and reconstructed
plot uncertainty. This conditional-family policy does not change direct
regression or unconditional kernel-sum evaluation and does not modify the
caller's np.largelambda option.
With generalized nearest-neighbor bandwidths, query identity matters when
selecting a radius: a training observation excludes its own occurrence,
whereas explicit evaluation data remain external queries even if their
values equal training observations. Consequently,
predict(fit, newdata = training.data) can differ from
fitted(fit). This does not omit the training contribution from the
fitted estimator. See np.kernels for the radius convention.
With a formula-derived bandwidth object, supplying only tydat
replaces the evaluated response in retained-training-sample order: one row
per observation retained after the original subset and missing-value selection.
Original excluded rows are not restored; row names or equal lengths do not
imply original-data order. The effective na.action is then applied
jointly to the retained predictors and replacement response; any new omission
indices refer to this retained sample. The selected bandwidths remain fixed,
and the returned object retains the replacement sample for subsequent refits.
Use data for full formula-data replacement, not together with a partial
response replacement. Explicit native training arguments retain their separate
positional contract.
For native (non-formula) objects, named newdata columns are matched
to the retained variable names and reordered as needed. Extra columns are
ignored; missing, duplicate or ambiguous names are errors. An unnamed
matrix or vector remains positional for a single evaluation role.
Explicit native evaluation arguments retain their positional contract and
take precedence over newdata.
For a native bandwidth object, newdata is split into
exdat and eydat using the retained predictor and response
column names. Names must identify both roles unambiguously;
explicitly supplied native evaluation arguments take precedence. This
evaluates at the requested rows without repeating bandwidth selection.
For explicit external evaluation rows, a completed explanatory-kernel row
whose weights are all zero has no conditional estimate. Such rows return
NA for the fitted value and requested uncertainty or derivatives,
with one notice. A missing categorical counterfactual affects only its
contrast; it does not invalidate an otherwise supported base estimate.
A zero response-kernel contribution is not a missing explanatory row.
Supported rows retain their usual computation. Required internal evaluations
remain strict. With proper = TRUE, complete unsupported fixed-X
slices retain NA; projection still applies to supported slices.
Documentation guide: see npcdistbw for bandwidth selection and search controls, np.kernels for kernels, np.options for global options, and plot, plot.np for plotting options.
When bws is omitted, the formula and default methods call
npcdistbw first and pass bandwidth-selection arguments
from ... to that call. When bws is already a
condbandwidth object, npcdist estimates with the stored
bandwidth metadata in that object.
Beta associated kernels may be selected independently for explanatory X
coordinates (cxkertype="beta") and response Y coordinates
(cykertype="beta"). Orders 2, 4, 6, and 8, fixed/generalized-NN/
adaptive-NN bandwidths, explicit finite bounds, sample-range bounds, and
automatic cv.ls bandwidth selection are supported. Beta kernels act on continuous
coordinates alongside the kernels for categorical coordinates.
Local-constant, local-linear and local-polynomial fits are supported.
For local-constant fits, analytic first derivatives with respect to continuous X
coordinates are available with gradients=TRUE; the Y-side CDF factor
itself is not differentiated. Fixed/adaptive order-2 Y CDF
factors are proper on their declared support; generalized-NN order-2 curves
may be locally nonmonotone, and signed orders 4, 6, and 8 may also leave
. No clipping or monotone repair is applied. At exact beta-X
endpoints, numerator and denominator jumps are cancelled before classifying
the conditional-distribution gradient. A constant Y CDF factor (in
particular at its exact support endpoints) gives a structural zero
gradient. Genuine ratio jumps are reported as signed infinities and
indeterminate numerical cancellations as NA, with warnings.
Returned infinities retain that extended-real meaning. Plot methods convert
them to missing geometry only in a temporary drawing copy, leaving fitted
and plot-data objects unchanged.
For ordinary conditional-distribution level plots, bootstrap intervals
support different continuous X- and Y-side kernel families or orders,
including beta on either side. Beta-containing bootstrap levels use the
same signed log-domain conditional ratio as the fitted estimator. With
non-fixed bandwidths, np_boot_control(nonfixed="exact") reconstructs
each duplicate-row resample and recomputes its nearest-neighbour bandwidths,
while nonfixed="frozen" keeps the original fitted bandwidths. In both
modes, resolved beta "range" support bounds are replayed from the
bandwidth object rather than recomputed from bootstrap counts. This
mixed-family level-bootstrap support does not alter the separate restrictions on gradient, quantile, or bias-corrected centers.
With finite continuous response bounds, npcdist uses the
observation-centered truncated-kernel CDF documented in
np.kernels. Each response contribution is exactly zero
and one at the declared lower and upper endpoints and has the linear
uniform-CDF limit as the response bandwidth diverges.
Argument groups for bandwidth selection are documented on
npcdistbw. The most common workflow is to choose data
and bandwidth inputs first, then bandwidth criterion and
representation, then kernel/support controls, numerical search
controls, and finally local-polynomial/NOMAD controls for
polynomial-adaptive fits.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
npcdist implements a variety of methods for estimating
multivariate conditional cumulative distributions (-variate)
defined over a set of possibly continuous and/or discrete (unordered,
ordered) data. The approach is based on Li and Racine (2004) who
employ ‘generalized product kernels’ that admit a mix of
continuous and discrete data types.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating
the cumulative conditional distribution at the point
. Generalized nearest-neighbor bandwidths change with the point
at which the cumulative conditional distribution is estimated,
. Fixed bandwidths are constant over the support of .
Training and evaluation input data may be a
mix of continuous (default), unordered discrete (to be specified in
the data frames using factor), and ordered discrete (to be
specified in the data frames using ordered). Data can be
entered in an arbitrary order and data types will be detected
automatically by the routine (see np for details).
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth order Gaussian and Epanechnikov kernels, and the uniform kernel. Unordered discrete data types use a variation on Aitchison and Aitken's (1976) kernel, while ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
For practitioners who want the recommended automatic local-polynomial degree-and-bandwidth NOMAD route
without spelling out all LP tuning arguments,
npcdist(..., nomad=TRUE) and npcdistbw(..., nomad=TRUE)
expand missing settings to the same documented preset. Explicit
incompatible settings fail fast rather than being silently rewritten.
With a raw polynomial basis, high powers of poorly scaled continuous
predictors (such as uncentred calendar years) can produce severely
ill-conditioned systems. Conditional local-polynomial fits do not apply
the design-conditioning rejection used by npreg; they may return
inaccurate finite values without a warning, with or without a ridge
adjustment. Centre or scale such predictors before fitting and apply the
same transformation to all evaluation or prediction data. The explicit
bernstein.basis = TRUE representation is another option for
improving conditioning. Check numerical stability for the chosen data,
degree and bandwidths. proper = TRUE enforces probability-shape
constraints; it does not repair an ill-conditioned polynomial solve.
With regtype = "lp", gradients = TRUE and
gradient.order greater than one expose higher-order derivative
estimates with respect to continuous explanatory variables. These
derivatives use the same local-polynomial basis, degree, Bernstein
option, bandwidths, and kernels as the fitted conditional
distribution. See npreg for the complete heterogeneous
GLP multi-index and Bernstein-representation definitions shared by these
routes. With se = TRUE, available higher-order derivative
columns for fixed and adaptive nearest-neighbour bandwidths also have
standard errors. These combine the existing local pseudo-response
variance with the squared norm of the actual derivative weighting row,
including its accepted ridge adjustment. They condition on the selected
bandwidths, neighbour radii and local-polynomial map; they do not account
for their selection uncertainty. Generalized nearest-neighbour higher-order
point derivatives remain subject to the existing hat-operator restriction.
Bootstrap inference remains recommended.
With positive-degree local-polynomial fits (including local-linear fits),
numerical ridging follows the policies described in npreg
(Seifert and Gasser, 2000). The conditional pseudo-response uncertainty
formulas here are distinct from ordinary regression's residual normalization.
With positive-degree local-polynomial fits (including local-linear fits),
categorical first-difference standard errors use paired endpoint influence
calculations. The covariance between the two category endpoints is retained,
not replaced by the sum of their marginal variances. These calculations
condition on the selected basis, smoothing parameters and realized neighbour
radii for all three bandwidth types. They run only when both
gradients = TRUE and se = TRUE request them. A nonsmooth
regularization boundary or nonfinite influence gives NA uncertainty
with a notice, without changing the point contrast.
For ordinary scalar fits, leading interior standard errors use the squared X-kernel moment; conditional density errors additionally use the independent Y-kernel moment. Analytic first-derivative errors for fixed and generalized nearest-neighbour bandwidths with Gaussian or Epanechnikov kernels use the squared derivative-kernel moment and the X bandwidth. These formulas do not establish uniform-kernel derivative inference or full adaptive-NN inference with estimated random radii. Positive-degree local-polynomial fits use their separate covariance calculation.
For fixed and generalized nearest-neighbour scalar fits with categorical variables, these leading moments retain squared categorical kernel factors and the joint training-category frequencies. Conditional distributions, and conditional densities with no continuous response, retain the numerator–denominator covariance of the ratio estimator. In particular, a constant response-kernel contribution has zero conditional variance. Purely categorical fits use this ratio covariance without a continuous bandwidth factor, including nearest-neighbour-labelled bandwidth objects. Beta-kernel and positive-degree local-polynomial covariance calculations retain their separate targets.
For scalar adaptive nearest-neighbour fits with any continuous variable,
requested level and available continuous first-derivative standard errors
use the complete empirical influence of the conditional ratio. They retain
the actual normalized X weights and continuous/categorical Y contributions,
including numerator and denominator derivatives. This working covariance
holds the selected model, observed X geometry and realized response
nearest-neighbour radii fixed; it does not account for their sampling or
selection uncertainty. Local-constant-equivalent degree-zero fits share
this calculation, including continuous responses with categorical-only X.
Positive-degree local-polynomial, beta-kernel and paired categorical-
contrast errors retain their separate covariance calculations. With
se = FALSE, the additional uncertainty pass is not performed.
The se component records whether uncertainty was requested.
conderr and congerr are NULL when se = FALSE.
se() and gradients(..., se = TRUE) only extract stored
results and give a no-search refit message when the errors were omitted.
predict(..., se.fit = TRUE) explicitly requests the needed errors.
npcdist returns a condistribution object. The generic
accessor functions fitted, se, and
gradients, extract estimated values, asymptotic standard
errors on estimates, and gradients, respectively, from
the returned object. Furthermore, the functions predict,
summary
and plot support objects of both classes. The returned objects
have the following components:
xbw |
bandwidth(s), scale factor(s) or nearest neighbours for the
explanatory data, |
ybw |
bandwidth(s), scale factor(s) or nearest neighbours for the
dependent data, |
xeval |
the evaluation points of the explanatory data |
yeval |
the evaluation points of the dependent data |
condist |
estimates of the conditional cumulative
distribution at the evaluation points. An evaluation row whose required
explanatory normalization is exactly zero or non-finite is returned as
|
conderr |
when |
congrad |
if invoked with |
congerr |
if invoked with |
log_likelihood |
log likelihood of the cumulative conditional distribution estimate |
The conditional distribution target is
. The estimator uses the selected
mixed-data conditional distribution bandwidths and kernels for the
response and conditioning coordinates; local-polynomial routes use the
selected continuous-coordinate polynomial degree. These fitted
conditional CDFs are also the object inverted by npqreg
when computing conditional quantiles.
Scalar conditional fits involving beta kernels use the empirical
observation-influence covariance. For normalized explanatory weights
, response-kernel contributions , and fitted value
, the level variance is
, using the full training count
. Supported continuous-derivative errors use the corresponding
differentiated influence. Categorical contrasts use the difference of the
two endpoints' observation influences inside the same squared norm, thereby
retaining their covariance; self-contrasts have zero variance.
These calculations hold the selected bandwidth
state fixed; they do not add bandwidth-selection or random-NN-radius
uncertainty, and do not replace positive-degree LP covariance.
For book-length derivations, see Li and Racine (2007), Chapter 6 Conditional CDF and Quantile Estimation, especially Sections 6.1, 6.2, and 6.5, together with Chapter 5 Conditional Density Estimation. The later workflow treatment is Racine (2019), Chapter 4 Conditional Probability Density and Cumulative Distribution Functions.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Chen, S.X. (1999), “Beta kernel estimators for density functions,” Computational Statistics & Data Analysis, 31(2), 131–145. doi:10.1016/S0167-9473(99)00010-9.
Igarashi, G. and Kakizawa, Y. (2020), “Higher-order bias corrections for asymmetric kernel density estimators,” Journal of Nonparametric Statistics, 32(3), 716–752. doi:10.1080/10485252.2020.1770754.
Mansouri, B., Rastin, A., and Allah Mombeni, H. (2024), “Beta Kernel Estimator for a Cumulative Distribution Function with Bounded Support,” Journal of Sciences, Islamic Republic of Iran, 34(4), 349–361. doi:10.22059/jsciences.2024.367933.1007836.
Hall, P. and J.S. Racine and Q. Li (2004), “Cross-validation and the estimation of conditional probability densities,” Journal of the American Statistical Association, 99, 1015-1026.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2008), “Nonparametric estimation of conditional CDF and quantile functions with mixed categorical and continuous data,” Journal of Business and Economic Statistics, 26, 423-434.
Li, Q. and J. Lin and J.S. Racine (2013), “Optimal bandwidth selection for nonparametric conditional distribution and quantile functions”, Journal of Business and Economic Statistics, 31, 57-65.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Scott, D.W. (1992), Multivariate Density Estimation. Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np
npudens
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), and compute the # cross-validated bandwidths (default) using a second-order Gaussian # kernel (default). Note - this may take a minute or two depending on # the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { # First, compute the bandwidths. bw <- npcdistbw(formula=gdp~ordered(year), nmulti=1) # Next, compute the condistribution object... Fhat <- npcdist(bws=bw) # The object Fhat now contains results such as the estimated cumulative # conditional distribution function (Fhat$condist) and so on... summary(Fhat) # Call the plot() function to visualize the results (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), and compute the # cross-validated bandwidths (default) using a second-order Gaussian # kernel (default). Note - this may take a minute or two depending on # the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { # First, compute the bandwidths. # Note - we cast `X' and `y' as data frames so that plot() can # automatically grab names (this looks like overkill, but in # multivariate settings you would do this anyway, so may as well get in # the habit). X <- data.frame(year=ordered(year)) y <- data.frame(gdp) bw <- npcdistbw(xdat=X, ydat=y, nmulti=1) # Next, compute the condistribution object... Fhat <- npcdist(bws=bw) # The object Fhat now contains results such as the estimated cumulative # conditional distribution function (Fhat$condist) and so on... summary(Fhat) # Call the plot() function to visualize the results (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=FORMULA): For this example, we load the old # faithful geyser data from the R `datasets' library and compute the # conditional distribution function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npcdistbw(formula=eruptions~waiting, nmulti=1) summary(bw) # Plot the conditional cumulative distribution function (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=DATA FRAME): For this example, we load the old # faithful geyser data from the R `datasets' library and compute the # cumulative conditional distribution function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... # Note - we cast `X' and `y' as data frames so that plot() can # automatically grab names (this looks like overkill, but in # multivariate settings you would do this anyway, so may as well get in # the habit). X <- data.frame(waiting) y <- data.frame(eruptions) bw <- npcdistbw(xdat=X, ydat=y, nmulti=1) summary(bw) # Plot the conditional cumulative distribution function (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows systems) if (interactive()) plot(bw) }) # EXAMPLE 3: Variations on local polynomial conditional distribution # estimation with proper = TRUE. data("Italy") # Work in years relative to 1975 to condition the raw polynomial basis. # Calendar year = model year + year.offset, also for prediction data. year.offset <- 1975 Italy2 <- within(Italy, { year <- as.numeric(as.character(year)) - year.offset }) # Plot only: make the plotted surface proper on the plot evaluation grid. Fhat <- npcdist(gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1) plot(Fhat, proper = TRUE) # Fit an object whose fitted values are themselves proper. ctrl_fit <- list( mode = "slice", apply = "fitted", slice.grid.size = 101L, slice.extend.factor = 0.1 ) Fhat_fit <- npcdist( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_fit ) fit_proper <- fitted(Fhat_fit) fit_raw <- Fhat_fit$condist.raw # Predict on a common explicit y-grid for several years, and render # those predictions proper. g.grid <- seq(min(Italy2$gdp), max(Italy2$gdp), length.out = 200) nd_grid <- expand.grid( gdp = g.grid, year = c(1955, 1975, 1995) - year.offset ) pred_grid <- predict(Fhat, newdata = nd_grid, proper = TRUE) # Predict on paired rows with different gdp grids by year, and still # make the predictions proper via slice mode. g1 <- seq(quantile(Italy2$gdp, 0.10), quantile(Italy2$gdp, 0.60), length.out = 60) g2 <- seq(quantile(Italy2$gdp, 0.30), quantile(Italy2$gdp, 0.90), length.out = 35) nd_slice <- rbind( data.frame(gdp = g1, year = rep(1960 - year.offset, length(g1))), data.frame(gdp = g2, year = rep(1985 - year.offset, length(g2))) ) pred_slice <- predict( Fhat, newdata = nd_slice, proper = TRUE, proper.control = list(mode = "slice") ) # One object that carries properization for fitted values and for later # predict() calls. ctrl_both <- list( mode = "slice", apply = "both", slice.grid.size = 101L, slice.extend.factor = 0.1 ) Fhat_both <- npcdist( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_both ) fit_both <- fitted(Fhat_both) pred_both <- predict( Fhat_both, newdata = nd_slice, proper.control = ctrl_both ) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), and compute the # cross-validated bandwidths (default) using a second-order Gaussian # kernel (default). Note - this may take a minute or two depending on # the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { # First, compute the bandwidths. bw <- npcdistbw(formula=gdp~ordered(year), nmulti=1) # Next, compute the condistribution object... Fhat <- npcdist(bws=bw) # The object Fhat now contains results such as the estimated cumulative # conditional distribution function (Fhat$condist) and so on... summary(Fhat) # Call the plot() function to visualize the results (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), and compute the # cross-validated bandwidths (default) using a second-order Gaussian # kernel (default). Note - this may take a minute or two depending on # the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { # First, compute the bandwidths. # Note - we cast `X' and `y' as data frames so that plot() can # automatically grab names (this looks like overkill, but in # multivariate settings you would do this anyway, so may as well get in # the habit). X <- data.frame(year=ordered(year)) y <- data.frame(gdp) bw <- npcdistbw(xdat=X, ydat=y, nmulti=1) # Next, compute the condistribution object... Fhat <- npcdist(bws=bw) # The object Fhat now contains results such as the estimated cumulative # conditional distribution function (Fhat$condist) and so on... summary(Fhat) # Call the plot() function to visualize the results (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=FORMULA): For this example, we load the old # faithful geyser data from the R `datasets' library and compute the # conditional distribution function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npcdistbw(formula=eruptions~waiting, nmulti=1) summary(bw) # Plot the conditional cumulative distribution function (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=DATA FRAME): For this example, we load the old # faithful geyser data from the R `datasets' library and compute the # cumulative conditional distribution function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... # Note - we cast `X' and `y' as data frames so that plot() can # automatically grab names (this looks like overkill, but in # multivariate settings you would do this anyway, so may as well get in # the habit). X <- data.frame(waiting) y <- data.frame(eruptions) bw <- npcdistbw(xdat=X, ydat=y, nmulti=1) summary(bw) # Plot the conditional cumulative distribution function (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows systems) if (interactive()) plot(bw) }) # EXAMPLE 3: Variations on local polynomial conditional distribution # estimation with proper = TRUE. data("Italy") # Work in years relative to 1975 to condition the raw polynomial basis. # Calendar year = model year + year.offset, also for prediction data. year.offset <- 1975 Italy2 <- within(Italy, { year <- as.numeric(as.character(year)) - year.offset }) # Plot only: make the plotted surface proper on the plot evaluation grid. Fhat <- npcdist(gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1) plot(Fhat, proper = TRUE) # Fit an object whose fitted values are themselves proper. ctrl_fit <- list( mode = "slice", apply = "fitted", slice.grid.size = 101L, slice.extend.factor = 0.1 ) Fhat_fit <- npcdist( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_fit ) fit_proper <- fitted(Fhat_fit) fit_raw <- Fhat_fit$condist.raw # Predict on a common explicit y-grid for several years, and render # those predictions proper. g.grid <- seq(min(Italy2$gdp), max(Italy2$gdp), length.out = 200) nd_grid <- expand.grid( gdp = g.grid, year = c(1955, 1975, 1995) - year.offset ) pred_grid <- predict(Fhat, newdata = nd_grid, proper = TRUE) # Predict on paired rows with different gdp grids by year, and still # make the predictions proper via slice mode. g1 <- seq(quantile(Italy2$gdp, 0.10), quantile(Italy2$gdp, 0.60), length.out = 60) g2 <- seq(quantile(Italy2$gdp, 0.30), quantile(Italy2$gdp, 0.90), length.out = 35) nd_slice <- rbind( data.frame(gdp = g1, year = rep(1960 - year.offset, length(g1))), data.frame(gdp = g2, year = rep(1985 - year.offset, length(g2))) ) pred_slice <- predict( Fhat, newdata = nd_slice, proper = TRUE, proper.control = list(mode = "slice") ) # One object that carries properization for fitted values and for later # predict() calls. ctrl_both <- list( mode = "slice", apply = "both", slice.grid.size = 101L, slice.extend.factor = 0.1 ) Fhat_both <- npcdist( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_both ) fit_both <- fitted(Fhat_both) pred_both <- predict( Fhat_both, newdata = nd_slice, proper.control = ctrl_both ) ## End(Not run)
npcdistbw computes a condbandwidth object for estimating
a -variate kernel conditional cumulative distribution
estimator defined over mixed continuous and discrete (unordered
xdat, ordered xdat and ydat) data using either
the normal-reference rule-of-thumb or least-squares cross validation
method of Li and Racine (2008) and Li, Lin and Racine
(2013).
npcdistbw(...) ## S3 method for class 'formula' npcdistbw(formula, data, subset, na.action, call, gdata = NULL, ...) ## S3 method for class 'condbandwidth' npcdistbw(xdat = stop("data 'xdat' missing"), ydat = stop("data 'ydat' missing"), gydat = NULL, bws, bandwidth.compute = TRUE, cfac.dir = 2.5*(3.0-sqrt(5)), scale.factor.init = 0.5, dfac.dir = 0.25*(3.0-sqrt(5)), dfac.init = 0.375, dfc.dir = 3, do.full.integral = FALSE, ftol = 1.490116e-07, scale.factor.init.upper = 2.0, hbd.dir = 1, hbd.init = 0.9, initc.dir = 1.0, initd.dir = 1.0, invalid.penalty = c("baseline","dbmax"), itmax = 10000, lbc.dir = 0.5, scale.factor.init.lower = 0.1, lbd.dir = 0.1, lbd.init = 0.1, memfac = 500.0, ngrid = 100, nmulti, penalty.multiplier = 10, powell.remin = TRUE, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample = FALSE, scale.factor.search.lower = NULL, small = 1.490116e-05, tol = 1.490116e-04, transform.bounds = FALSE, ..., nomad.opts = list()) ## Default S3 method: npcdistbw(xdat = stop("data 'xdat' missing"), ydat = stop("data 'ydat' missing"), gydat, bws, bandwidth.compute = TRUE, bwmethod, bwscaling, bwtype, cfac.dir, scale.factor.init, cxkerbound, cxkerlb, cxkerorder, cxkertype, cxkerub, cykerbound, cykerlb, cykerorder, cykertype, cykerub, dfac.dir, dfac.init, dfc.dir, do.full.integral, ftol, scale.factor.init.upper, hbd.dir, hbd.init, initc.dir, initd.dir, invalid.penalty, itmax, lbc.dir, scale.factor.init.lower, lbd.dir, lbd.init, memfac, ngrid, nmulti, oxkertype, oykertype, penalty.multiplier, nomad.remin = FALSE, powell.remin, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample, scale.factor.search.lower = NULL, small, tol, transform.bounds, uxkertype, regtype = c("lc", "ll", "lp"), basis = c("glp", "additive", "tensor"), degree = NULL, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, bernstein.basis = FALSE, ..., nomad.opts = list())npcdistbw(...) ## S3 method for class 'formula' npcdistbw(formula, data, subset, na.action, call, gdata = NULL, ...) ## S3 method for class 'condbandwidth' npcdistbw(xdat = stop("data 'xdat' missing"), ydat = stop("data 'ydat' missing"), gydat = NULL, bws, bandwidth.compute = TRUE, cfac.dir = 2.5*(3.0-sqrt(5)), scale.factor.init = 0.5, dfac.dir = 0.25*(3.0-sqrt(5)), dfac.init = 0.375, dfc.dir = 3, do.full.integral = FALSE, ftol = 1.490116e-07, scale.factor.init.upper = 2.0, hbd.dir = 1, hbd.init = 0.9, initc.dir = 1.0, initd.dir = 1.0, invalid.penalty = c("baseline","dbmax"), itmax = 10000, lbc.dir = 0.5, scale.factor.init.lower = 0.1, lbd.dir = 0.1, lbd.init = 0.1, memfac = 500.0, ngrid = 100, nmulti, penalty.multiplier = 10, powell.remin = TRUE, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample = FALSE, scale.factor.search.lower = NULL, small = 1.490116e-05, tol = 1.490116e-04, transform.bounds = FALSE, ..., nomad.opts = list()) ## Default S3 method: npcdistbw(xdat = stop("data 'xdat' missing"), ydat = stop("data 'ydat' missing"), gydat, bws, bandwidth.compute = TRUE, bwmethod, bwscaling, bwtype, cfac.dir, scale.factor.init, cxkerbound, cxkerlb, cxkerorder, cxkertype, cxkerub, cykerbound, cykerlb, cykerorder, cykertype, cykerub, dfac.dir, dfac.init, dfc.dir, do.full.integral, ftol, scale.factor.init.upper, hbd.dir, hbd.init, initc.dir, initd.dir, invalid.penalty, itmax, lbc.dir, scale.factor.init.lower, lbd.dir, lbd.init, memfac, ngrid, nmulti, oxkertype, oykertype, penalty.multiplier, nomad.remin = FALSE, powell.remin, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample, scale.factor.search.lower = NULL, small, tol, transform.bounds, uxkertype, regtype = c("lc", "ll", "lp"), basis = c("glp", "additive", "tensor"), degree = NULL, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, bernstein.basis = FALSE, ..., nomad.opts = list())
These arguments identify the data, formula interface, optional distribution grid, and whether bandwidths are supplied or computed.
bandwidth.compute |
a logical value which specifies whether to do a numerical search for
bandwidths or not. If set to |
bws |
a bandwidth specification. This can be set as a |
call |
the original function call. This is passed internally by
|
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
formula |
a symbolic description of variables on which bandwidth selection is to be performed. The details of constructing a formula are described below. |
gdata |
a grid of data on which the indicator function for least-squares cross-validation is to be computed (can be the sample or a grid of quantiles). |
gydat |
a grid of data on which the indicator function for
least-squares cross-validation is to be computed (can be the sample
or a grid of quantiles for |
na.action |
a function which indicates what should happen when the data contain
|
subset |
an optional vector specifying a subset of observations to be used in the fitting process. |
xdat |
a |
ydat |
a |
These arguments control automatic local-polynomial degree search when regtype="lp".
degree.max |
optional scalar or integer vector giving upper bounds for automatic
degree search over continuous |
degree.max.cycles |
positive integer giving the maximum number of coordinate-search
sweeps over the degree vector. Ignored for |
degree.min |
optional scalar or integer vector giving lower bounds for automatic
degree search over continuous |
degree.restarts |
non-negative integer giving the number of additional deterministic
coordinate-search restarts. Ignored for |
degree.select |
character string controlling local-polynomial degree handling when
|
degree.start |
optional starting degree vector for automatic coordinate search. If
omitted, the search starts from the degree-zero local-constant
baseline on the continuous |
degree.verify |
logical value indicating whether a coordinate-search solution should
be exhaustively verified over the admissible degree grid after the
heuristic phase completes. Available only for
|
These arguments choose the selection criterion and the way continuous bandwidths are represented.
bwmethod |
which method to use to select bandwidths.
|
bwscaling |
a logical value that when set to |
bwtype |
character string used for the continuous variable bandwidth type,
specifying the type of bandwidth to compute and return in the
|
These controls set categorical search starts and categorical direction-set initialization.
dfac.dir |
stretch factor for direction set search for Powell's algorithm for categorical variables. See Details |
dfac.init |
non-random initial values for scale factors for categorical variables for Powell's algorithm. See Details |
hbd.dir |
upper bound for direction set search for Powell's algorithm for categorical variables. See Details |
hbd.init |
upper bound for scale factors for categorical variables for Powell's algorithm. See Details |
initd.dir |
initial non-random values for direction set search for Powell's algorithm for categorical variables. See Details |
lbd.dir |
lower bound for direction set search for Powell's algorithm for categorical variables. See Details |
lbd.init |
lower bound for scale factors for categorical variables for Powell's algorithm. See Details |
scale.init.categorical.sample |
a logical value that when set
to |
These controls set Powell direction-set initialization for continuous variables.
cfac.dir |
stretch factor for direction set search for Powell's algorithm for |
dfc.dir |
chi-square degrees of freedom for direction set search for Powell's algorithm for |
initc.dir |
initial non-random values for direction set search for Powell's algorithm for |
lbc.dir |
lower bound for direction set search for Powell's algorithm for |
These controls choose and parameterize bounded support for continuous kernels.
cxkerbound |
character string controlling continuous-kernel support handling for
|
cxkerlb |
numeric scalar/vector of lower bounds for continuous |
cxkerub |
numeric scalar/vector of upper bounds for continuous |
cykerbound |
character string controlling continuous-kernel support handling for
|
cykerlb |
numeric scalar/vector of lower bounds for continuous |
cykerub |
numeric scalar/vector of upper bounds for continuous |
These controls define deterministic and random continuous scale-factor starts and the lower admissibility floor for fixed-bandwidth search.
scale.factor.init |
deterministic initial scale factor for continuous fixed-bandwidth
search. Defaults to |
scale.factor.init.lower |
lower endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.init.upper |
upper endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.search.lower |
optional nonnegative scalar giving the hard lower admissibility
bound for continuous fixed-bandwidth search candidates. Defaults to
|
These controls tune the conditional distribution-function integral and grid calculations.
do.full.integral |
a logical value which when set as |
memfac |
The algorithm to compute the least-squares objective function uses a block-based algorithm to eliminate or minimize redundant kernel evaluations. Due to memory, hardware and software constraints, a maximum block size must be imposed by the algorithm. This block size is roughly equal to memfac*10^5 elements. Empirical tests on modern hardware find that a memfac of around 500 performs well. If you experience out of memory errors, or strange behaviour for large data sets (>100k elements) setting memfac to a lower value may fix the problem. |
ngrid |
integer number of grid points to use when computing the moment-based
integral. Defaults to |
These controls choose continuous, unordered, and ordered kernels for xdat and ydat.
cxkerorder |
numeric value specifying kernel order for
|
cxkertype |
character string used to specify the continuous kernel type for
|
cykerorder |
numeric value specifying kernel order for
|
cykertype |
character string used to specify the continuous kernel type for
|
oxkertype |
character string used to specify the ordered categorical kernel
type for |
oykertype |
character string used to specify the ordered categorical kernel
type for |
uxkertype |
character string used to specify the unordered categorical kernel
type for |
These arguments control the local-polynomial estimator, basis, and fixed degree specification.
basis |
character string specifying the polynomial basis used when
|
bernstein.basis |
logical value controlling the stabilized representation for
|
degree |
integer scalar or integer vector of polynomial degrees for
continuous |
regtype |
character string specifying the conditional local method used for
the |
These arguments control the optional NOMAD direct-search route for local-polynomial degree and bandwidth search.
nomad |
logical or character shortcut for the recommended automatic local-polynomial
NOMAD route. When |
nomad.nmulti |
non-negative integer controlling the inner
the native crs NOMAD C API multistart count used within each outer
NOMAD restart when |
nomad.opts |
optional named list of native NOMAD parameters forwarded to the
crs NOMAD C API for NOMAD-backed bandwidth searches.
|
nomad.remin |
logical flag controlling the optional second NOMAD hot start. When
|
search.engine |
character string controlling the automatic local-polynomial search
backend when |
These controls set optimizer tolerances, restart behavior, invalid-candidate penalties, memory blocking, and bounded search transformations.
ftol |
fractional tolerance on the value of the cross-validation function
evaluated at located minima (of order the machine precision or
perhaps slightly larger so as not to be diddled by
roundoff). Defaults to |
invalid.penalty |
a character string specifying the penalty
used when the optimizer encounters invalid bandwidths.
|
itmax |
integer number of iterations before failure in the numerical
optimization routine. Defaults to |
nmulti |
integer number of times to restart the process of finding extrema of the cross-validation function from different (random) initial points |
penalty.multiplier |
a numeric multiplier applied to the
baseline penalty when |
powell.remin |
logical flag controlling Powell restart-from-minimum behavior. For
ordinary fixed-degree Powell-style search, |
bwsolver |
bandwidth optimizer for fixed-degree searches. The default
|
small |
a small number used to bracket a minimum (it is hopeless to ask for
a bracketing interval of width less than sqrt(epsilon) times its
central value, a fractional width of only about 10-04 (single
precision) or 3x10-8 (double precision)). Defaults to |
tol |
tolerance on the position of located minima of the cross-validation
function (tol should generally be no smaller than the square root of
your machine's floating point precision). Defaults to |
transform.bounds |
a logical value that when set to |
These arguments collect remaining controls passed through S3 methods.
... |
additional arguments supplied to specify the bandwidth type, kernel types, selection methods, and so on, detailed below. |
Formula bandwidth objects retain the prepared training sample (after alignment,
subsetting and missing-value handling) and the resolved missing-value policy.
Later refits use that sample even if constructor variables are rebound.
Supplying explicit training data to the estimator replaces the training data;
evaluation via newdata does not. Retention requires storage proportional
to the sample size times the number of variables, not a pairwise weight matrix.
Older saved objects without this retained state still rely on their original
data bindings; rebuild their bandwidth object from the intended data before
changing those bindings. User-defined transformation and missing-value
functions should not rely on subsequently modified closure state.
Beta associated kernels may be selected independently with
cxkertype="beta" and cykertype="beta". Orders 2, 4, 6,
and 8, fixed/generalized-NN/adaptive-NN bandwidths,
cxkerbound/cykerbound equal to "fixed" or
"range", explicit bandwidth objects, and automatic cv.ls
search are supported. Normal-reference selection is not. Beta kernels act on continuous
coordinates alongside the kernels for categorical coordinates.
Local-constant, local-linear and local-polynomial fits are supported. Local-constant gradients with respect to X are
available: a beta X coordinate uses its analytic evaluation-coordinate PDF
derivative, while the beta or legacy Y CDF factor is held fixed. Exact
matching beta-X endpoints use structural cancellation in the normalized
ratio and can yield signed infinity or NA when a finite derivative
does not exist. Order-2 CDF factors
use the observation-centered incomplete-beta construction, while orders 4,
6, and 8 use its signed multiscale extension. See np.kernels
for the orientation, warnings, and references.
The scale.factor.* controls are dimensionless search
controls. The package converts scale factors to bandwidths using the
estimator-specific scaling encoded in the bandwidth object, including
kernel order and the number of continuous variables relevant for the
estimator. Users should not pre-multiply these controls by sample-size
or standard-deviation factors.
scale.factor.init controls the deterministic first search
start. scale.factor.init.lower and
scale.factor.init.upper define the random multistart interval.
scale.factor.search.lower is the lower admissibility bound for
continuous fixed-bandwidth search candidates. The effective first
start is max(scale.factor.init, scale.factor.search.lower),
and the effective random-start lower endpoint is
max(scale.factor.init.lower, scale.factor.search.lower).
scale.factor.init.upper must be at least that effective lower
endpoint; the package errors rather than silently expanding the user's
interval.
When scale.factor.search.lower is NULL, an existing
bandwidth object's stored floor is inherited when available;
otherwise the package default 0.1 is used. Explicit bandwidths
supplied for storage with bandwidth.compute = FALSE are not
rewritten by the search floor.
Categorical search-start controls such as dfac.init,
lbd.init, and hbd.init have separate semantics and are
not affected by scale.factor.search.lower.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot, plot.np for plotting options.
The bandwidth-selection argument surface is easiest to read by
decision group. Start with the data and bandwidth inputs
(xdat, ydat, gydat, bws, and
bandwidth.compute), then choose the bandwidth criterion and
representation (bwmethod, bwscaling, and
bwtype). Next choose continuous kernel and support controls
(cxker* and cyker*), categorical kernel controls
(uxkertype, oxkertype, and oykertype), and
numerical search controls including nmulti, tolerances,
penalties, and the scale.factor.* search-start and
admissibility controls. Local-polynomial and NOMAD controls
(regtype, basis, degree*,
search.engine, nomad, nomad.nmulti, and
bernstein.basis) are relevant when using the explicit
local-polynomial route.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
npcdistbw implements a variety of methods for choosing
bandwidths for multivariate distributions (-variate) defined
over a set of possibly continuous and/or discrete (unordered
xdat, ordered xdat and ydat) data. The approach
is based on Li and Racine (2004) who employ ‘generalized
product kernels’ that admit a mix of continuous and discrete data
types.
The cross-validation methods employ multivariate numerical search
algorithms. For fixed local-constant/local-linear fits, and for
local-polynomial fits with degree.select="manual", bandwidth
search uses multidimensional Powell direction-set optimization.
Bandwidths can (and will) differ for each variable which is, of course, desirable.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating
the cumulative distribution at the point . Generalized nearest-neighbor
bandwidths change with the point at which the cumulative distribution is estimated,
. Fixed bandwidths are constant over the support of .
Exact ties can make the literal th continuous nearest-neighbor
radius zero. Such a bandwidth is undefined and is rejected; see
np.kernels for the precise contract and remedies.
npcdistbw may be invoked either with a formula-like
symbolic
description of variables on which bandwidth selection is to be
performed or through a simpler interface whereby data is passed
directly to the function via the xdat and ydat
parameters. Use of these two interfaces is mutually exclusive.
Data contained in the data frame xdat may be a mix of
continuous (default), unordered discrete (to be specified in the data
frames using factor), and ordered discrete (to be
specified in the data frames using ordered). Data
contained in the data frame ydat may be a mix of continuous
(default) and ordered discrete (to be specified in the data frames
using ordered). Data can be entered in an arbitrary
order and data types will be detected automatically by the routine
(see np for details).
Data for which bandwidths are to be estimated may be specified
symbolically. A typical description has the form dependent data
~ explanatory data,
where dependent data and explanatory data are both
series of variables specified by name, separated by
the separation character '+'. For example, y1 + y2 ~ x1 + x2
specifies that the bandwidths for the joint distribution of variables
y1 and y2 conditioned on x1 and x2 are to
be estimated. See below for further examples.
Response expressions such as log(y) or I(y^2) are not
supported on the left-hand side and are rejected. Instead create, for
example, data$log_y <- log(data$y) and use log_y ~ x, or
supply the transformed response through ydat. Right-hand-side
offset() special terms are also unsupported and are rejected rather
than omitted. These checks do not evaluate response expressions, alter
stored/dynamically constructed formulas, or change supported explanatory
transformations.
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth order Gaussian and Epanechnikov kernels, and the uniform kernel. Unordered discrete data types use a variation on Aitchison and Aitken's (1976) kernel, while ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
When regtype="lp" and degree.select != "manual",
npcdistbw can jointly determine the xdat-side local
polynomial degree vector and the fixed bandwidth coordinates entering
the conditional distribution criterion. With
search.engine="cell", the criterion is profiled over the
admissible degree grid using cached coordinate-wise or exhaustive
search. With search.engine="nomad" or
"nomad+powell", the criterion is optimized directly over the
joint degree/bandwidth space using the native crs NOMAD C API;
"nomad+powell" then performs one Powell hot start from the
NOMAD solution and keeps the better of the direct NOMAD and polished
answers. This polynomial-adaptive joint-search route is motivated by
Hall and Racine (2015) together with Li, Li, and Racine (under
revision). When bernstein.basis is not explicitly supplied,
the automatic search route defaults to bernstein.basis=TRUE
for numerical stability.
Setting nomad=TRUE is a convenience preset for this automatic
LP route, not a generic optimizer alias. For conditional distribution
bandwidth selection it expands any missing values to the equivalent
long-form call
npcdistbw(...,
regtype = "lp",
search.engine = "nomad+powell",
degree.select = "coordinate",
bernstein.basis = TRUE,
degree.min = 0L,
degree.max = 10L,
degree.verify = FALSE,
bwtype = "fixed")
Compatible explicit tuning arguments are respected. Incompatible
explicit settings fail fast so the shortcut never silently changes
user-selected semantics.
The character value nomad="auto" applies the same LP
shortcut but leaves search.engine and degree.select
eligible for data-driven resolution when both were not supplied
explicitly: scalar continuous degree searches use the exhaustive
degree-grid route, while higher-dimensional degree searches keep the
NOMAD/Powell route. Explicit search.engine or
degree.select choices are honored.
The optimizer invoked for search is Powell's conjugate direction
method which requires the setting of (non-random) initial values and
search directions for bandwidths, and, when restarting, random values
for successive invocations. Bandwidths for numeric variables
are scaled by robust measures of spread, the sample size, and the
number of numeric variables where appropriate. Two sets of
parameters for bandwidths for numeric can be modified, those
for initial values for the parameters themselves, and those for the
directions taken (Powell's algorithm does not involve explicit
computation of the function's gradient). The default values are set by
considering search performance for a variety of difficult test cases
and simulated cases. We highly recommend restarting search a large
number of times to avoid the presence of local minima (achieved by
modifying nmulti). Further refinement for difficult cases can
be achieved by modifying these sets of parameters. However, these
parameters are intended more for the authors of the package to enable
‘tuning’ for various methods rather than for the user themselves.
npcdistbw returns a condbandwidth object, with the
following components:
xbw |
bandwidth(s), scale factor(s) or nearest neighbours for the
explanatory data, |
ybw |
bandwidth(s), scale factor(s) or nearest neighbours for the
dependent data, |
fval |
objective function value at minimum |
if bwtype is set to fixed, an object containing
bandwidths (or scale factors if bwscaling = TRUE) is
returned. If it is set to generalized_nn or adaptive_nn,
then instead the th nearest neighbors are returned for the
continuous variables while the discrete kernel bandwidths are returned
for the discrete variables.
Prediction follows a two-stage contract. Calling predict(bw)
on the returned bandwidth object is a convenience forwarder for
npcdist(bws = bw) and returns a fitted condistribution
object; it does not return a numeric vector of conditional-distribution
estimates. Call fitted(fit) or
predict(fit, newdata = ...) on that fitted object to obtain
numeric results. The canonical workflow is
bw <- npcdistbw(y ~ x, data = mydata)
fit <- predict(bw) # equivalent to npcdist(bws = bw)
fitted(fit)
predict(fit, newdata = newdata)
The functions summary and plot also
support condbandwidth objects.
Local-polynomial search uses the numerical-ridging policies described in
npreg; see Seifert and Gasser (2000) there.
npcdistbw selects response and conditioning bandwidths, and
when requested local-polynomial degree/search metadata, for the
conditional distribution target
estimated by
npcdist and inverted by npqreg.
For book-length derivations, see Li and Racine (2007), Chapter 6 Conditional CDF and Quantile Estimation, especially Sections 6.1, 6.2, 6.3, and 6.5, and Chapter 5 Conditional Density Estimation. The later workflow treatment is Racine (2019), Chapter 4.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Caution: multivariate data-driven bandwidth selection methods are, by
their nature, computationally intensive. Virtually all methods
require dropping the th observation from the data set, computing an
object, repeating this for all observations in the sample, then
averaging each of these leave-one-out estimates for a given
value of the bandwidth vector, and only then repeating this a large
number of times in order to conduct multivariate numerical
minimization/maximization. Furthermore, due to the potential for local
minima/maxima, restarting this procedure a large number of times may
often be necessary. This can be frustrating for users possessing
large datasets. For exploratory purposes, you may wish to override the
default search tolerances, say, setting ftol=.01 and tol=.01 and
conduct multistarting (the default is to restart min(2, ncol(xdat,ydat))
times) as is done for a number of examples. Once the procedure
terminates, you can restart search with default tolerances using those
bandwidths obtained from the less rigorous search (i.e., set
bws=bw on subsequent calls to this routine where bw is
the initial bandwidth object). A version of this package using the
Rmpi wrapper is under development that allows one to deploy
this software in a clustered computing environment to facilitate
computation involving large datasets.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Hall, P. and J.S. Racine and Q. Li (2004), “Cross-validation and the estimation of conditional probability densities,” Journal of the American Statistical Association, 99, 1015-1026.
Hall, P. and J.S. Racine (2015), “Infinite Order Cross-Validated Local Polynomial Regression,” Journal of Econometrics, 185, 510-525.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2008), “Nonparametric estimation of conditional CDF and quantile functions with mixed categorical and continuous data,” Journal of Business and Economic Statistics, 26, 423-434.
Li, Q. and J. Lin and J.S. Racine (2013), “Optimal bandwidth selection for nonparametric conditional distribution and quantile functions”, Journal of Business and Economic Statistics, 31, 57-65.
Li, A. and Q. Li and J.S. Racine (under revision), “Boundary Adjusted, Polynomial Adaptive, Nonparametric Kernel Conditional Density Estimation,” Econometric Reviews.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Scott, D.W. (1992), Multivariate Density Estimation. Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np
bw.nrd, bw.SJ, hist,
npudens, npudist
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we compute the # cross-validated bandwidths (default) using a second-order Gaussian # kernel (default). Note - this may take a minute or two depending on # the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { bw <- npcdistbw(formula=gdp~ordered(year), nmulti=1) # The object bw can be used for further estimation using # npcdist(), plotting using plot() etc. Entering the name of # the object provides useful summary information, and names() will also # provide useful information. summary(bw) # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we compute the # cross-validated bandwidths (default) using a second-order Gaussian # kernel (default). Note - this may take a minute or two depending on # the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { bw <- npcdistbw(xdat=ordered(year), ydat=gdp, nmulti=1) # The object bw can be used for further estimation using npcdist(), # plotting using plot() etc. Entering the name of the object provides # useful summary information, and names() will also provide useful # information. summary(bw) # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. }) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we compute the # cross-validated bandwidths (default) using a second-order Gaussian # kernel (default). Note - this may take a minute or two depending on # the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { bw <- npcdistbw(formula=gdp~ordered(year), nmulti=1) # The object bw can be used for further estimation using # npcdist(), plotting using plot() etc. Entering the name of # the object provides useful summary information, and names() will also # provide useful information. summary(bw) # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we compute the # cross-validated bandwidths (default) using a second-order Gaussian # kernel (default). Note - this may take a minute or two depending on # the speed of your computer. data("Italy") Italy <- Italy[seq_len(min(300, nrow(Italy))), ] with(Italy, { bw <- npcdistbw(xdat=ordered(year), ydat=gdp, nmulti=1) # The object bw can be used for further estimation using npcdist(), # plotting using plot() etc. Entering the name of the object provides # useful summary information, and names() will also provide useful # information. summary(bw) # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. }) ## End(Not run)
Constructs the conditional distribution hat operator associated with
npcdist bandwidth objects. The returned operator maps a
right-hand side y to ; with y = 1 this reproduces the
fitted conditional distribution function.
npcdisthat(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), exdat, eydat, y = NULL, output = c("matrix", "apply"), deriv = NULL, s = NULL)npcdisthat(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), exdat, eydat, y = NULL, output = c("matrix", "apply"), deriv = NULL, s = NULL)
These arguments identify the fitted bandwidth object, training data, and evaluation data.
bws |
A fitted conditional distribution bandwidth object of class |
exdat |
Optional evaluation conditioning data. If omitted, the operator is built on the training conditioning data. |
eydat |
Optional evaluation response data. If omitted, the operator is built on the training response data. |
txdat |
Training conditioning data used to construct the operator. |
tydat |
Training response data used to construct the operator. |
These arguments control whether the operator is returned as a matrix or applied directly.
output |
Either |
y |
Optional right-hand side vector or matrix with one row per training observation. |
These arguments request continuous-conditioning derivative hat operators.
deriv |
Optional derivative selector passed through to the continuous-conditioning derivative resolver. |
s |
Optional derivative multi-index for continuous conditioning variables. The default |
For the adaptive-nearest-neighbour local-constant (including degree-zero
local-polynomial) ratio, every finite nonzero conditioning-weight sum is used
without an epsilon floor. If all computed conditioning weights at an external
evaluation row are zero, that row is returned as NA with a warning.
This describes computed weights, not necessarily absence of geometric support.
Zero response weights still give a valid zero numerator when the conditioning
denominator is defined. Required internal and bootstrap ratios remain strict.
For output = "matrix", the return value is a matrix with class
c("npcdisthat", "matrix") and attributes storing the bandwidth object,
training data, evaluation data, and call metadata.
For output = "apply", the function returns H y directly. Matrix
right-hand sides are applied column-wise.
The optional s argument follows the derivative multi-index convention
used by npreghat for continuous conditioning variables. The
default s = NULL returns the ordinary conditional-distribution hat
operator. Supplying one first derivative, for example s = 1L in a
univariate continuous- problem or s = c(x2 = 1L) in a
multivariate problem, returns the hat operator for that component of the
conditional-distribution gradient. This derivative route is intended to match
npcdist(..., gradients = TRUE)$congrad.
For local-constant beta X kernels, first derivatives use the analytic beta
PDF derivative; the beta Y CDF factor is not differentiated. Exact
support-endpoint rows whose raw X weights jump are returned as NA,
because a response-free hat matrix cannot perform the Y-factor-specific
ratio cancellation available to the fitted conditional-distribution route.
This helper is intended for object-fed repeated evaluation once a bandwidth object has already been constructed. It does not perform bandwidth selection.
Either a hat matrix of class "npcdisthat" or the applied result
H y, depending on output.
## Not run: data(cps71) tx <- data.frame(age = cps71$age) ty <- data.frame(logwage = cps71$logwage) bw <- npcdistbw(xdat = tx, ydat = ty, bwtype = "fixed", bandwidth.compute = FALSE, bws = c(1.0, 1.0)) H <- npcdisthat(bws = bw, txdat = tx, tydat = ty) dist.hat <- npcdisthat(bws = bw, txdat = tx, tydat = ty, y = rep(1, nrow(tx)), output = "apply") dist.core <- fitted(npcdist(bws = bw, txdat = tx, tydat = ty)) head(cbind(dist.core, dist.hat), n = 2L) ## End(Not run)## Not run: data(cps71) tx <- data.frame(age = cps71$age) ty <- data.frame(logwage = cps71$logwage) bw <- npcdistbw(xdat = tx, ydat = ty, bwtype = "fixed", bandwidth.compute = FALSE, bws = c(1.0, 1.0)) H <- npcdisthat(bws = bw, txdat = tx, tydat = ty) dist.hat <- npcdisthat(bws = bw, txdat = tx, tydat = ty, y = rep(1, nrow(tx)), output = "apply") dist.core <- fitted(npcdist(bws = bw, txdat = tx, tydat = ty)) head(cbind(dist.core, dist.hat), n = 2L) ## End(Not run)
npcmstest implements a consistent test for correct
specification of parametric regression models (linear or nonlinear) as
described in Hsiao, Li, and Racine (2007).
npcmstest(formula, data = NULL, subset, xdat, ydat, model = stop(paste(sQuote("model")," has not been provided")), distribution = c("bootstrap", "asymptotic"), boot.method = c("iid","wild","wild-rademacher"), B = 399, pivot = TRUE, density.weighted = TRUE, random.seed = 42, ...)npcmstest(formula, data = NULL, subset, xdat, ydat, model = stop(paste(sQuote("model")," has not been provided")), distribution = c("bootstrap", "asymptotic"), boot.method = c("iid","wild","wild-rademacher"), B = 399, pivot = TRUE, density.weighted = TRUE, random.seed = 42, ...)
These arguments identify the model formula/data interface and explicit data inputs.
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
formula |
a symbolic description of the model to be tested. If |
model |
a model object obtained from a call to |
subset |
an optional vector specifying a subset of observations to be used. |
xdat |
a |
ydat |
a one (1) dimensional numeric or integer vector of dependent data, each
element |
These arguments control the test statistic, bootstrap procedure, and reproducibility settings.
boot.method |
a character string used to specify the bootstrap method.
|
B |
an integer value specifying the number of bootstrap replications to
use. Defaults to |
density.weighted |
a logical value specifying whether the statistic should be
weighted by the density of |
distribution |
a character string used to specify the method of estimating the
distribution of the statistic to be calculated. |
pivot |
a logical value specifying whether the statistic should be
normalised such that it approaches |
random.seed |
an integer used to seed R's random number generator. This is to ensure replicability. Defaults to 42. |
Further arguments are passed to the bandwidth-selection routines used by the test.
... |
additional arguments supplied to control bandwidth selection on the
residuals. One can specify the bandwidth type,
kernel types, and so on. To do this, you may specify any of |
Documentation guide: see np.kernels for kernels,
np.options for global options, and
plot for plotting options.
For distribution = "bootstrap", each bootstrap model is still
refitted separately using the selected bootstrap law. The resulting
residual vectors are collected in bounded groups, and the fixed-design
kernel contractions for and, when requested,
are evaluated as multi-response kernel sums. This reuses kernel geometry
without forming a dense observation-by-observation weight matrix or
changing residual order, pivoting, density weighting, or random draws.
The selected bandwidth's effective kernel metadata are shared by the observed
and bootstrap statistics. Manual bandwidth inputs and selection controls are
not forwarded a second time as kernel-sum arguments.
Bootstrap refits preserve the model's observation weights and offsets (GLM prior weights, not iterative working weights).
Model residuals, fitted values, response and design use the model's compact
complete-observation sample, including when it was fitted with
na.exclude. The supplied test data must represent those same complete
observations in the same order. Row counts and response values are checked;
when those agree, the caller remains responsible for supplying the matching
covariate rows. The test does not infer a new pairing or reorder observations.
The original model and its missing-value restoration policy are not modified.
npcmstest returns an object of type cmstest with the
following components, components will contain information
related to Jn or In depending on the value of pivot:
Jn |
the statistic |
In |
the statistic |
Omega.hat |
as described in Hsiao, C. and Q. Li and J.S. Racine. |
q.* |
the various quantiles of the statistic |
P |
the P-value of the statistic |
Jn.bootstrap |
if |
In.bootstrap |
if |
summary supports object of type cmstest.
The bootstrap upper-tail p-value is the proportion of bootstrap statistics greater than or equal to the observed statistic. Ties count as at least as extreme, giving the conservative tie convention for discrete statistics. This is the ordinary bootstrap proportion, without an add-one correction; a reported zero is possible with a finite number of replications.
npcmstest tests a parametric conditional-mean specification
against a nonparametric alternative, using residual-based bootstrap or
asymptotic calibration as selected by distribution. The
statistic is designed for continuous outcomes and fitted
lm or glm objects whose model frame, model
matrix, and response are available.
For book-length background, see Li and Racine (2007), Chapter 12 Model Specification Tests, especially Section 12.1 and Section 12.1.2. For the conditional-mean estimation context used by the test, see Racine (2019), Chapter 6 Conditional Mean Function Estimation.
npcmstest supports regression objects generated by
lm and uses features specific to objects of type
lm hence if you attempt to pass objects of a different
type the function cannot be expected to work.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Hsiao, C. and Q. Li and J.S. Racine (2007), “A consistent model specification test with mixed categorical and continuous data,” Journal of Econometrics, 140, 802-826.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Maasoumi, E. and J.S. Racine and T. Stengos (2007), “Growth and convergence: a profile of distribution dynamics and mobility,” Journal of Econometrics, 136, 483-508.
Murphy, K. M. and F. Welch (1990), “Empirical age-earnings profiles,” Journal of Labor Economics, 8, 202-229.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options,
plot, npregbw.
## Not run: # EXAMPLE 1: For this example, we conduct a consistent model # specification test for a parametric wage regression model that is # quadratic in age. The work of Murphy and Welch (1990) would suggest # that this parametric regression model is misspecified. data("cps71") with(cps71, { model <- lm(logwage~age+I(age^2), x=TRUE, y=TRUE) if (interactive()) plot(age, logwage) lines(age, fitted(model)) # Note - this may take a few minutes depending on the speed of your # computer... npcmstest(model = model, xdat = age, ydat = logwage, B=9, nmulti = 1) # Next try Murphy & Welch's (1990) suggested quintic specification. model <- lm(logwage~age+I(age^2)+I(age^3)+I(age^4)+I(age^5), x=TRUE, y=TRUE) if (interactive()) plot(age, logwage) lines(age, fitted(model)) X <- data.frame(age) # Note - this may take a few minutes depending on the speed of your # computer... npcmstest(model = model, xdat = age, ydat = logwage, B=9, nmulti = 1) # Note - you can pass in multiple arguments to this function. For # instance, to use local linear rather than local constant regression, # you would use npcmstest(model, X, regtype="ll"), while you could also # change the kernel type (default is second order Gaussian), numerical # search tolerance, or feed in your own vector of bandwidths and so # forth. }) # EXAMPLE 2: For this example, we replicate the application in Maasoumi, # Racine, and Stengos (2007) (see oecdpanel for details). We # estimate a parametric model that is used in the literature, then # subject it to the model specification test. data("oecdpanel") with(oecdpanel, { model <- lm(growth ~ oecd + factor(year) + initgdp + I(initgdp^2) + I(initgdp^3) + I(initgdp^4) + popgro + inv + humancap + I(humancap^2) + I(humancap^3) - 1, x=TRUE, y=TRUE) X <- data.frame(factor(oecd), factor(year), initgdp, popgro, inv, humancap) npcmstest(model = model, xdat = X, ydat = growth, B=9, nmulti = 1) }) ## End(Not run)## Not run: # EXAMPLE 1: For this example, we conduct a consistent model # specification test for a parametric wage regression model that is # quadratic in age. The work of Murphy and Welch (1990) would suggest # that this parametric regression model is misspecified. data("cps71") with(cps71, { model <- lm(logwage~age+I(age^2), x=TRUE, y=TRUE) if (interactive()) plot(age, logwage) lines(age, fitted(model)) # Note - this may take a few minutes depending on the speed of your # computer... npcmstest(model = model, xdat = age, ydat = logwage, B=9, nmulti = 1) # Next try Murphy & Welch's (1990) suggested quintic specification. model <- lm(logwage~age+I(age^2)+I(age^3)+I(age^4)+I(age^5), x=TRUE, y=TRUE) if (interactive()) plot(age, logwage) lines(age, fitted(model)) X <- data.frame(age) # Note - this may take a few minutes depending on the speed of your # computer... npcmstest(model = model, xdat = age, ydat = logwage, B=9, nmulti = 1) # Note - you can pass in multiple arguments to this function. For # instance, to use local linear rather than local constant regression, # you would use npcmstest(model, X, regtype="ll"), while you could also # change the kernel type (default is second order Gaussian), numerical # search tolerance, or feed in your own vector of bandwidths and so # forth. }) # EXAMPLE 2: For this example, we replicate the application in Maasoumi, # Racine, and Stengos (2007) (see oecdpanel for details). We # estimate a parametric model that is used in the literature, then # subject it to the model specification test. data("oecdpanel") with(oecdpanel, { model <- lm(growth ~ oecd + factor(year) + initgdp + I(initgdp^2) + I(initgdp^3) + I(initgdp^4) + popgro + inv + humancap + I(humancap^2) + I(humancap^3) - 1, x=TRUE, y=TRUE) X <- data.frame(factor(oecd), factor(year), initgdp, popgro, inv, humancap) npcmstest(model = model, xdat = X, ydat = growth, B=9, nmulti = 1) }) ## End(Not run)
npconmode performs kernel modal regression on mixed data,
and finds the
conditional mode given a set of training data, consisting of
explanatory data and dependent data, and possibly evaluation data.
Automatically computes various in sample and out of sample measures of
accuracy.
npconmode(bws, ...) ## S3 method for class 'formula' npconmode(bws, data = NULL, newdata = NULL, ..., se = FALSE) ## Default S3 method: npconmode(bws, txdat, tydat, nomad = FALSE, proper = NULL, proper.control = list(), probabilities = FALSE, gradients = FALSE, level = NULL, ..., se = FALSE) ## S3 method for class 'conbandwidth' npconmode(bws, txdat = stop("invoked without training data 'txdat'"), tydat = stop("invoked without training data 'tydat'"), exdat, eydat, proper = NULL, proper.control = list(), probabilities = FALSE, gradients = FALSE, level = NULL, ..., se = FALSE) ## S3 method for class 'conmode' predict(object, newdata = NULL, type = c("class", "prob"), se.fit = FALSE, ...) ## S3 method for class 'conmode' plot(x, ...)npconmode(bws, ...) ## S3 method for class 'formula' npconmode(bws, data = NULL, newdata = NULL, ..., se = FALSE) ## Default S3 method: npconmode(bws, txdat, tydat, nomad = FALSE, proper = NULL, proper.control = list(), probabilities = FALSE, gradients = FALSE, level = NULL, ..., se = FALSE) ## S3 method for class 'conbandwidth' npconmode(bws, txdat = stop("invoked without training data 'txdat'"), tydat = stop("invoked without training data 'tydat'"), exdat, eydat, proper = NULL, proper.control = list(), probabilities = FALSE, gradients = FALSE, level = NULL, ..., se = FALSE) ## S3 method for class 'conmode' predict(object, newdata = NULL, type = c("class", "prob"), se.fit = FALSE, ...) ## S3 method for class 'conmode' plot(x, ...)
These arguments identify the bandwidth specification, formula/data interface, and training data.
bws |
a bandwidth specification. This can be set as a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
txdat |
a |
tydat |
a one (1) dimensional vector of unordered or ordered factors, containing the dependent data. Defaults to the corresponding training data recoverable from the bandwidth object in the current session. |
object |
an object of class |
x |
an object of class |
These arguments control where the conditional mode is evaluated.
exdat |
a |
eydat |
Optional observed categorical outcomes at |
newdata |
An optional data frame in which to look for evaluation data. If omitted, the training data are used. |
type |
prediction type for |
se.fit |
a logical value for |
se |
a scalar logical controlling raw class-probability asymptotic
standard errors. Defaults to |
These arguments control stored class probabilities, proper probability normalization, and level-specific class-probability effects.
probabilities |
a logical value. If |
gradients |
a logical value. If |
level |
response level for class-probability gradients/effects and
|
proper |
a logical value or |
proper.control |
a list of controls for discrete probability properization. Currently
|
This argument controls the recommended automatic local-polynomial NOMAD route, which jointly selects continuous polynomial degree and bandwidths when conditional-density bandwidths are computed inside npconmode.
nomad |
logical shortcut passed through to |
Further arguments are passed to the bandwidth-selection counterpart, prediction/evaluation route, or plot route as appropriate.
... |
additional arguments supplied to Continuous gradient plots retain the raw underlying conditional-density
derivative documented above, including when These are selected-smoothing variability approximations for the named
level, not confidence bands for the winning class, all classes jointly,
smoothing bias or values between grid points. Independent observations,
regular local neighborhoods and valid covariance/marginal approximations
are required. Local-polynomial and fixed-view response factors use local
response moments as a working covariance approximation conditional on the
accepted design and response map. At fixed nonshrinking bandwidths they
need not equal a full empirical-caseweight derivative, which also perturbs
the design map. Their leading interpretation requires smooth shrinking
neighborhoods and nondegenerate local response variation.
A growing or data-dependent sample grid additionally needs
uniform linearization, non-dominating influences and a Gaussian-maximum
approximation; arbitrary sample grids do not carry a uniform-coverage
guarantee. |
Conditional fitting and replay use the literal categorical kernels for
both explanatory and response variables. Near-upper categorical bandwidths
are not replaced by approximate constant factors. The same target is used
for levels, gradients, standard errors, conditional hats, and reconstructed
plot uncertainty. This conditional-family policy does not change direct
regression or unconditional kernel-sum evaluation and does not modify the
caller's np.largelambda option.
New fitted objects record conditional.kernel.policy. Stored values
in older objects remain available without refitting. A plot that combines
such historical stored class probabilities or effects with newly
reconstructed bootstrap or joint asymptotic uncertainty requires an explicit
refit under the current policy. Stored pointwise probability standard errors
remain readable. Explicit predictions at new evaluation data use the current
conditional target and retain the object's probability-normalization controls.
With a formula-derived bandwidth object, supplying only tydat
replaces the evaluated response in retained-training-sample order: one row
per observation retained after the original subset and missing-value selection.
Original excluded rows are not restored; row names or equal lengths do not
imply original-data order. The effective na.action is then applied
jointly to the retained predictors and replacement response; any new omission
indices refer to this retained sample. The selected bandwidths remain fixed,
and the returned object retains the replacement sample for subsequent refits.
Use data for full formula-data replacement, not together with a partial
response replacement. Explicit native training arguments retain their separate
positional contract.
For native (non-formula) objects, named newdata columns are matched
to the retained variable names and reordered as needed. Extra columns are
ignored; missing, duplicate or ambiguous names are errors. An unnamed
matrix or vector remains positional for a single evaluation role.
Explicit native evaluation arguments retain their positional contract and
take precedence over newdata.
For both formula and native bandwidth objects, newdata supplies
evaluation predictors and, when present, named evaluation outcomes. Explicit
native evaluation arguments take precedence. This evaluates at the requested
rows without repeating bandwidth selection.
With evaluation predictors and outcomes, the confusion matrix and accuracy
describe the evaluation sample. With evaluation predictors only, predictions
are returned normally and these diagnostics are NA. Without evaluation
inputs, diagnostics describe training data. Missing evaluation outcomes do
not remove predictor-complete prediction rows: scores use observed
outcome/prediction pairs, and are NA when none are available. Supplying
outcomes never changes fitted class support, probabilities or gradients.
Formula variables of class ts, including lagged variables, are
aligned on their common time support before fitting. Other variables
must already have the length of that intersection. Supply explicitly
aligned rows when using native data arguments instead of a formula.
Local-polynomial calculations inherit numerical ridging from
npcdens. See that estimator's help for the solve
policy and its distinct conditional uncertainty formula.
Documentation guide: see np.kernels for kernels,
np.options for global options, and
plot for plotting options.
If bws is not an explicit conbandwidth object,
npconmode computes conditional density bandwidths by forwarding the
call to npcdensbw. The resulting conbandwidth object is
stored unchanged in the returned object's bws component. Regression
type, local-polynomial degree, and NOMAD/search metadata are also mirrored on
the returned conmode object for convenient inspection and summary
reporting; the bandwidth object remains the canonical source.
For non-local-constant conditional-mode fits, npconmode constructs
the full set of fitted probabilities over the discrete response support and
projects them onto the probability simplex before selecting and reporting
the modal outcome. Thus the probabilities used for modal selection are
non-negative and sum to one over the discrete support. For binary outcomes
this is the complement contract
. Local-constant fits
are already proper by construction, so omitted proper resolves to
FALSE for regtype="lc" and to TRUE otherwise.
The predict method follows the usual S3
newdata convention. With no evaluation arguments,
predict(fit) extracts the stored modal class and
predict(fit, type="prob") extracts stored class probabilities
when the object was fitted with probabilities=TRUE. With
newdata, predict evaluates the conditional mode at the
supplied rows using the stored bandwidth object. Use
type="prob" to return the full matrix of fitted class
probabilities at the evaluation rows. Use se.fit=TRUE with
type="prob" to return a list containing the class-probability matrix
and the matching asymptotic standard-error matrix. Native evaluator
arguments exdat and eydat remain available for advanced
workflows and take precedence if supplied.
npconmode returns a conmode object with the following
components:
omit, rows.omit, nobs.omit
|
omitted-row information for the active result: training rows for training evaluation, otherwise evaluation rows. Existing NA padding of row outputs is unchanged. |
train.rows.omit, train.nobs.omit
|
training omissions, retained separately even when the result evaluates external data. |
eval.omit, eval.rows.omit, eval.nobs.omit
|
omission information for external evaluation data, when supplied. |
bws |
the |
conmode |
a vector of type |
condens |
a vector of numeric type containing the modal density estimates at each evaluation point |
conderr |
a vector of numeric type containing asymptotic
standard errors for the modal density estimates at each evaluation point.
This component is |
xeval |
a data frame of evaluation points |
yeval |
a vector of type |
diagnostics.sample |
|
diagnostics.nobs |
Number of observed outcome/prediction pairs scored. |
confusion.matrix |
the confusion matrix or |
CCR.overall |
the overall correct
classification ratio, or |
CCR.byoutcome |
a numeric vector containing the correct
classification ratio by outcome, or |
fit.mcfadden |
the McFadden-Puig-Kerschner performance measure
or |
probabilities |
if requested, a matrix of fitted probabilities over the discrete response support |
probability.levels |
if |
probability.errors |
if |
se |
whether probability uncertainty was requested |
probability.repaired.rows |
if |
probability.gradients |
if |
probability.gradient.level, probability.gradient.names, probability.gradient.info
|
metadata describing the response support,
conditioning variables, and interpretation of
|
proper.requested, proper.applied, proper.info
|
metadata describing whether discrete probability properization was requested, whether any row was materially projected, and diagnostics for non-negativity and unit-mass checks |
regtype, degree, nomad, search.engine
|
metadata mirrored from
|
degree.search, nomad.shortcut, nomad.time, powell.time
|
detailed
search metadata mirrored from |
The function predict may be used to extract conditional mode
class predictions, while fitted extracts the conditional
density estimates at the conditional mode from the resulting object. The
function gradients extracts
class-probability gradients/effects when gradients=TRUE. Also,
summary and plot support conmode
objects. For plot.conmode, first fit with
probabilities=TRUE so the plot can remain object-fed. The default
plot displays the fitted probability for the base/reference response level
levels(y)[1]; use plot(fit, level=...) to select another
outcome and plot(fit, gradients=TRUE) to display stored
class-probability effects. The default view="sample" draws stored
object-fed probability/effect payloads at the fitted evaluation points. Use
view="fixed" and neval to draw object-fed one-dimensional
slices over each conditioning variable, with other variables held at their
median/mode values. Use perspective=TRUE to draw a base-graphics
probability surface for one selected response level over two continuous
conditioning variables, and renderer="rgl" for the corresponding
interactive surface. Use errors="asymptotic" for probability-level
standard errors and intervals in one-dimensional plots and fixed surfaces.
Surface band="all" draws the pointwise, simultaneous and Bonferroni
endpoints already present in output="data"; coverage remains for
the selected response level on the declared evaluation grid, not jointly
across response levels. Automatic surface limits include finite interval
endpoints without truncating them to . Explicit zlim
controls drawing only and does not alter returned endpoints. Unavailable
interval cells remain missing. Surface bootstrap intervals and gradient
surfaces are not implemented.
The conditional-mode target is
for a discrete response. In practice
npconmode estimates the conditional probability of each
response support point using npcdensbw /
npcdens, optionally projects non-local-constant fitted
probabilities onto the probability simplex, and then reports the
modal support point.
Setting gradients=TRUE stores class-probability effects for one
response level. If level is omitted, the base/reference response level
levels(y)[1] is used. These effects are useful for asking how the
fitted probability of a selected class changes with each covariate; they are
not gradients of the arg max classification rule itself.
For book-length background, see Racine (2019), Chapter 4 Conditional Probability Density and Cumulative Distribution Functions, especially the binary and multinomial choice material, and Li and Racine (2007), Chapter 5 Conditional Density Estimation together with Chapter 4 Kernel Estimation with Mixed Data.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Hall, P. and J.S. Racine and Q. Li (2004), “Cross-validation and the estimation of conditional probability densities,” Journal of the American Statistical Association, 99, 1015-1026.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
McFadden, D. and C. Puig and D. Kerschner (1977), “Determinants of the long-run demand for electricity,” Proceedings of the American Statistical Association (Business and Economics Section), 109-117.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Scott, D.W. (1992), Multivariate Density Estimation. Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options,
plot, npcdensbw.
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we use the # birthweight data taken from the MASS library, and compute a parametric # logit model and a nonparametric conditional mode model. We then # compare their confusion matrices and summary measures of # classification ability. library("MASS") data("birthwt") birthwt$low <- factor(birthwt$low) birthwt$smoke <- factor(birthwt$smoke) birthwt$race <- factor(birthwt$race) birthwt$ht <- factor(birthwt$ht) birthwt$ui <- factor(birthwt$ui) birthwt$ftv <- ordered(birthwt$ftv) with(birthwt, { # Fit a parametric logit model with low (0/1) as the dependent # variable and age, lwt, and smoke (0/1) as the covariates # From ?birthwt # 'low' indicator of birth weight less than 2.5kg # 'smoke' smoking status during pregnancy # 'race' mother's race ('1' = white, '2' = black, '3' = other) # 'ht' history of hypertension # 'ui' presence of uterine irritability # 'ftv' number of physician visits during the first trimester # 'age' mother's age in years # 'lwt' mother's weight in pounds at last menstrual period model.logit <- glm(low~smoke+ race+ ht+ ui+ ftv+ age+ lwt, family=binomial(link=logit)) # Generate the confusion matrix and correct classification ratio cm <- table(factor(low, levels = 0:1), factor(ifelse(fitted(model.logit)>0.5, 1, 0), levels = 0:1)) ccr <- sum(diag(cm))/sum(cm) # Now do the same with a nonparametric model. Note - this may take a # few minutes depending on the speed of your computer... bw <- npcdensbw(formula=low~smoke+ race+ ht+ ui+ ftv+ age+ lwt, data=birthwt) model.np <- npconmode(bws=bw) # Compare confusion matrices from the logit and nonparametric model # Logit cm ccr # Nonparametric summary(model.np) # Predict modal classes and fitted class probabilities at selected rows new.birthwt <- birthwt[1:5, c("smoke", "race", "ht", "ui", "ftv", "age", "lwt")] predict(model.np, newdata=new.birthwt) predict(npconmode(bws=bw, probabilities=TRUE), newdata=new.birthwt, type="prob") }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we use the # birthweight data taken from the MASS library, and compute a parametric # logit model and a nonparametric conditional mode model. We then # compare their confusion matrices and summary measures of # classification ability. library("MASS") data("birthwt") with(birthwt, { # Fit a parametric logit model with low (0/1) as the dependent # variable and age, lwt, and smoke (0/1) as the covariates # From ?birthwt # 'low' indicator of birth weight less than 2.5kg # 'smoke' smoking status during pregnancy # 'race' mother's race ('1' = white, '2' = black, '3' = other) # 'ht' history of hypertension # 'ui' presence of uterine irritability # 'ftv' number of physician visits during the first trimester # 'age' mother's age in years # 'lwt' mother's weight in pounds at last menstrual period model.logit <- glm(low~factor(smoke)+ factor(race)+ factor(ht)+ factor(ui)+ ordered(ftv)+ age+ lwt, family=binomial(link=logit)) # Generate the confusion matrix and correct classification ratio cm <- table(factor(low, levels = 0:1), factor(ifelse(fitted(model.logit)>0.5, 1, 0), levels = 0:1)) ccr <- sum(diag(cm))/sum(cm) # Now do the same with a nonparametric model... X <- data.frame(factor(smoke), factor(race), factor(ht), factor(ui), ordered(ftv), age, lwt) y <- factor(low) # Note - this may take a few minutes depending on the speed of your # computer... bw <- npcdensbw(xdat=X, ydat=y) model.np <- npconmode(bws=bw) # Compare confusion matrices from the logit and nonparametric model # Logit cm ccr # Nonparametric summary(model.np) }) # EXAMPLE 3 (CLASS PROBABILITY EFFECTS): compute and plot # class-probability gradients/effects for one selected response level. # This example uses a small artificial sample so that it runs quickly. set.seed(42) n <- 100 x <- seq(-1, 1, length.out=n) y <- factor(rbinom(n, 1, plogis(1.5*x)), levels=0:1) model.effects <- npconmode(y~x, regtype="ll", bwmethod="cv.ls", nmulti=1, probabilities=TRUE, gradients=TRUE) gradients(model.effects) plot(model.effects) plot(model.effects, view="fixed", neval=25) plot(model.effects, gradients=TRUE) plot(model.effects, gradients=TRUE, view="fixed", neval=25) ## A two-continuous-predictor fit can be displayed as a probability surface. ## The default level is the base/reference response level. z <- runif(n, -1, 1) y2 <- factor(rbinom(n, 1, plogis(1.5*x - z)), levels=0:1) model.surface <- npconmode(y2~x+z, regtype="ll", bwmethod="cv.ls", nmulti=1, probabilities=TRUE) plot(model.surface, perspective=TRUE, neval=15) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we use the # birthweight data taken from the MASS library, and compute a parametric # logit model and a nonparametric conditional mode model. We then # compare their confusion matrices and summary measures of # classification ability. library("MASS") data("birthwt") birthwt$low <- factor(birthwt$low) birthwt$smoke <- factor(birthwt$smoke) birthwt$race <- factor(birthwt$race) birthwt$ht <- factor(birthwt$ht) birthwt$ui <- factor(birthwt$ui) birthwt$ftv <- ordered(birthwt$ftv) with(birthwt, { # Fit a parametric logit model with low (0/1) as the dependent # variable and age, lwt, and smoke (0/1) as the covariates # From ?birthwt # 'low' indicator of birth weight less than 2.5kg # 'smoke' smoking status during pregnancy # 'race' mother's race ('1' = white, '2' = black, '3' = other) # 'ht' history of hypertension # 'ui' presence of uterine irritability # 'ftv' number of physician visits during the first trimester # 'age' mother's age in years # 'lwt' mother's weight in pounds at last menstrual period model.logit <- glm(low~smoke+ race+ ht+ ui+ ftv+ age+ lwt, family=binomial(link=logit)) # Generate the confusion matrix and correct classification ratio cm <- table(factor(low, levels = 0:1), factor(ifelse(fitted(model.logit)>0.5, 1, 0), levels = 0:1)) ccr <- sum(diag(cm))/sum(cm) # Now do the same with a nonparametric model. Note - this may take a # few minutes depending on the speed of your computer... bw <- npcdensbw(formula=low~smoke+ race+ ht+ ui+ ftv+ age+ lwt, data=birthwt) model.np <- npconmode(bws=bw) # Compare confusion matrices from the logit and nonparametric model # Logit cm ccr # Nonparametric summary(model.np) # Predict modal classes and fitted class probabilities at selected rows new.birthwt <- birthwt[1:5, c("smoke", "race", "ht", "ui", "ftv", "age", "lwt")] predict(model.np, newdata=new.birthwt) predict(npconmode(bws=bw, probabilities=TRUE), newdata=new.birthwt, type="prob") }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we use the # birthweight data taken from the MASS library, and compute a parametric # logit model and a nonparametric conditional mode model. We then # compare their confusion matrices and summary measures of # classification ability. library("MASS") data("birthwt") with(birthwt, { # Fit a parametric logit model with low (0/1) as the dependent # variable and age, lwt, and smoke (0/1) as the covariates # From ?birthwt # 'low' indicator of birth weight less than 2.5kg # 'smoke' smoking status during pregnancy # 'race' mother's race ('1' = white, '2' = black, '3' = other) # 'ht' history of hypertension # 'ui' presence of uterine irritability # 'ftv' number of physician visits during the first trimester # 'age' mother's age in years # 'lwt' mother's weight in pounds at last menstrual period model.logit <- glm(low~factor(smoke)+ factor(race)+ factor(ht)+ factor(ui)+ ordered(ftv)+ age+ lwt, family=binomial(link=logit)) # Generate the confusion matrix and correct classification ratio cm <- table(factor(low, levels = 0:1), factor(ifelse(fitted(model.logit)>0.5, 1, 0), levels = 0:1)) ccr <- sum(diag(cm))/sum(cm) # Now do the same with a nonparametric model... X <- data.frame(factor(smoke), factor(race), factor(ht), factor(ui), ordered(ftv), age, lwt) y <- factor(low) # Note - this may take a few minutes depending on the speed of your # computer... bw <- npcdensbw(xdat=X, ydat=y) model.np <- npconmode(bws=bw) # Compare confusion matrices from the logit and nonparametric model # Logit cm ccr # Nonparametric summary(model.np) }) # EXAMPLE 3 (CLASS PROBABILITY EFFECTS): compute and plot # class-probability gradients/effects for one selected response level. # This example uses a small artificial sample so that it runs quickly. set.seed(42) n <- 100 x <- seq(-1, 1, length.out=n) y <- factor(rbinom(n, 1, plogis(1.5*x)), levels=0:1) model.effects <- npconmode(y~x, regtype="ll", bwmethod="cv.ls", nmulti=1, probabilities=TRUE, gradients=TRUE) gradients(model.effects) plot(model.effects) plot(model.effects, view="fixed", neval=25) plot(model.effects, gradients=TRUE) plot(model.effects, gradients=TRUE, view="fixed", neval=25) ## A two-continuous-predictor fit can be displayed as a probability surface. ## The default level is the base/reference response level. z <- runif(n, -1, 1) y2 <- factor(rbinom(n, 1, plogis(1.5*x - z)), levels=0:1) model.surface <- npconmode(y2~x+z, regtype="ll", bwmethod="cv.ls", nmulti=1, probabilities=TRUE) plot(model.surface, perspective=TRUE, neval=15) ## End(Not run)
npcopula estimates a mixed-data kernel copula distribution or
copula density. It can be called with an existing unconditional
distribution/density bandwidth object, or with a one-sided formula in
which case the appropriate bandwidth object is selected internally.
Continuous marginal kernel bounds retain their original variable identity
when continuous and categorical columns are mixed or reordered.
npcopula(bws, ...) ## S3 method for class 'formula' npcopula(bws, data = NULL, u = NULL, target = c("distribution", "density"), evaluation = c("grid", "sample"), neval = 30, n.quasi.inv = 1000, er.quasi.inv = 1, ..., se = FALSE) ## Default S3 method: npcopula(bws, data, u = NULL, target = NULL, evaluation = c("sample", "grid"), neval = 30, n.quasi.inv = 1000, er.quasi.inv = 1, ..., se = FALSE) ## S3 method for class 'npcopula' predict(object, newdata = NULL, u = NULL, se.fit = FALSE, output = c("vector", "object", "data"), ...) ## S3 method for class 'npcopula' plot(x, perspective = TRUE, view = c("rotate", "fixed", "surface", "contour", "image", "empirical", "all"), renderer = c("base", "rgl"), errors = c("none", "bootstrap", "asymptotic"), band = c("pointwise", "pmzsd", "bonferroni", "simultaneous", "all"), alpha = 0.05, bootstrap = c("inid", "fixed", "geom"), B = 9999, center = c("estimate", "bias-corrected"), boot.control = np_boot_control(), output = c("plot", "data", "plot-data", "both"), legend = TRUE, theta = 0.0, phi = 20.0, xlab = "u1", ylab = "u2", zlab = NULL, main = NULL, col = NULL, border = .np_plot_color("surface_border"), zlim = NULL, gaussian.draws = 9999L, random.seed = 42L, ...)npcopula(bws, ...) ## S3 method for class 'formula' npcopula(bws, data = NULL, u = NULL, target = c("distribution", "density"), evaluation = c("grid", "sample"), neval = 30, n.quasi.inv = 1000, er.quasi.inv = 1, ..., se = FALSE) ## Default S3 method: npcopula(bws, data, u = NULL, target = NULL, evaluation = c("sample", "grid"), neval = 30, n.quasi.inv = 1000, er.quasi.inv = 1, ..., se = FALSE) ## S3 method for class 'npcopula' predict(object, newdata = NULL, u = NULL, se.fit = FALSE, output = c("vector", "object", "data"), ...) ## S3 method for class 'npcopula' plot(x, perspective = TRUE, view = c("rotate", "fixed", "surface", "contour", "image", "empirical", "all"), renderer = c("base", "rgl"), errors = c("none", "bootstrap", "asymptotic"), band = c("pointwise", "pmzsd", "bonferroni", "simultaneous", "all"), alpha = 0.05, bootstrap = c("inid", "fixed", "geom"), B = 9999, center = c("estimate", "bias-corrected"), boot.control = np_boot_control(), output = c("plot", "data", "plot-data", "both"), legend = TRUE, theta = 0.0, phi = 20.0, xlab = "u1", ylab = "u2", zlab = NULL, main = NULL, col = NULL, border = .np_plot_color("surface_border"), zlim = NULL, gaussian.draws = 9999L, random.seed = 42L, ...)
These arguments identify the bandwidth specification, source data, and formula route.
bws |
bandwidth specification or one-sided formula. A bandwidth
specification is either an unconditional distribution bandwidth
object returned by |
data |
data frame containing the variables used to construct |
These arguments control whether a copula distribution or density is estimated and where it is evaluated.
er.quasi.inv |
fraction passed to |
evaluation |
evaluation route used when |
n.quasi.inv |
number of grid points used to compute each marginal quasi-inverse
when |
newdata |
optional prediction data for |
neval |
number of probability values per margin in the automatically
generated two-dimensional grid used when |
target |
target used when |
u |
optional matrix or data frame of marginal probability values in
|
object |
an object of class |
se |
logical value; default |
se.fit |
logical value. With vector output, |
These arguments control how a two-dimensional grid copula object is displayed.
x |
an object of class |
border |
border color for surface facets and interval wireframes when
|
col |
optional surface or image colors. If omitted, |
legend |
logical or legend-control value used for |
main, xlab, ylab, zlab
|
plot titles and axis labels. |
output |
return mode. For |
perspective |
logical value. If |
phi, theta
|
viewing angles passed to |
renderer |
plotting renderer for surface displays. |
view |
display type for grid output. The default |
zlim |
optional z-axis limits for surface displays. |
These arguments add asymptotic or bootstrap intervals to two-dimensional surface plots.
alpha |
nominal size used for asymptotic or bootstrap intervals when
|
B |
number of bootstrap replications when |
band |
interval type for plotted surfaces. Supported values are
|
bootstrap |
bootstrap resampling method used when |
boot.control |
optional |
center |
centering convention for bootstrap intervals. Copula plots support
|
gaussian.draws, random.seed
|
Gaussian maximum simulation count and reproducible seed for asymptotic
|
errors |
interval route for |
Further arguments are passed to the bandwidth-selection counterpart, prediction/evaluation route, or graphics renderer as appropriate.
... |
additional arguments supplied to |
Formula variables of class ts, including lagged variables, are
aligned on their common time support before fitting. Other variables
must already have the length of that intersection. Supply explicitly
aligned rows when using native data arguments instead of a formula.
Documentation guide: see np.kernels for kernels,
np.options for global options, and plot
for plotting options.
npcopula computes the nonparametric copula distribution or
copula density using marginal quasi-inversion. For the distribution
target, Sklar's theorem gives
where is the joint distribution and is the
quasi-inverse of marginal distribution . For the density
target, the estimated copula density is
with numerator and marginal denominators estimated using the selected mixed-data kernel bandwidths.
If u is provided, expand.grid is called on
u. As the dimension increases this can become unwieldy because
a grid with points in each of margins has
rows. Therefore the formula route automatically generates a
probability grid only for two-dimensional copulas. For
higher-dimensional copulas, supply u explicitly or use
evaluation="sample". The predict.npcopula method follows
these same probability-coordinate semantics: use u for
probability values named however convenient, or use newdata
only with u1, u2, ... columns.
The ‘quasi-inverse’ is computed via Definition 2.3.6 from
Nelsen (2006). An equi-quantile grid on the data range of length
n.quasi.inv/2 is combined with an equi-spaced grid on the data
range extended by er.quasi.inv and intersected with the fitted
marginal kernel's bounds; the sorted union forms the
grid used for marginal inversion. If requested probability values lie
outside the attainable estimated marginal distribution range, they
are reset to the nearest attainable endpoint. Inspect the returned
u columns when endpoint behavior matters. Higher-order
continuous CDF kernels can yield nonmonotone estimated marginal CDFs
on the finite inversion grid; the quasi-inverse follows the first grid
point whose estimated CDF reaches the requested probability.
The plot.npcopula method supports base persp,
contour, and image displays for
two-dimensional grid output. Central and uncertainty surfaces share one
coordinate ordering: probability axes
are sorted for display, while fitted values and returned plot data keep
their supplied-grid order. Duplicate display coordinates are collapsed only
when their fitted values and interval endpoints agree; conflicting duplicates
are rejected. Asymptotic simultaneous calibration uses the unique targets
after exact agreement of their fitted values, physical coordinates and
marginal standard errors. Repeating a target does not change the maximum
of its Gaussian process. Calibration metadata records the unique grid size
and, when duplicates occur, the original row count and target mapping.
All supplied rows remain in returned plot data; existing pointwise and
Bonferroni intervals retain their original calibration. Surface plots use the package-wide
viridis default palette, detailed perspective ticks, and the same
default viewing angles and base-graphics rotation cadence as the
other surface plot methods. renderer="rgl" requests the shared
interactive rgl surface renderer, using the same default-angle
remapping used by the other package surface plots. For mixed ordered
margins and endpoint-clamped continuous margins, grid displays are
drawn against the requested probability grid, while the returned
u columns retain the attainable marginal probability values
produced by quasi-inversion. The
"empirical" view plots empirical copula coordinates, and
"all" gives a base-graphics four-panel diagnostic display.
Standard-error extraction with se(object) only reads stored
results; it does not silently refit the model. To add errors without
repeating bandwidth selection, use
npcopula(bws=object$bws, data=object$data, u=object$u.input, se=TRUE,
n.quasi.inv=object$n.quasi.inv, er.quasi.inv=object$er.quasi.inv).
The default skips uncertainty-only work. Explicit asymptotic plot
requests obtain their needed errors even if the original fit omitted them.
For grid surfaces, plot.npcopula can add asymptotic or
bootstrap intervals. Distribution-copula asymptotic intervals use the
joint distribution standard error evaluated at the marginal
quasi-inverse grid. For fixed bandwidths, density-copula standard errors
use the centered empirical influence of
, including the same-sample
covariance of the joint density and all marginal densities. Query
coordinates and selected bandwidths are held fixed. A zero marginal
density or nonfinite influence produces an unavailable row standard
error (NA) and a notice. Nearest-neighbor density-copula errors
retain the existing joint-density error divided by the marginal-density
product; their complete ratio and random-radius covariance is not covered
by the fixed-bandwidth correction. Bootstrap intervals resample
rows and recompute the plotted copula surface on the same probability
grid. These interval conventions do not fully propagate uncertainty
from the marginal quasi-inverse transform. band="simultaneous"
calibrates a joint Gaussian maximum over the declared grid. Distribution
copulas use the selected joint-CDF influence. Fixed-bandwidth density
copulas use the complete same-sample ratio influence.
Nearest-neighbor density simultaneous bands also combine the joint-density
and all estimated marginal-density influences on the same observations,
including their covariance in the density ratio. Generalized-neighbor
factors retain the selected query radii as fixed; adaptive-neighbor factors
include the existing random-radius contributions in both joint and marginal
densities. The fitted inverse coordinates remain fixed for these working
targets. A one-dimensional density ratio has exactly zero simultaneous
variability when its positive numerator and sole marginal are the same
canonical primitive. These new simultaneous scales do not replace the
existing nearest-neighbor pointwise or Bonferroni scales.
These are finite-grid selected-smoothing variability bands, not
bias-corrected population or continuum confidence bands. Unavailable
incumbent uncertainty, nonregular support/radius geometry and memory-limited
grids retain NA simultaneous limits with a specific notice. Adaptive-neighbor
density and distribution bands include regular finite-bound and beta-kernel
routes through a separate simultaneous influence scale. The existing
se(), pointwise and Bonferroni values are unchanged, including their
NA values where marginal errors are not implemented. Thus
band="all" may contain finite simultaneous limits together with
unavailable marginal limits. Ordinary fractional neighbor counts use the
point estimator's canonical rounding. Extended maximum-radius counts require
a separate endpoint or tail law and remain unavailable for these bands.
Numerical precision checks can also make a requested band unavailable;
they never replace the fitted point estimates. Beta checks compare the same
shape with an independent PDF implementation and propagate the discrepancy;
this is a numerical agreement check, not a rigorous special-function bound.
band="all" retains pointwise and Bonferroni intervals and adds the
qualified simultaneous wireframe.
npcopula returns an object of class "npcopula". The main
components are:
copula |
estimated copula distribution value or copula density value. |
u1, u2, ...
|
marginal probability coordinates associated with the sample realizations or evaluation grid. |
x, y, ...
|
marginal quasi-inverse coordinates corresponding to the requested probability grid when grid evaluation is used. |
bws |
selected unconditional distribution or density bandwidth object. |
eval |
data frame containing the copula values, probability coordinates, and
quasi-inverse coordinates. |
copulaerr |
stored asymptotic standard errors when |
The source data, target, evaluation route, grid dimensions, and timing
metadata are retained as list components. The functions
fitted, predict, se,
summary, as.data.frame, and
plot support "npcopula" objects.
The copula distribution target is
; the copula density
target is . The mixed-data
kernel implementation follows Racine (2015), with quasi-inversion in
the sense of Nelsen (2006). For the underlying mixed-data density and
distribution estimators, see Li and Racine (2007), Chapter 1
Density Estimation, Chapter 3 Kernel Estimation with
Mixed Data, and Racine (2019), Chapter 2 Continuous Density
and Cumulative Distribution Functions.
Use a data.frame rather than cbind for
mixed data so that ordered variables remain ordered. Unordered
factors are not valid for copula estimation in this implementation.
Jeffrey S. Racine [email protected]
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Nelsen, R.B. (2006), An Introduction to Copulas, Second Edition, Springer.
Racine, J.S. (2015), “Mixed Data Kernel Copulas”, Empirical Economics, 48, 37–59.
Racine, J.S. (2019), An Introduction to the Advanced Theory and Practice of Nonparametric Econometrics: A Replicable Approach Using R.
npudistbw, npudist,
npudensbw, npudens,
np.kernels, np.options,
plot
## Not run: library("MASS") ## Example 1: bivariate mixed data, continuous x and ordered y. set.seed(42) n <- 1000 n.eval <- 30 rho <- 0.99 mu <- c(0, 0) Sigma <- matrix(c(1, rho, rho, 1), 2, 2) xy <- mvrnorm(n = n, mu = mu, Sigma = Sigma) mydat <- data.frame( x = xy[, 1], y = ordered(as.integer(cut(xy[, 2], quantile(xy[, 2], seq(0, 1, by = .1)), include.lowest = TRUE)) - 1) ) grid.seq <- seq(0, 1, length.out = n.eval) grid.dat <- data.frame(u1 = grid.seq, u2 = grid.seq) ## Estimate the copula distribution from an npudistbw() object. bw.cdf <- npudistbw(~ x + y, data = mydat, nmulti = 1) copula <- npcopula(bws = bw.cdf, data = mydat, u = grid.dat) summary(copula) ## Native plotting replaces the older manual contour(), persp(), and ## empirical scatterplot calls. plot(copula, perspective = FALSE, view = "contour") plot(copula, perspective = FALSE, view = "image") plot(copula, view = "fixed", zlim = c(0, 1)) if (requireNamespace("rgl", quietly = TRUE)) plot(copula, view = "fixed", renderer = "rgl", zlim = c(0, 1)) plot(copula) ## Plot empirical copula coordinates from the retained sample data. plot(copula, view = "empirical") ## Or request the four-panel base-graphics diagnostic display. plot(copula, view = "all") ## Estimate and plot the copula density from an npudensbw() object. bw.pdf <- npudensbw(~ x + y, data = mydat, nmulti = 1) copula.dens <- npcopula(bws = bw.pdf, data = mydat, u = grid.dat) summary(copula.dens) plot(copula.dens, view = "fixed") if (requireNamespace("rgl", quietly = TRUE)) plot(copula.dens, view = "fixed", renderer = "rgl") plot(copula.dens) ## Intervals are available for two-dimensional grid surfaces. plot(copula, errors = "asymptotic", band = "pointwise") plot(copula, errors = "bootstrap", bootstrap = "inid", B = 399, band = "pointwise") ## Prediction evaluates the retained bandwidth object on a supplied ## probability grid. predict(copula, u = data.frame(x = c(0.25, 0.75), y = c(0.25, 0.75))) predict(copula, newdata = data.frame(u1 = c(0.25, 0.75), u2 = c(0.25, 0.75))) ## Example 2: bivariate continuous data. set.seed(42) n <- 1000 n.eval <- 30 rho <- 0.99 mu <- c(0, 0) Sigma <- matrix(c(1, rho, rho, 1), 2, 2) xy <- mvrnorm(n = n, mu = mu, Sigma = Sigma) mydat <- data.frame(x = xy[, 1], y = xy[, 2]) grid.seq <- seq(0, 1, length.out = n.eval) grid.dat <- data.frame(u1 = grid.seq, u2 = grid.seq) bw.cdf <- npudistbw(~ x + y, data = mydat, nmulti = 1) copula <- npcopula(bws = bw.cdf, data = mydat, u = grid.dat) summary(copula) plot(copula, perspective = FALSE, view = "contour") plot(copula, perspective = FALSE, view = "image") plot(copula, view = "fixed", zlim = c(0, 1)) if (requireNamespace("rgl", quietly = TRUE)) plot(copula, view = "fixed", renderer = "rgl", zlim = c(0, 1)) plot(copula) plot(copula, view = "empirical") plot(copula, view = "all") bw.pdf <- npudensbw(~ x + y, data = mydat, nmulti = 1) copula.dens <- npcopula(bws = bw.pdf, data = mydat, u = grid.dat) summary(copula.dens) plot(copula.dens, view = "fixed", zlim = c(0, 40)) if (requireNamespace("rgl", quietly = TRUE)) plot(copula.dens, view = "fixed", renderer = "rgl", zlim = c(0, 40)) plot(copula.dens, zlim = c(0, 40)) ## The formula interface is a shorter route when bandwidths do not need ## to be reused explicitly. copula.short <- npcopula(~ x + y, data = mydat, neval = n.eval, nmulti = 1) plot(copula.short, view = "all") ## End(Not run)## Not run: library("MASS") ## Example 1: bivariate mixed data, continuous x and ordered y. set.seed(42) n <- 1000 n.eval <- 30 rho <- 0.99 mu <- c(0, 0) Sigma <- matrix(c(1, rho, rho, 1), 2, 2) xy <- mvrnorm(n = n, mu = mu, Sigma = Sigma) mydat <- data.frame( x = xy[, 1], y = ordered(as.integer(cut(xy[, 2], quantile(xy[, 2], seq(0, 1, by = .1)), include.lowest = TRUE)) - 1) ) grid.seq <- seq(0, 1, length.out = n.eval) grid.dat <- data.frame(u1 = grid.seq, u2 = grid.seq) ## Estimate the copula distribution from an npudistbw() object. bw.cdf <- npudistbw(~ x + y, data = mydat, nmulti = 1) copula <- npcopula(bws = bw.cdf, data = mydat, u = grid.dat) summary(copula) ## Native plotting replaces the older manual contour(), persp(), and ## empirical scatterplot calls. plot(copula, perspective = FALSE, view = "contour") plot(copula, perspective = FALSE, view = "image") plot(copula, view = "fixed", zlim = c(0, 1)) if (requireNamespace("rgl", quietly = TRUE)) plot(copula, view = "fixed", renderer = "rgl", zlim = c(0, 1)) plot(copula) ## Plot empirical copula coordinates from the retained sample data. plot(copula, view = "empirical") ## Or request the four-panel base-graphics diagnostic display. plot(copula, view = "all") ## Estimate and plot the copula density from an npudensbw() object. bw.pdf <- npudensbw(~ x + y, data = mydat, nmulti = 1) copula.dens <- npcopula(bws = bw.pdf, data = mydat, u = grid.dat) summary(copula.dens) plot(copula.dens, view = "fixed") if (requireNamespace("rgl", quietly = TRUE)) plot(copula.dens, view = "fixed", renderer = "rgl") plot(copula.dens) ## Intervals are available for two-dimensional grid surfaces. plot(copula, errors = "asymptotic", band = "pointwise") plot(copula, errors = "bootstrap", bootstrap = "inid", B = 399, band = "pointwise") ## Prediction evaluates the retained bandwidth object on a supplied ## probability grid. predict(copula, u = data.frame(x = c(0.25, 0.75), y = c(0.25, 0.75))) predict(copula, newdata = data.frame(u1 = c(0.25, 0.75), u2 = c(0.25, 0.75))) ## Example 2: bivariate continuous data. set.seed(42) n <- 1000 n.eval <- 30 rho <- 0.99 mu <- c(0, 0) Sigma <- matrix(c(1, rho, rho, 1), 2, 2) xy <- mvrnorm(n = n, mu = mu, Sigma = Sigma) mydat <- data.frame(x = xy[, 1], y = xy[, 2]) grid.seq <- seq(0, 1, length.out = n.eval) grid.dat <- data.frame(u1 = grid.seq, u2 = grid.seq) bw.cdf <- npudistbw(~ x + y, data = mydat, nmulti = 1) copula <- npcopula(bws = bw.cdf, data = mydat, u = grid.dat) summary(copula) plot(copula, perspective = FALSE, view = "contour") plot(copula, perspective = FALSE, view = "image") plot(copula, view = "fixed", zlim = c(0, 1)) if (requireNamespace("rgl", quietly = TRUE)) plot(copula, view = "fixed", renderer = "rgl", zlim = c(0, 1)) plot(copula) plot(copula, view = "empirical") plot(copula, view = "all") bw.pdf <- npudensbw(~ x + y, data = mydat, nmulti = 1) copula.dens <- npcopula(bws = bw.pdf, data = mydat, u = grid.dat) summary(copula.dens) plot(copula.dens, view = "fixed", zlim = c(0, 40)) if (requireNamespace("rgl", quietly = TRUE)) plot(copula.dens, view = "fixed", renderer = "rgl", zlim = c(0, 40)) plot(copula.dens, zlim = c(0, 40)) ## The formula interface is a shorter route when bandwidths do not need ## to be reused explicitly. copula.short <- npcopula(~ x + y, data = mydat, neval = n.eval, nmulti = 1) plot(copula.short, view = "all") ## End(Not run)
npdeneqtest implements a consistent integrated squared
difference test for equality of densities as described in Li, Maasoumi,
and Racine (2009).
npdeneqtest(x = NULL, y = NULL, bw.x = NULL, bw.y = NULL, B = 399, random.seed = 42, ...)npdeneqtest(x = NULL, y = NULL, bw.x = NULL, bw.y = NULL, B = 399, random.seed = 42, ...)
These arguments identify the two samples and any supplied bandwidths.
bw.x, bw.y
|
optional common bandwidth specification. If neither is supplied, one
bandwidth is selected on the pooled sample by least-squares cross-validation
( |
x, y
|
data frames for the two samples for which one wishes to test equality of densities. The variables in each data frame must be the same (i.e. have identical names). |
These arguments control bootstrap replication and reproducibility settings.
B |
an integer value specifying the number of bootstrap
replications to use. Defaults to |
random.seed |
an integer used to seed R's random number generator. This is to ensure replicability. Defaults to 42. |
Further arguments are passed to the bandwidth-selection routines used by the test.
... |
additional arguments supplied to specify the bandwidth
type, kernel types, and so on. These selection arguments are used only
when both |
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
npdeneqtest computes the integrated squared density difference
between the estimated densities/probabilities of two samples having
identical variables/datatypes. See Li, Maasoumi, and Racine (2009) for
details.
The same bandwidth is held fixed in both samples and every bootstrap
replication. Automatic selection uses one pooled-sample search, followed by
a harmonic-mean reference-size adjustment. Write
and , where the sample sizes count
complete observations. Retaining the pooled spread estimates, continuous
bandwidths are multiplied by and categorical
bandwidths by , following the scale-factor convention
of npudensbw. Here is the continuous kernel order
(two by default), and is the number of continuous variables.
For the default second-order kernel the continuous exponent is
. Categorical parameters cannot exceed their kernel's permitted
maximum: an adjusted value above that maximum is set to the maximum and a
warning names the affected variables.
Under a common density, the leading variance coefficient of the equally
weighted average of the two density-estimation risks is
. This motivates the common reference size;
it is not a claim of optimal test power or exact finite-sample calibration.
The mixed-data and higher-order adjustments use the existing bandwidth
scaling convention. This rule differs from the archived first-sample
simulation implementation and from unadjusted pooled selection.
To use an unadjusted pooled bandwidth, construct it with
npudensbw(dat = rbind(x, y), bwmethod = "cv.ls") and supply it as
bw.x. Explicit bw.x/bw.y are never rescaled.
Likewise, bws = ..., bandwidth.compute = FALSE in ...
remains a manual specification, with scale factors interpreted using
x's complete observations rather than the pool.
Categorical coordinates use the union of the declared levels in both samples
and supplied bandwidth objects, including unused levels. The same domain
and effective kernel metadata are retained in every contraction and bootstrap
draw. Ordered domains must have an unambiguous common order; otherwise declare
the same ordered levels in both samples. Automatic selection uses both
samples with this common metadata.
A raw numeric bandwidth retains the default raw kernel-sum conventions;
a density bandwidth object retains its selected density-kernel conventions,
including normalized ordered Li–Racine masses. Selection arguments in
... do not override an explicitly supplied bandwidth specification.
With fixed, unbounded bandwidths, pooled bootstrap samples are represented by multiplicities on their common support and processed in bounded groups. Multi-response kernel sums then reuse the fixed geometry for the first- and second-power contractions without constructing a dense kernel matrix. Boundary-normalized and nearest-neighbour specifications are not supported by this density-equality statistic.
npdeneqtest returns an object of type deneqtest with the
following components
Tn |
the (standardized) statistic |
In |
the (unstandardized) statistic |
Tn.bootstrap |
contains the bootstrap replications of |
In.bootstrap |
contains the bootstrap replications of |
Tn.P |
the P-value of the |
In.P |
the P-value of the |
boot.num |
number of bootstrap replications |
summary supports object of type deneqtest.
The bootstrap upper-tail p-value is the proportion of bootstrap statistics greater than or equal to the observed statistic. Ties count as at least as extreme, giving the conservative tie convention for discrete statistics. This is the ordinary bootstrap proportion, without an add-one correction; a reported zero is possible with a finite number of replications.
npdeneqtest compares two distributions by estimating the
integrated squared difference between their density or probability
functions. The two samples must have matching variables and data
types because the statistic compares like with like.
For book-length background, see Li and Racine (2007), Chapter 12 Model Specification Tests, especially Section 12.2, and Chapter 13 Nonsmoothing Tests, especially Section 13.2. For density and mixed-data density context, see Racine (2019), Chapters 2 and 3.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
It is crucial that both data frames have the same variable names.
Incomplete rows are omitted independently from each sample before bandwidth selection, bootstrap resampling and computation of the statistic. Factor levels are retained. Each sample must contain at least two complete observations. Supplying one bandwidth reuses it for both samples; it is not reselected when the other bandwidth argument is missing.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Li, Q. and E. Maasoumi and J.S. Racine (2009), “A Nonparametric Test for Equality of Distributions with Mixed Categorical and Continuous Data,” Journal of Econometrics, 148, pp 186-200.
np.kernels, np.options, plot
npdeptest,npsdeptest,npsymtest,npunitest
## Not run: set.seed(1234) ## Distributions are equal n <- 250 sample.A <- data.frame(x=rnorm(n)) sample.B <- data.frame(x=rnorm(n)) npdeneqtest(sample.A,sample.B,B=99) if (interactive()) Sys.sleep(5) ## Distributions are unequal sample.A <- data.frame(x=rnorm(n)) sample.B <- data.frame(x=rchisq(n,df=5)) npdeneqtest(sample.A,sample.B,B=99) ## Mixed datatypes, distributions are equal sample.A <- data.frame(a=rnorm(n),b=factor(rbinom(n,2,.5))) sample.B <- data.frame(a=rnorm(n),b=factor(rbinom(n,2,.5))) npdeneqtest(sample.A,sample.B,B=99) if (interactive()) Sys.sleep(5) ## Mixed datatypes, distributions are unequal sample.A <- data.frame(a=rnorm(n),b=factor(rbinom(n,2,.5))) sample.B <- data.frame(a=rnorm(n,sd=10),b=factor(rbinom(n,2,.25))) npdeneqtest(sample.A,sample.B,B=99) ## End(Not run)## Not run: set.seed(1234) ## Distributions are equal n <- 250 sample.A <- data.frame(x=rnorm(n)) sample.B <- data.frame(x=rnorm(n)) npdeneqtest(sample.A,sample.B,B=99) if (interactive()) Sys.sleep(5) ## Distributions are unequal sample.A <- data.frame(x=rnorm(n)) sample.B <- data.frame(x=rchisq(n,df=5)) npdeneqtest(sample.A,sample.B,B=99) ## Mixed datatypes, distributions are equal sample.A <- data.frame(a=rnorm(n),b=factor(rbinom(n,2,.5))) sample.B <- data.frame(a=rnorm(n),b=factor(rbinom(n,2,.5))) npdeneqtest(sample.A,sample.B,B=99) if (interactive()) Sys.sleep(5) ## Mixed datatypes, distributions are unequal sample.A <- data.frame(a=rnorm(n),b=factor(rbinom(n,2,.5))) sample.B <- data.frame(a=rnorm(n,sd=10),b=factor(rbinom(n,2,.25))) npdeneqtest(sample.A,sample.B,B=99) ## End(Not run)
npdeptest implements the consistent metric entropy test of
pairwise independence as described in Maasoumi and Racine (2002).
npdeptest(data.x = NULL, data.y = NULL, method = c("integration","summation"), bootstrap = TRUE, B = 399, random.seed = 42)npdeptest(data.x = NULL, data.y = NULL, method = c("integration","summation"), bootstrap = TRUE, B = 399, random.seed = 42)
These arguments identify the paired samples being tested.
data.x, data.y
|
two univariate vectors containing two variables that are of type
|
method |
a character string used to specify whether to compute the integral
version or the summation version of the statistic. Can be set as
|
These arguments control bootstrap execution and reproducibility settings.
B |
an integer value specifying the number of bootstrap
replications to use. Defaults to |
bootstrap |
a logical value which specifies whether to conduct
the bootstrap test or not. If set to |
random.seed |
an integer used to seed R's random number generator. This is to ensure replicability. Defaults to 42. |
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
npsdeptest computes the nonparametric metric entropy
(normalized Hellinger of Granger, Maasoumi and Racine (2004)) for
testing pairwise nonlinear dependence between the densities of two
data series. See Maasoumi and Racine (2002) for details. Default
bandwidths are of the Kullback-Leibler variety obtained via
likelihood cross-validation. The null distribution is obtained via
bootstrap resampling under the null of pairwise independence.
npdeptest computes the distance between the joint distribution
and the product of marginals (i.e. the joint distribution under the
null), . Examples include, (a) a measure/test of “fit”,
for in-sample values of a variable and its fitted values,
, and (b) a measure of “predictability” for
a variable and its predicted values (from
a user implemented model).
The summation version of this statistic will be numerically unstable
when data.x and data.y lack common support or are sparse
(the summation version involves division of densities while the
integration version involves differences). Warning messages are
produced should this occur (‘integration recommended’) and should be
heeded.
npdeptest returns an object of type deptest with the
following components
Srho |
the statistic |
Srho.bootstrap.vec |
contains the bootstrap replications of
|
P |
the P-value of the Srho statistic |
bootstrap |
a logical value indicating whether bootstrapping was performed |
boot.num |
number of bootstrap replications |
bw.data.x |
the numeric bandwidth for |
bw.data.y |
the numeric bandwidth for
|
bw.joint |
the numeric matrix of bandwidths for |
summary supports object of type deptest.
The bootstrap upper-tail p-value is the proportion of bootstrap statistics greater than or equal to the observed statistic. Ties count as at least as extreme, giving the conservative tie convention for discrete statistics. This is the ordinary bootstrap proportion, without an add-one correction; a reported zero is possible with a finite number of replications.
npdeptest compares the joint density or probability law of two
variables with the product of their marginals. Departures from the
product form indicate dependence, lack of fit, or predictability
depending on how the two inputs are constructed.
For book-length background, see Li and Racine (2007), Chapter 13 Nonsmoothing Tests, especially Sections 13.4 and 13.5, and Chapter 12 Model Specification Tests, especially Sections 12.4.1 and 12.4.3. For entropy and density context, see Racine (2019), Chapter 2.
The integration version uses deterministic tensor-product,
corrected composite trapezoidal quadrature. Along each axis the domain
extends eight relevant bandwidths beyond the observed support and uses
two evaluation points per smallest relevant bandwidth. A registered
native callback evaluates the Gaussian marginal and joint densities in
bounded tiles, so package-owned working memory does not grow as a dense
sample-by-quadrature array. The integration version is generally more
computationally demanding than summation, but avoids the density
division that can make the summation statistic unstable.
The summation version fuses both marginal density sums and the
joint density sum in one registered native pass with constant auxiliary
storage. During bootstrapping, bounded groups of sampled data.x
indices share the invariant data.y marginal work while retaining
every draw's positionwise pairing, reduction order, and output order.
Workspace grows only with the sample size times the bounded group size;
no dense sample-by-sample kernel matrix is retained. Counts alone are not
used because they would discard the required pairing with data.y.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Granger, C.W. and E. Maasoumi and J.S. Racine (2004), “A dependence metric for possibly nonlinear processes”, Journal of Time Series Analysis, 25, 649-669.
Maasoumi, E. and J.S. Racine (2002), “Entropy and Predictability of Stock Market Returns,” Journal of Econometrics, 107, 2, pp 291-312.
np.kernels, np.options, plot
npdeneqtest,npsdeptest,npsymtest,npunitest
## Not run: set.seed(1234) ## Test/measure lack of fit between y and its fitted value from a ## regression model when x is relevant using the `summation' version. n <- 100 x <- rnorm(n) y <- 1 + x + rnorm(n) model <- lm(y~x) y.fit <- fitted(model) npdeptest(y,y.fit,B=99,method="summation") if (interactive()) Sys.sleep(5) ## Test/measure lack of fit between y and its fitted value from a ## regression model when x is irrelevant using the `summation' version. n <- 100 x <- runif(n,-2,2) y <- 1 + rnorm(n) model <- lm(y~x) y.fit <- fitted(model) npdeptest(y,y.fit,B=99,method="summation") ## Test/measure lack of fit between y and its fitted value from a ## regression model when x is relevant using the `integration' ## version (default, slower than summation version). n <- 100 x <- rnorm(n) y <- 1 + x + rnorm(n) model <- lm(y~x) y.fit <- fitted(model) npdeptest(y,y.fit,B=99) if (interactive()) Sys.sleep(5) ## Test/measure lack of fit between y and its fitted value from a ## regression model when x is irrelevant using the `integration' ## version (default, slower than summation version). n <- 100 x <- runif(n,-2,2) y <- 1 + rnorm(n) model <- lm(y~x) y.fit <- fitted(model) npdeptest(y,y.fit,B=99) ## End(Not run)## Not run: set.seed(1234) ## Test/measure lack of fit between y and its fitted value from a ## regression model when x is relevant using the `summation' version. n <- 100 x <- rnorm(n) y <- 1 + x + rnorm(n) model <- lm(y~x) y.fit <- fitted(model) npdeptest(y,y.fit,B=99,method="summation") if (interactive()) Sys.sleep(5) ## Test/measure lack of fit between y and its fitted value from a ## regression model when x is irrelevant using the `summation' version. n <- 100 x <- runif(n,-2,2) y <- 1 + rnorm(n) model <- lm(y~x) y.fit <- fitted(model) npdeptest(y,y.fit,B=99,method="summation") ## Test/measure lack of fit between y and its fitted value from a ## regression model when x is relevant using the `integration' ## version (default, slower than summation version). n <- 100 x <- rnorm(n) y <- 1 + x + rnorm(n) model <- lm(y~x) y.fit <- fitted(model) npdeptest(y,y.fit,B=99) if (interactive()) Sys.sleep(5) ## Test/measure lack of fit between y and its fitted value from a ## regression model when x is irrelevant using the `integration' ## version (default, slower than summation version). n <- 100 x <- runif(n,-2,2) y <- 1 + rnorm(n) model <- lm(y~x) y.fit <- fitted(model) npdeptest(y,y.fit,B=99) ## End(Not run)
npindex computes a semiparametric single index model
for a dependent variable and -variate explanatory data using
the model , given a
set of evaluation points, training points (consisting of explanatory
data and dependent data), and a npindexbw bandwidth
specification. Note that for this semiparametric estimator, the
bandwidth object contains parameters for the single index model and
the (scalar) bandwidth for the index function.
npindex(bws, ..., B = 399) ## S3 method for class 'formula' npindex(bws, data = NULL, newdata = NULL, y.eval = NULL, se = TRUE, ..., se.type = c("asymptotic", "bootstrap")) ## Default S3 method: npindex(bws, txdat, tydat, nomad = FALSE, se = TRUE, ..., se.type = c("asymptotic", "bootstrap")) ## S3 method for class 'sibandwidth' npindex(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), exdat, eydat, B = 399, se = TRUE, gradients = FALSE, residuals = FALSE, ..., se.type = c("asymptotic", "bootstrap"), y.eval = NULL)npindex(bws, ..., B = 399) ## S3 method for class 'formula' npindex(bws, data = NULL, newdata = NULL, y.eval = NULL, se = TRUE, ..., se.type = c("asymptotic", "bootstrap")) ## Default S3 method: npindex(bws, txdat, tydat, nomad = FALSE, se = TRUE, ..., se.type = c("asymptotic", "bootstrap")) ## S3 method for class 'sibandwidth' npindex(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), exdat, eydat, B = 399, se = TRUE, gradients = FALSE, residuals = FALSE, ..., se.type = c("asymptotic", "bootstrap"), y.eval = NULL)
These arguments identify the bandwidth specification, formula/data interface, and training data.
bws |
a bandwidth specification. This can be set as a
|
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
txdat |
a |
tydat |
a one (1) dimensional numeric or integer vector of dependent data, each
element |
This argument controls the recommended automatic local-polynomial NOMAD route, which jointly selects continuous polynomial degree and bandwidths when these are computed inside npindex.
nomad |
logical shortcut passed through to |
These arguments control where the single-index fit is evaluated and which evaluation quantities are returned.
exdat |
a |
eydat |
a one (1) dimensional numeric or integer vector of the true values of the dependent variable. Optional, and used only to calculate the true errors. |
newdata |
An optional data frame in which to look for evaluation data. If omitted, the training data are used. |
y.eval |
Selects the outcomes used for goodness-of-fit diagnostics. The default
|
These arguments control residuals, gradients, and asymptotic or bootstrap inference.
B |
an integer specifying the number of bootstrap replications to use
when |
se |
a logical value requesting asymptotic coefficient covariance and standard
errors for the conditional mean and, when |
se.type |
the standard-error method for the conditional mean and gradients:
|
gradients |
a logical value indicating that you want gradients computed and returned.
Defaults to |
residuals |
a logical value indicating that you want residuals computed and
returned in the resulting |
Further arguments are passed to the bandwidth-selection counterpart when bandwidths are not supplied.
... |
additional arguments supplied to specify the parameters to the
|
New bandwidth objects expand factors into the retained R contrast design
described in npindexbw. Training refits, prediction and plots
reuse the same columns, levels and contrasts. Numeric scores and older saved
bandwidth objects retain their existing interpretation. Supply raw predictor
data to the public fitting and prediction interfaces; expansion is automatic.
Coefficients, covariance and gradients use expanded design-column names.
Gradients for factor contrast columns are derivatives of the numerical
design extension, ; they are not the effect of
switching between observed categories. Such effects require comparing
predictions at the desired categories. No coefficient is estimated for the
intercept, which is absorbed into the unknown link.
Klein–Spady coefficient covariance uses the link derivative multiplied by
covariates centered on their conditional means given the index. This corrects
a legacy raw-covariate information calculation, including for numeric-only
inputs. Ichimura retains its conditional-centered sandwich calculation.
Coefficient inference requires additional conditional-moment computation;
se=FALSE skips this work. This correction does not change the search
objective or the conditional fitted-value uncertainty calculation.
Fixed kernel endpoints retained in the bandwidth object are also used by fitting, prediction, inference and bootstrap resamples. They are not recomputed from the evaluation grid or from a resampled training set.
With a formula-derived bandwidth object, supplying only tydat
replaces the evaluated response in retained-training-sample order: one row
per observation retained after the original subset and missing-value selection.
Original excluded rows are not restored; row names or equal lengths do not
imply original-data order. The effective na.action is then applied
jointly to the retained predictors and replacement response; any new omission
indices refer to this retained sample. The selected bandwidths remain fixed,
and the returned object retains the replacement sample for subsequent refits.
Use data for full formula-data replacement, not together with a partial
response replacement. Explicit native training arguments retain their separate
positional contract.
For native (non-formula) objects, named newdata columns are matched
to the retained variable names and reordered as needed. Extra columns are
ignored; missing, duplicate or ambiguous names are errors. An unnamed
matrix or vector remains positional for a single evaluation role.
Explicit native evaluation arguments retain their positional contract and
take precedence over newdata.
For a native bandwidth object, newdata supplies exdat
and, in automatic mode, a named response column supplies evaluation outcomes.
Explicit native evaluation arguments take precedence. This evaluates at the
requested rows without repeating bandwidth selection or re-estimating index
coefficients. For held-out assessment, estimate the coefficients and any
data-selected bandwidths using the training sample.
For Ichimura fits trained on an unordered factor response (or an ordered response without numeric levels), evaluation outcomes must also be factors compatible with the training levels: raw numeric labels do not identify the factor-code scale used for fitting. In automatic mode such numeric outcomes leave diagnostics unavailable, without blocking predictions; explicit evaluation-outcome requests report an error. For ordered training responses with numeric levels, numeric evaluation outcomes on that same scale are also accepted.
Evaluation outcomes affect diagnostics only. In automatic mode, outcomes that
cannot be evaluated, aligned, or validated are treated as unavailable for
diagnostics; predictions remain available. Explicit y.eval=TRUE and
explicitly supplied eydat retain strict validation. Missing outcomes do not remove
predictor-complete prediction rows. Time-series outcomes are matched to the
predictor time coordinates; predictions outside the supplied outcome time
support remain available but are not scored. Scores use observed outcome/prediction
pairs, and are NA when none are available. Formula responses, including
transformations, are evaluated only when their variables are present in
newdata; an ambient response is never substituted. Predictor omission
and row-restoration conventions are unchanged.
Formula variables of class ts, including lagged variables, are
aligned on their common time support before fitting. Other variables
must already have the length of that intersection. Supply explicitly
aligned rows when using native data arguments instead of a formula.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot, plot.np for plotting options.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
A matrix of gradients along with average derivatives are computed and
returned if gradients=TRUE is used.
Single-index coefficients are identified only up to scale, so
npindexbw normalizes the first coefficient to one. The
remaining coefficients describe relative movement in the index
, not standalone linear-model slopes. Holding
other variables fixed, a one-unit increase in changes the
index by the same amount as a -unit increase in
. Where the link derivative exists and is nonzero, this is
also the local marginal-effect ratio relative to . Choose
the first continuous regressor deliberately when coefficient
interpretation is important.
For , the component plotted for
predictor is
Accordingly, plot(..., gradients=TRUE) displays every component
against the common scalar index ; the y-axis identifies
the predictor with respect to which the derivative is taken. These panels
are not partial-dependence plots against the individual values.
When npindex computes its bandwidth object internally,
optimizer controls in ... are passed to npindexbw.
The default optim.method="Nelder-Mead" is a robust
derivative-free starting point for low-dimensional searches, such as
one bandwidth plus only a few index coefficients. For larger
, optim.method="BFGS" can be useful as a performance
and sensitivity comparison, but users should compare objective
values, convergence behavior, and fitted objects because the
single-index criterion can be nonconvex and route-sensitive.
For practitioners who want the recommended automatic local-polynomial degree-and-bandwidth NOMAD route
without spelling out all LP tuning arguments,
npindex(..., nomad=TRUE) and npindexbw(..., nomad=TRUE)
expand missing settings to the same documented preset. Explicit
incompatible settings fail fast rather than being silently rewritten.
npindex returns a singleindex object. The generic
functions fitted, residuals,
coef, vcov, se,
predict, and gradients, extract (or
generate) estimated values, residuals, coefficients,
variance-covariance matrix, asymptotic or bootstrap standard errors on estimates,
predictions, and gradients, respectively, from the returned
object. Furthermore, the functions summary and
plot support objects of this type. The returned object
has the following components:
eval |
evaluation points |
mean |
estimates of the regression function (conditional mean) at the evaluation points |
beta |
the model coefficients |
betavcov |
the asymptotic covariance matrix for the model coefficients |
merr |
standard errors of the regression function estimates |
grad |
estimates of the gradients at each evaluation point |
gerr |
standard errors of the gradient estimates |
mean.grad |
mean (average) gradient over the evaluation points |
mean.gerr |
bootstrapped standard error of the mean gradient estimates |
R2 |
if |
MSE |
if |
MAE |
if |
MAPE |
if |
CORR |
if |
SIGN |
if |
diagnostics.sample |
|
diagnostics.nobs |
Number of observed outcome/prediction pairs scored. |
training.MSE |
For Ichimura fits, the training mean squared error when
training fitted values were computed, otherwise |
confusion.matrix |
if |
CCR.overall |
if |
CCR.byoutcome |
if |
fit.mcfadden |
if |
The single-index model reduces a multivariate predictor to an index,
typically written for continuous
outcomes, with a normalization on for identification.
For binary outcomes, the Klein-Spady route estimates the corresponding
binary-choice probability through the index. The fitted index
regression, gradients, and average derivatives are computed from the
selected index direction and kernel regression fit.
For book-length derivations, see Li and Racine (2007), Chapter 8 Semiparametric Single Index Models, especially Sections 8.1, 8.2.1, 8.4, 8.5, and 8.10. The later workflow treatment is Racine (2019), Chapter 8 Semiparametric Conditional Mean Function Estimation, especially the single-index material.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. For formula evaluation with newdata, an
explicit na.action also applies to the evaluation predictors:
na.omit drops incomplete predictor rows, na.exclude
restores their positions with NA in predictions, standard errors
and requested gradients, and na.fail rejects them. When omitted,
evaluation uses the current model-frame missing-data policy. Evaluation
outcomes are scored separately and do not remove prediction rows.
With both replacement training data and evaluation data, the policy is
applied separately to each frame. An evaluation-only request does not
refilter retained training data. Explicit native evaluation arguments
retain precedence and their existing complete-row handling.
Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available.
vcov extracts the asymptotic coefficient covariance computed
when se=TRUE, independently of gradients and se.type.
Its first row and column are zero because the first coefficient is normalized
to one. A singular free-coefficient information matrix raises an informative
error; the calculation does not substitute a generalized inverse or bootstrap.
In particular, the local-constant uniform kernel has zero first derivative
away from its support boundaries and cannot supply this covariance for free
coefficients. Use se=FALSE for point estimates in that case.
Selecting se.type="bootstrap" does not replace the coefficient
covariance calculation, which remains asymptotic.
The default inference requires additional training derivatives and moments;
it can cost appreciably more than a point-estimate-only fit, especially when
bandwidths have already been selected. Use se=FALSE to omit that work.
Asymptotic fitted-value and gradient standard errors use the same scalar-index
regression calculation as the asymptotic plot intervals, treating the fitted
index coefficients as fixed. They inherit the residual normalization of
Ruppert et al. (1997) described under Standard Errors in
npreg. This is not the separate coefficient covariance
returned by vcov(). Missing training residual information can
therefore make individual fitted-value or gradient errors unavailable
without removing their point estimates.
Local-polynomial index fits also inherit the numerical-ridging policy
described in npreg.
Asymptotic standard errors of average gradients
are not supplied; mean.gerr is available only in bootstrap mode.
Missing quantities can be computed without repeating bandwidth search.
After model <- npindex(...), use
model <- npindex(bws=model$bws, gradients=TRUE, se=TRUE) to add gradients
and asymptotic inference, or se=FALSE for gradients alone. This reuses
both the fitted beta and bandwidth, just as fitting an object returned by
npindexbw() does. The training data must remain recoverable from the
retained state/call, or be supplied explicitly. predict(..., se.fit=TRUE)
uses the fitted object's stored se.type for new evaluation data unless
an explicit se.type is supplied.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Doksum, K. and A. Samarov (1995), “Nonparametric estimation of global functionals and a measure of the explanatory power of covariates regression,” The Annals of Statistics, 23 1443-1473.
Ichimura, H., (1993), “Semiparametric least squares (SLS) and weighted SLS estimation of single-index models,” Journal of Econometrics, 58, 71-120.
Klein, R. W. and R. H. Spady (1993), “An efficient semiparametric estimator for binary response models,” Econometrica, 61, 387-421.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
McFadden, D. and C. Puig and D. Kerschner (1977), “Determinants of the long-run demand for electricity,” Proceedings of the American Statistical Association (Business and Economics Section), 109-117.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options,
plot, plot.np, npindexbw
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): Generate a simple linear model then # estimate it using a semiparametric single index specification and # Ichimura's nonlinear least squares coefficients and bandwidth # (default). Also compute the matrix of gradients and average derivative # estimates. set.seed(12345) n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- x1 - x2 + rnorm(n) # Note - this may take a minute or two depending on the speed of your # computer. Note also that the first element of the vector beta is # normalized to one for identification purposes, and that X must contain # at least one continuous variable. bw <- npindexbw(formula=y~x1+x2) summary(bw) model <- npindex(bws=bw, gradients=TRUE) summary(model) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Or you can visualize the input with plot. if (interactive()) plot(bw) if (interactive()) Sys.sleep(5) # EXAMPLE 1 (INTERFACE=DATA FRAME): Generate a simple linear model then # estimate it using a semiparametric single index specification and # Ichimura's nonlinear least squares coefficients and bandwidth # (default). Also compute the matrix of gradients and average derivative # estimates. set.seed(12345) n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- x1 - x2 + rnorm(n) X <- cbind(x1, x2) # Note - this may take a minute or two depending on the speed of your # computer. Note also that the first element of the vector beta is # normalized to one for identification purposes, and that X must contain # at least one continuous variable. bw <- npindexbw(xdat=X, ydat=y) summary(bw) model <- npindex(bws=bw, gradients=TRUE) summary(model) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Or you can visualize the input with plot. if (interactive()) plot(bw) if (interactive()) Sys.sleep(5) # EXAMPLE 2 (INTERFACE=FORMULA): Generate a simple binary outcome linear # model then estimate it using a semiparametric single index # specification and Klein and Spady's likelihood-based coefficients and # bandwidth (default). Also compute the matrix of gradients and average # derivative estimates. n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) # Note that the first element of the vector beta is normalized to one # for identification purposes, and that X must contain at least one # continuous variable. bw <- npindexbw(formula=y~x1+x2, method="kleinspady") summary(bw) model <- npindex(bws=bw, gradients=TRUE) # Note that, since the outcome is binary, we can assess model # performance using methods appropriate for binary outcomes. We look at # the confusion matrix, various classification ratios, and McFadden et # al's measure of predictive performance. summary(model) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 2 (INTERFACE=DATA FRAME): Generate a simple binary outcome # linear model then estimate it using a semiparametric single index # specification and Klein and Spady's likelihood-based coefficients and # bandwidth (default). Also compute the matrix of gradients and average # derivative estimates. n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) X <- cbind(x1, x2) # Note that the first element of the vector beta is normalized to one # for identification purposes, and that X must contain at least one # continuous variable. bw <- npindexbw(xdat=X, ydat=y, method="kleinspady") summary(bw) model <- npindex(bws=bw, gradients=TRUE) # Note that, since the outcome is binary, we can assess model # performance using methods appropriate for binary outcomes. We look at # the confusion matrix, various classification ratios, and McFadden et # al's measure of predictive performance. summary(model) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 3 (INTERFACE=FORMULA): Replicate the DGP of Klein & Spady # (1993) (see their description on page 405, pay careful attention to # footnote 6 on page 405). set.seed(123) n <- 1000 # x1 is chi-squared having 3 df truncated at 6 standardized by # subtracting 2.348 and dividing by 1.511 x <- rchisq(n, df=3) x1 <- (ifelse(x < 6, x, 6) - 2.348)/1.511 # x2 is normal (0, 1) truncated at +- 2 divided by 0.8796 x <- rnorm(n) x2 <- ifelse(abs(x) < 2 , x, 2) / 0.8796 # y is 1 if y* > 0, 0 otherwise. y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) # Compute the parameter vector and bandwidth. Note that the first # element of the vector beta is normalized to one for identification # purposes, and that X must contain at least one continuous variable. bw <- npindexbw(formula=y~x1+x2, method="kleinspady") # Next, create the evaluation data in order to generate a perspective # plot # Create an evaluation data matrix x1.seq <- seq(min(x1), max(x1), length=50) x2.seq <- seq(min(x2), max(x2), length=50) X.eval <- expand.grid(x1=x1.seq, x2=x2.seq) # Now evaluate the single index model on the evaluation data fit <- fitted(npindex(exdat=X.eval, eydat=rep(1, nrow(X.eval)), bws=bw)) # Finally, coerce the fitted model into a matrix suitable for 3D # plotting via persp() fit.mat <- matrix(fit, 50, 50) # Generate a perspective plot similar to Figure 2 b of Klein and Spady # (1993) persp(x1.seq, x2.seq, fit.mat, col="white", ticktype="detailed", expand=0.5, axes=FALSE, box=FALSE, main="Estimated Semiparametric Probability Perspective", theta=310, phi=25) # EXAMPLE 3 (INTERFACE=DATA FRAME): Replicate the DGP of Klein & Spady # (1993) (see their description on page 405, pay careful attention to # footnote 6 on page 405). set.seed(123) n <- 1000 # x1 is chi-squared having 3 df truncated at 6 standardized by # subtracting 2.348 and dividing by 1.511 x <- rchisq(n, df=3) x1 <- (ifelse(x < 6, x, 6) - 2.348)/1.511 # x2 is normal (0, 1) truncated at +- 2 divided by 0.8796 x <- rnorm(n) x2 <- ifelse(abs(x) < 2 , x, 2) / 0.8796 # y is 1 if y* > 0, 0 otherwise. y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) # Create the X matrix X <- cbind(x1, x2) # Compute the parameter vector and bandwidth. Note that the first # element of the vector beta is normalized to one for identification # purposes, and that X must contain at least one continuous variable. bw <- npindexbw(xdat=X, ydat=y, method="kleinspady") # Next, create the evaluation data in order to generate a perspective # plot # Create an evaluation data matrix x1.seq <- seq(min(x1), max(x1), length=50) x2.seq <- seq(min(x2), max(x2), length=50) X.eval <- expand.grid(x1=x1.seq, x2=x2.seq) # Now evaluate the single index model on the evaluation data fit <- fitted(npindex(exdat=X.eval, eydat=rep(1, nrow(X.eval)), bws=bw)) # Finally, coerce the fitted model into a matrix suitable for 3D # plotting via persp() fit.mat <- matrix(fit, 50, 50) # Generate a perspective plot similar to Figure 2 b of Klein and Spady # (1993) persp(x1.seq, x2.seq, fit.mat, col="white", ticktype="detailed", expand=0.5, axes=FALSE, box=FALSE, main="Estimated Semiparametric Probability Perspective", theta=310, phi=25) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): Generate a simple linear model then # estimate it using a semiparametric single index specification and # Ichimura's nonlinear least squares coefficients and bandwidth # (default). Also compute the matrix of gradients and average derivative # estimates. set.seed(12345) n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- x1 - x2 + rnorm(n) # Note - this may take a minute or two depending on the speed of your # computer. Note also that the first element of the vector beta is # normalized to one for identification purposes, and that X must contain # at least one continuous variable. bw <- npindexbw(formula=y~x1+x2) summary(bw) model <- npindex(bws=bw, gradients=TRUE) summary(model) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Or you can visualize the input with plot. if (interactive()) plot(bw) if (interactive()) Sys.sleep(5) # EXAMPLE 1 (INTERFACE=DATA FRAME): Generate a simple linear model then # estimate it using a semiparametric single index specification and # Ichimura's nonlinear least squares coefficients and bandwidth # (default). Also compute the matrix of gradients and average derivative # estimates. set.seed(12345) n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- x1 - x2 + rnorm(n) X <- cbind(x1, x2) # Note - this may take a minute or two depending on the speed of your # computer. Note also that the first element of the vector beta is # normalized to one for identification purposes, and that X must contain # at least one continuous variable. bw <- npindexbw(xdat=X, ydat=y) summary(bw) model <- npindex(bws=bw, gradients=TRUE) summary(model) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Or you can visualize the input with plot. if (interactive()) plot(bw) if (interactive()) Sys.sleep(5) # EXAMPLE 2 (INTERFACE=FORMULA): Generate a simple binary outcome linear # model then estimate it using a semiparametric single index # specification and Klein and Spady's likelihood-based coefficients and # bandwidth (default). Also compute the matrix of gradients and average # derivative estimates. n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) # Note that the first element of the vector beta is normalized to one # for identification purposes, and that X must contain at least one # continuous variable. bw <- npindexbw(formula=y~x1+x2, method="kleinspady") summary(bw) model <- npindex(bws=bw, gradients=TRUE) # Note that, since the outcome is binary, we can assess model # performance using methods appropriate for binary outcomes. We look at # the confusion matrix, various classification ratios, and McFadden et # al's measure of predictive performance. summary(model) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 2 (INTERFACE=DATA FRAME): Generate a simple binary outcome # linear model then estimate it using a semiparametric single index # specification and Klein and Spady's likelihood-based coefficients and # bandwidth (default). Also compute the matrix of gradients and average # derivative estimates. n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) X <- cbind(x1, x2) # Note that the first element of the vector beta is normalized to one # for identification purposes, and that X must contain at least one # continuous variable. bw <- npindexbw(xdat=X, ydat=y, method="kleinspady") summary(bw) model <- npindex(bws=bw, gradients=TRUE) # Note that, since the outcome is binary, we can assess model # performance using methods appropriate for binary outcomes. We look at # the confusion matrix, various classification ratios, and McFadden et # al's measure of predictive performance. summary(model) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 3 (INTERFACE=FORMULA): Replicate the DGP of Klein & Spady # (1993) (see their description on page 405, pay careful attention to # footnote 6 on page 405). set.seed(123) n <- 1000 # x1 is chi-squared having 3 df truncated at 6 standardized by # subtracting 2.348 and dividing by 1.511 x <- rchisq(n, df=3) x1 <- (ifelse(x < 6, x, 6) - 2.348)/1.511 # x2 is normal (0, 1) truncated at +- 2 divided by 0.8796 x <- rnorm(n) x2 <- ifelse(abs(x) < 2 , x, 2) / 0.8796 # y is 1 if y* > 0, 0 otherwise. y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) # Compute the parameter vector and bandwidth. Note that the first # element of the vector beta is normalized to one for identification # purposes, and that X must contain at least one continuous variable. bw <- npindexbw(formula=y~x1+x2, method="kleinspady") # Next, create the evaluation data in order to generate a perspective # plot # Create an evaluation data matrix x1.seq <- seq(min(x1), max(x1), length=50) x2.seq <- seq(min(x2), max(x2), length=50) X.eval <- expand.grid(x1=x1.seq, x2=x2.seq) # Now evaluate the single index model on the evaluation data fit <- fitted(npindex(exdat=X.eval, eydat=rep(1, nrow(X.eval)), bws=bw)) # Finally, coerce the fitted model into a matrix suitable for 3D # plotting via persp() fit.mat <- matrix(fit, 50, 50) # Generate a perspective plot similar to Figure 2 b of Klein and Spady # (1993) persp(x1.seq, x2.seq, fit.mat, col="white", ticktype="detailed", expand=0.5, axes=FALSE, box=FALSE, main="Estimated Semiparametric Probability Perspective", theta=310, phi=25) # EXAMPLE 3 (INTERFACE=DATA FRAME): Replicate the DGP of Klein & Spady # (1993) (see their description on page 405, pay careful attention to # footnote 6 on page 405). set.seed(123) n <- 1000 # x1 is chi-squared having 3 df truncated at 6 standardized by # subtracting 2.348 and dividing by 1.511 x <- rchisq(n, df=3) x1 <- (ifelse(x < 6, x, 6) - 2.348)/1.511 # x2 is normal (0, 1) truncated at +- 2 divided by 0.8796 x <- rnorm(n) x2 <- ifelse(abs(x) < 2 , x, 2) / 0.8796 # y is 1 if y* > 0, 0 otherwise. y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) # Create the X matrix X <- cbind(x1, x2) # Compute the parameter vector and bandwidth. Note that the first # element of the vector beta is normalized to one for identification # purposes, and that X must contain at least one continuous variable. bw <- npindexbw(xdat=X, ydat=y, method="kleinspady") # Next, create the evaluation data in order to generate a perspective # plot # Create an evaluation data matrix x1.seq <- seq(min(x1), max(x1), length=50) x2.seq <- seq(min(x2), max(x2), length=50) X.eval <- expand.grid(x1=x1.seq, x2=x2.seq) # Now evaluate the single index model on the evaluation data fit <- fitted(npindex(exdat=X.eval, eydat=rep(1, nrow(X.eval)), bws=bw)) # Finally, coerce the fitted model into a matrix suitable for 3D # plotting via persp() fit.mat <- matrix(fit, 50, 50) # Generate a perspective plot similar to Figure 2 b of Klein and Spady # (1993) persp(x1.seq, x2.seq, fit.mat, col="white", ticktype="detailed", expand=0.5, axes=FALSE, box=FALSE, main="Estimated Semiparametric Probability Perspective", theta=310, phi=25) ## End(Not run)
npindexbw computes a npindexbw bandwidth specification
using the model . For continuous , the approach is that of Hardle, Hall
and Ichimura (1993) which jointly minimizes a least-squares
cross-validation function with respect to the parameters and
bandwidth. For binary , a likelihood-based cross-validation
approach is employed which jointly maximizes a likelihood
cross-validation function with respect to the parameters and
bandwidth. The bandwidth object contains parameters for the single
index model and the (scalar) bandwidth for the index function.
npindexbw(...) ## S3 method for class 'formula' npindexbw(formula, data, subset, na.action, call, ...) ## Default S3 method: npindexbw(xdat = stop("training data xdat missing"), ydat = stop("training data ydat missing"), bws, bandwidth.compute = TRUE, basis = c("glp", "additive", "tensor"), bernstein.basis = FALSE, degree = NULL, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, nmulti, nomad.remin = FALSE, powell.remin = TRUE, only.optimize.beta, optim.abstol, optim.maxattempts, optim.maxit, optim.method, optim.reltol, random.seed, regtype = c("lc", "ll", "lp"), scale.factor.init.lower = 0.1, scale.factor.init.upper = 2.0, scale.factor.init = 0.5, scale.factor.search.lower = NULL, ..., nomad.opts = list()) ## S3 method for class 'sibandwidth' npindexbw(xdat = stop("training data xdat missing"), ydat = stop("training data ydat missing"), bws, bandwidth.compute = TRUE, .certify.selected = TRUE, nmulti, only.optimize.beta = FALSE, optim.abstol = .Machine$double.eps, optim.maxattempts = 10, optim.maxit = 500, optim.method = c("Nelder-Mead", "BFGS", "CG"), optim.reltol = sqrt(.Machine$double.eps), random.seed = 42, scale.factor.init.lower = 0.1, scale.factor.init.upper = 2.0, scale.factor.init = 0.5, scale.factor.search.lower = NULL, .restore.first.start = TRUE, ..., .fixed.h.lower = NULL)npindexbw(...) ## S3 method for class 'formula' npindexbw(formula, data, subset, na.action, call, ...) ## Default S3 method: npindexbw(xdat = stop("training data xdat missing"), ydat = stop("training data ydat missing"), bws, bandwidth.compute = TRUE, basis = c("glp", "additive", "tensor"), bernstein.basis = FALSE, degree = NULL, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, nmulti, nomad.remin = FALSE, powell.remin = TRUE, only.optimize.beta, optim.abstol, optim.maxattempts, optim.maxit, optim.method, optim.reltol, random.seed, regtype = c("lc", "ll", "lp"), scale.factor.init.lower = 0.1, scale.factor.init.upper = 2.0, scale.factor.init = 0.5, scale.factor.search.lower = NULL, ..., nomad.opts = list()) ## S3 method for class 'sibandwidth' npindexbw(xdat = stop("training data xdat missing"), ydat = stop("training data ydat missing"), bws, bandwidth.compute = TRUE, .certify.selected = TRUE, nmulti, only.optimize.beta = FALSE, optim.abstol = .Machine$double.eps, optim.maxattempts = 10, optim.maxit = 500, optim.method = c("Nelder-Mead", "BFGS", "CG"), optim.reltol = sqrt(.Machine$double.eps), random.seed = 42, scale.factor.init.lower = 0.1, scale.factor.init.upper = 2.0, scale.factor.init = 0.5, scale.factor.search.lower = NULL, .restore.first.start = TRUE, ..., .fixed.h.lower = NULL)
These arguments identify the data, formula interface, method label, and whether bandwidths are supplied or computed.
bandwidth.compute |
a logical value which specifies whether to do a numerical search for
bandwidths or not. If set to |
.certify.selected |
internal logical control requiring one raw-objective replay of the selected search point. This argument is used by package search owners and is not intended for direct user control. |
.restore.first.start |
internal logical control enabling bounded restoration of eligible automatically generated raw-invalid first optimizer evaluations. It is used by package search owners and is not intended for direct user control. |
.fixed.h.lower |
internal physical-bandwidth floor passed from a NOMAD search to its fixed-degree refinement. The default retains the direct-call scale-factor domain. This argument is not intended for direct user control. |
bws |
a bandwidth specification. This can be set as a
|
call |
the original function call. This is passed internally by
|
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
formula |
a symbolic description of variables on which bandwidth selection is to be performed. The details of constructing a formula are described below. |
method |
the single index model method, one of either “ichimura”
(Ichimura (1993)) or “kleinspady” (Klein and Spady
(1993)). Defaults to
|
na.action |
a function which indicates what should happen when the data contain
|
subset |
an optional vector specifying a subset of observations to be used in the fitting process. |
xdat |
a |
ydat |
a one (1) dimensional numeric or integer vector of dependent data, each
element |
These arguments control automatic local-polynomial degree search.
degree.max |
optional scalar or integer vector giving upper bounds for automatic
degree search when |
degree.max.cycles |
positive integer giving the maximum number of coordinate-search
sweeps over the degree vector. Ignored for |
degree.min |
optional scalar or integer vector giving lower bounds for automatic
degree search when |
degree.restarts |
non-negative integer giving the number of additional deterministic
coordinate-search restarts. Ignored for |
degree.select |
character string controlling local-polynomial degree handling when
|
degree.start |
optional starting degree vector for automatic coordinate search. If omitted, the search starts from the degree-zero local-constant baseline for the index smoother. |
degree.verify |
logical value indicating whether an automatic degree-search solution
should be exhaustively certified over the admissible degree grid after
the heuristic phase completes. With |
These controls define deterministic and random continuous scale-factor starts and the lower admissibility floor for fixed-bandwidth search.
scale.factor.init |
deterministic initial scale factor for continuous fixed-bandwidth
search. Defaults to |
scale.factor.init.lower |
lower endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.init.upper |
upper endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.search.lower |
optional nonnegative scalar giving the hard lower admissibility
bound for continuous fixed-bandwidth search candidates. Defaults to
|
These arguments control the index smoother, local-polynomial basis, and fixed degree specification.
basis |
local polynomial basis selector used when
|
bernstein.basis |
logical flag used when |
degree |
integer degree vector for continuous predictors when
|
regtype |
a character string specifying local smoothing type for the
nonparametric index regression fit used downstream in
|
These arguments control the optional NOMAD direct-search route for local-polynomial degree and bandwidth search.
nomad |
logical or character shortcut for the recommended automatic local-polynomial
NOMAD route. When |
nomad.nmulti |
non-negative integer controlling the inner
the native crs NOMAD C API multistart count used within each outer
NOMAD restart when |
nomad.opts |
optional named list of native NOMAD parameters forwarded to the
crs NOMAD C API for NOMAD-backed bandwidth searches.
|
nomad.remin |
logical flag controlling the optional second NOMAD hot start. When
|
search.engine |
character string controlling the automatic local-polynomial search
backend when |
These controls set search restart behavior.
nmulti |
integer number of times to restart the process of finding extrema of
the cross-validation function from different (random) initial
points. Defaults to |
powell.remin |
compatibility argument shared with bandwidth families that use the Powell
direction-set solver. Single-index fixed-degree and post-NOMAD refinement
use R |
These arguments control outer optimization behavior for the semiparametric search.
only.optimize.beta |
minimizes the objective function with respect to beta while retaining
the existing polynomial degree and bandwidth (or nearest-neighbor count).
Automatic degree search, including NOMAD and cell search, is not run;
|
optim.abstol |
the absolute convergence tolerance used by |
optim.maxattempts |
maximum number of attempts taken trying to achieve successful
convergence in |
optim.maxit |
maximum number of iterations used by |
optim.method |
method used by the default method is an implementation of that of Nelder and Mead (1965), that uses only function values and is robust but relatively slow. It will work reasonably well for non-differentiable functions. method method The default |
optim.reltol |
relative convergence tolerance used by |
random.seed |
an integer used to seed R's random number generator. This ensures replicability of the numerical search. Defaults to 42. |
These arguments collect remaining controls passed through S3 methods.
... |
additional arguments supplied to specify the parameters to the
|
For newly constructed bandwidth objects, factors enter the linear index
through R model-matrix contrasts. An unordered factor with observed
levels ordinarily contributes coefficients. Ordered factors use
their R contrasts (polynomial contrasts by default), including when their
level labels look numeric. To fit a single coefficient on specified scores
instead, supply those scores as a numeric predictor.
For supported additive formulas, coefficient names and predictor columns
follow model.matrix(). The intercept is absorbed into the unknown
link and is not an index coefficient. The first retained design coefficient
is normalized to one; the package does not reorder predictors to choose a
different normalization. Thus a factor listed first can supply the
normalized contrast coefficient. These are relative index coefficients,
not linear-regression slopes. This representation does not add support for
otherwise unsupported formula syntax.
Native data-frame calls use the corresponding additive design. A manually
supplied bws vector contains one beta for each expanded design column,
in model-matrix order, followed by the scalar bandwidth. Automatic start
vectors use the same coordinates. Numeric-only inputs keep their existing
representation. A new factor design with aliased columns or a constant
direction is rejected: for example, y ~ 0 + x + group supplies all
group indicators and has an unidentified constant direction. Use the
ordinary contrast formula y ~ x + group or independent numeric columns.
Factor levels and the actual contrast matrices are retained at construction. Prediction uses this design even if global contrast options change or an evaluation sample omits some training levels. New evaluation levels are an error. Levels absent from the complete training sample do not identify coefficients. Custom contrasts must remain identifiable on that sample.
Older saved bandwidth objects without retained design metadata preserve
their historical single-score factor representation. Reconstruct a bandwidth
object to adopt the contrast design; the package does not silently reinterpret
an existing coefficient vector. The index.design component records the
raw predictor names, retained levels/contrasts, and expanded column mapping;
coefficient names and dimensions refer to the expanded design.
Formula bandwidth objects retain the prepared training sample (after alignment,
subsetting and missing-value handling) and the resolved missing-value policy.
Later refits use that sample even if constructor variables are rebound.
Supplying explicit training data to the estimator replaces the training data;
evaluation via newdata does not. Retention requires storage proportional
to the sample size times the number of variables, not a pairwise weight matrix.
Older saved objects without this retained state still rely on their original
data bindings; rebuild their bandwidth object from the intended data before
changing those bindings. User-defined transformation and missing-value
functions should not rely on subsequently modified closure state.
The scale.factor.* controls are dimensionless search
controls. The package converts scale factors to bandwidths using the
estimator-specific scaling encoded in the bandwidth object, including
kernel order and the number of continuous variables relevant for the
estimator. Users should not pre-multiply these controls by sample-size
or standard-deviation factors.
scale.factor.init controls the deterministic first search
start when that control is exposed. scale.factor.init.lower
and scale.factor.init.upper define the random multistart
interval when exposed. scale.factor.search.lower is the lower
admissibility bound for continuous fixed-bandwidth search candidates.
The effective first start is max(scale.factor.init,
scale.factor.search.lower) when both controls are present, and the
effective random-start lower endpoint is
max(scale.factor.init.lower, scale.factor.search.lower).
scale.factor.init.upper must be at least that effective lower
endpoint; the package errors rather than silently expanding the user's
interval.
When scale.factor.search.lower is NULL, an existing
bandwidth object's stored floor is inherited when available;
otherwise the package default 0.1 is used. Explicit bandwidths
supplied for storage with bandwidth.compute = FALSE are not
rewritten by the search floor.
Categorical search-start controls such as dfac.init,
lbd.init, and hbd.init have separate semantics and are
not affected by scale.factor.search.lower.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot, plot.np for plotting options.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
We implement Ichimura's (1993) method via joint estimation of the bandwidth and coefficient vector using leave-one-out nonlinear least squares. We implement Klein and Spady's (1993) method maximizing the leave-one-out log likelihood function jointly with respect to the bandwidth and coefficient vector. Note that Klein and Spady's (1993) method is for binary outcomes only, while Ichimura's (1993) method can be applied for any outcome data type (i.e., continuous or discrete).
Invalid outer-search guidance uses the exact declared leave-one-out null: the constant-model least-squares null for Ichimura and the clipped Bernoulli likelihood null for Klein–Spady. Inner regression evaluation remains raw; only terminal invalidity is mapped at the outer boundary. The selected point is replayed once against the raw objective and is rejected if it is not finite and valid.
We impose the identification condition that the first element of the coefficient vector beta is equal to one, while identification also requires that the explanatory variables contain at least one continuous variable.
The scale of and the scale of the unknown link
function are not separately identified, so npindexbw
normalizes the first coefficient to one. The remaining coefficients
should therefore be read relative to the first explanatory variable,
not as standalone linear-model slopes. Holding other variables fixed,
a one-unit increase in changes the index by the same amount
as a -unit increase in . Where the link
derivative exists and is nonzero, marginal-effect ratios satisfy
. Signs and magnitudes are therefore relative to
the chosen first variable and its units; choose the first continuous
regressor deliberately when interpretation is important.
For fixed-bandwidth R optim searches, an automatic raw-invalid
starting bandwidth is doubled while keeping its starting coefficients and
degree fixed. This applies to all supported regression types, kernel orders
and support options, including generated starts in automatic degree-search
children. Each multistart uses its own coefficients' index scale.
Only the first scalar evaluation already
requested by optim is checked. A valid original start continues in
that same optimizer invocation without an additional objective evaluation.
A rejected start does not incur a numerical-gradient stencil.
Restoration permits at most eight doublings (nine starting scalar
evaluations) for each multistart or existing convergence-retry start and
respects the existing search bounds. Each rejected start adds one scalar
evaluation, which can be costly. The random-draw control
scale.factor.init.upper is not a search upper bound, so restoration
may exceed it. Explicit initial bandwidths and bandwidths held by
only.optimize.beta=TRUE are never expanded; a raw-invalid first
evaluation fails with the method, start/retry, attempted bandwidth range,
count and reason. Budget exhaustion also fails the complete call.
This rule does not change subsequent optimizer trials, finite differences, penalties, convergence-retry controls or final exact-point certification. A valid start does not guarantee convergence or a valid final point. Increasing the bandwidth does not guarantee feasibility for higher-order kernels or local-polynomial fits; every attempted start must pass the same raw-objective check. Nearest-neighbour bandwidths and NOMAD's own direct search retain their existing feasibility mechanisms. An explicit NOMAD refinement start is checked but not expanded. No alternative solver or earlier multistart winner is substituted when restoration fails.
optim.method
The default "Nelder-Mead" search is often a good starting
point for low-dimensional single-index problems because it uses only
objective values and is comparatively tolerant of rough objective
surfaces. When is larger, especially when many coefficients
enter , "BFGS" may reduce runtime for some
problems, but it is more dependent on local smoothness and on the
quality of numerical gradient information. For important fits, try
both methods with adequate multistarts and compare the final
objective values, convergence messages, and fitted objects.
npindexbw may be invoked either with a formula-like
symbolic description of variables on which bandwidth selection is to
be performed or through a simpler interface whereby data is
passed directly to the function via the xdat and ydat
parameters. Use of these two interfaces is mutually exclusive.
Note that, unlike most other bandwidth methods in the np
package, this implementation uses the R optim nonlinear
minimization routines and npksum. We have implemented
multistarting and strongly encourage its use in practice. For
exploratory purposes, you may wish to override the default search
tolerances, say, setting optim.reltol=.1 and conduct
multistarting (the default is to restart min(2, ncol(xdat)) times) as is done
for a number of examples. See the optimizer guidance above when
choosing between the default "Nelder-Mead" method and
optim.method="BFGS" for higher-dimensional index searches.
Data for which bandwidths are to be estimated may be specified
symbolically. A typical description has the form dependent data
~ explanatory data, where dependent data is a univariate
response, and explanatory data is a series of variables
specified by name, separated by the separation character '+'. For
example y1 ~ x1 + x2 specifies that the bandwidth object for
the regression of response y1 and semiparametric regressors
x1 and x2 are to be estimated. See below for further
examples.
When regtype="lp" and degree.select != "manual",
npindexbw can jointly determine the local-polynomial degree for
the index smoother together with its bandwidth coordinate. With
search.engine="cell", the criterion is profiled over the
admissible degree grid using cached coordinate-wise or exhaustive
search. With search.engine="nomad" or
"nomad+powell", the criterion is optimized directly over the
joint degree/bandwidth space using the native crs NOMAD C API.
For this family, the compatibility value "nomad+powell" then
performs one family-native R optim hot start using
optim.method and retains the better of the direct NOMAD and refined
solutions. For the
index-smoother local-polynomial component, this polynomial-adaptive
joint-search route follows Hall and Racine (2015).
Setting nomad=TRUE is a convenience preset for this automatic
LP route, not a generic optimizer alias. For single-index bandwidth
selection it expands any missing values to the equivalent long-form
call
npindexbw(...,
regtype = "lp",
search.engine = "nomad+powell",
degree.select = "coordinate",
bernstein.basis = TRUE,
degree.min = 0L,
degree.max = 10L,
degree.verify = FALSE,
bwtype = "fixed")
Compatible explicit tuning arguments are respected. Incompatible
explicit settings fail fast so the shortcut never silently changes
user-selected semantics.
The character value nomad="auto" applies the same LP
shortcut but leaves search.engine and degree.select
eligible for data-driven resolution when both were not supplied
explicitly: scalar continuous degree searches use the exhaustive
degree-grid route, while higher-dimensional degree searches keep the
compatibility "nomad+powell" route. Explicit search.engine or
degree.select choices are honored.
npindexbw returns a sibandwidth object, with the
following components:
bw |
bandwidth(s), scale factor(s) or nearest neighbours for the
data, |
beta |
coefficients of the model |
fval |
objective function value at minimum |
If bwtype is set to fixed, an object containing a scalar
bandwidth for the function and an estimate of
the parameter vector is returned.
If bwtype is set to generalized_nn or
adaptive_nn, then instead the scalar th nearest neighbor
is returned.
The functions coef, predict,
summary, and plot support
objects of this class.
Local-polynomial index search inherits the numerical-ridging policies
described in npreg; see Seifert and Gasser (2000) there.
npindexbw selects the index direction, bandwidth, and when
requested local-polynomial degree/search metadata for the single-index
model. The continuous-outcome target is typically written
, with normalized for
identification; binary outcomes use the Klein-Spady route.
For book-length derivations, see Li and Racine (2007), Chapter 8 Semiparametric Single Index Models, especially Sections 8.1, 8.2.1, 8.4, 8.5, and 8.10, and Racine (2019), Chapter 8.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Caution: multivariate data-driven bandwidth selection methods are, by
their nature, computationally intensive. Virtually all methods
require dropping the th observation from the data set,
computing an object, repeating this for all observations in the
sample, then averaging each of these leave-one-out estimates for a
given value of the bandwidth vector, and only then repeating
this a large number of times in order to conduct multivariate
numerical minimization/maximization. Furthermore, due to the potential
for local minima/maxima, restarting this procedure a large
number of times may often be necessary. This can be frustrating for
users possessing large datasets. For exploratory purposes, you may
wish to override the default search tolerances, say, setting
optim.reltol=.1 and conduct multistarting (the default is to
restart min(2, ncol(xdat)) times). Once the procedure terminates, you can
restart search with default tolerances using those bandwidths obtained
from the less rigorous search (i.e., set bws=bw on subsequent
calls to this routine where bw is the initial bandwidth
object). A version of this package using the Rmpi wrapper is
under development that allows one to deploy this software in a
clustered computing environment to facilitate computation involving
large datasets.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Hardle, W. and P. Hall and H. Ichimura (1993), “Optimal Smoothing in Single-Index Models,” The Annals of Statistics, 21, 157-178.
Ichimura, H., (1993), “Semiparametric least squares (SLS) and weighted SLS estimation of single-index models,” Journal of Econometrics, 58, 71-120.
Klein, R. W. and R. H. Spady (1993), “An efficient semiparametric estimator for binary response models,” Econometrica, 61, 387-421.
Hall, P. and J.S. Racine (2015), “Infinite Order Cross-Validated Local Polynomial Regression,” Journal of Econometrics, 185, 510-525.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): Generate a simple linear model then # compute coefficients and the bandwidth using Ichimura's nonlinear # least squares approach. set.seed(12345) n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- x1 - x2 + rnorm(n) # Note - this may take a minute or two depending on the speed of your # computer. Note also that the first element of the vector beta is # normalized to one for identification purposes, and that X must contain # at least one continuous variable. bw <- npindexbw(formula=y~x1+x2, method="ichimura") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 1 (INTERFACE=DATA FRAME): Generate a simple linear model then # compute coefficients and the bandwidth using Ichimura's nonlinear # least squares approach. set.seed(12345) n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- x1 - x2 + rnorm(n) X <- cbind(x1, x2) # Note - this may take a minute or two depending on the speed of your # computer. Note also that the first element of the vector beta is # normalized to one for identification purposes, and that X must contain # at least one continuous variable. bw <- npindexbw(xdat=X, ydat=y, method="ichimura") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 2 (INTERFACE=DATA FRAME): Generate a simple binary outcome # model then compute coefficients and the bandwidth using Klein and # Spady's likelihood-based approach. n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) # Note that the first element of the vector beta is normalized to one # for identification purposes, and that X must contain at least one # continuous variable. bw <- npindexbw(formula=y~x1+x2, method="kleinspady") summary(bw) # EXAMPLE 2 (INTERFACE=DATA FRAME): Generate a simple binary outcome # model then compute coefficients and the bandwidth using Klein and # Spady's likelihood-based approach. n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) X <- cbind(x1, x2) # Note that the first element of the vector beta is normalized to one # for identification purposes, and that X must contain at least one # continuous variable. bw <- npindexbw(xdat=X, ydat=y, method="kleinspady") summary(bw) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): Generate a simple linear model then # compute coefficients and the bandwidth using Ichimura's nonlinear # least squares approach. set.seed(12345) n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- x1 - x2 + rnorm(n) # Note - this may take a minute or two depending on the speed of your # computer. Note also that the first element of the vector beta is # normalized to one for identification purposes, and that X must contain # at least one continuous variable. bw <- npindexbw(formula=y~x1+x2, method="ichimura") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 1 (INTERFACE=DATA FRAME): Generate a simple linear model then # compute coefficients and the bandwidth using Ichimura's nonlinear # least squares approach. set.seed(12345) n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- x1 - x2 + rnorm(n) X <- cbind(x1, x2) # Note - this may take a minute or two depending on the speed of your # computer. Note also that the first element of the vector beta is # normalized to one for identification purposes, and that X must contain # at least one continuous variable. bw <- npindexbw(xdat=X, ydat=y, method="ichimura") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 2 (INTERFACE=DATA FRAME): Generate a simple binary outcome # model then compute coefficients and the bandwidth using Klein and # Spady's likelihood-based approach. n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) # Note that the first element of the vector beta is normalized to one # for identification purposes, and that X must contain at least one # continuous variable. bw <- npindexbw(formula=y~x1+x2, method="kleinspady") summary(bw) # EXAMPLE 2 (INTERFACE=DATA FRAME): Generate a simple binary outcome # model then compute coefficients and the bandwidth using Klein and # Spady's likelihood-based approach. n <- 100 x1 <- runif(n, min=-1, max=1) x2 <- runif(n, min=-1, max=1) y <- ifelse(x1 + x2 + rnorm(n) > 0, 1, 0) X <- cbind(x1, x2) # Note that the first element of the vector beta is normalized to one # for identification purposes, and that X must contain at least one # continuous variable. bw <- npindexbw(xdat=X, ydat=y, method="kleinspady") summary(bw) ## End(Not run)
npksum computes kernel sums on evaluation
data, given a set of training data, data to be weighted (optional), and a
bandwidth specification (any bandwidth object).
npksum(...) ## S3 method for class 'formula' npksum(formula, data, newdata, subset, na.action, ...) ## Default S3 method: npksum(bws, txdat = stop("training data 'txdat' missing"), tydat = NULL, exdat = NULL, weights = NULL, bandwidth.divide = FALSE, compute.ocg = FALSE, compute.score = FALSE, kernel.pow = 1.0, leave.one.out = FALSE, operator = names(ALL_OPERATORS), permutation.operator = names(PERMUTATION_OPERATORS), return.kernel.weights = FALSE, ...) ## S3 method for class 'numeric' npksum(bws, txdat = stop("training data 'txdat' missing"), tydat, exdat, weights, bandwidth.divide, compute.ocg, compute.score, kernel.pow, leave.one.out, operator, permutation.operator, return.kernel.weights, ...)npksum(...) ## S3 method for class 'formula' npksum(formula, data, newdata, subset, na.action, ...) ## Default S3 method: npksum(bws, txdat = stop("training data 'txdat' missing"), tydat = NULL, exdat = NULL, weights = NULL, bandwidth.divide = FALSE, compute.ocg = FALSE, compute.score = FALSE, kernel.pow = 1.0, leave.one.out = FALSE, operator = names(ALL_OPERATORS), permutation.operator = names(PERMUTATION_OPERATORS), return.kernel.weights = FALSE, ...) ## S3 method for class 'numeric' npksum(bws, txdat = stop("training data 'txdat' missing"), tydat, exdat, weights, bandwidth.divide, compute.ocg, compute.score, kernel.pow, leave.one.out, operator, permutation.operator, return.kernel.weights, ...)
Core inputs defining the symbolic interface, training data, optional weighted response, and evaluation points for the generalized product kernel sum.
bws |
a bandwidth specification. This can be set as any suitable bandwidth object returned from a bandwidth-generating function, or a numeric vector. |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
exdat |
a |
formula |
a symbolic description of variables on which the sum is to be performed. The details of constructing a formula are described below. |
na.action |
a function which indicates what should happen when the data contain
|
newdata |
an optional data frame in which to look for evaluation data. If
omitted, |
subset |
an optional vector specifying a subset of observations to be used. |
txdat |
a |
tydat |
a numeric vector of data to be weighted. The |
weights |
a |
Controls for bandwidth normalization, kernel powers, leave-one-out evaluation, operator variants, and returned kernel weights.
bandwidth.divide |
a single, non-missing logical specifying whether or not to divide
continuous kernel weights by their bandwidths. Use this with
nearest-neighbor methods. Defaults to |
compute.ocg |
a single, non-missing logical specifying whether or not to return a
separate result for each unordered and ordered dimension, where the
product kernel term for that dimension is evaluated at an appropriate
reference category. This is used primarily in |
compute.score |
a single, non-missing logical specifying whether or not to return the
score (the ‘grad h’ terms) for each dimension in addition to the
kernel sum. Cannot be |
kernel.pow |
a single, finite integer specifying the power to which the kernels
will be raised in the sum. Defaults to |
leave.one.out |
a single, non-missing logical value specifying whether or not to
compute the leave one out sums. The matching contribution is omitted;
nearest-neighbor radii retain the full-sample geometry. This flag alone
is not a literal deleted-sample estimator refit. Will not work if |
operator |
a string specifying whether the |
permutation.operator |
a string which can have a value of |
return.kernel.weights |
a single, non-missing logical specifying whether or not to return the
matrix of generalized product kernel weights. Defaults to
|
Further arguments passed to the default kernel-sum method.
... |
additional arguments supplied to specify the parameters to the
|
Formula variables of class ts, including lagged variables, are
aligned on their common time support before fitting. Other variables
must already have the length of that intersection. Supply explicitly
aligned rows when using native data arguments instead of a formula.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
npksum
exists so that you can create your own kernel objects with
or without a variable to be weighted (default ). With the options
available, you could create new nonparametric tests or even new kernel
estimators. The convolution kernel option would allow you to create,
say, the least squares cross-validation function for kernel density
estimation.
npksum uses highly-optimized C code that strives to minimize
its ‘memory footprint’, while there is low overhead involved
when using repeated calls to this function (see, by way of
illustration, the example below that conducts leave-one-out
cross-validation for a local constant regression estimator via calls
to the R function nlm, and compares this to the
npregbw function).
npksum implements a variety of methods for computing
multivariate kernel sums (-variate) defined over a set of
possibly continuous and/or discrete (unordered, ordered) data. The
approach is based on Li and Racine (2003) who employ
‘generalized product kernels’ that admit a mix of continuous
and discrete data types.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating
the kernel sum at the point . Generalized nearest-neighbor
bandwidths change with the point at which the sum is computed,
. Fixed bandwidths are constant over the support of .
Exact ties can make the literal th continuous nearest-neighbor
radius zero. Such a bandwidth is undefined and is rejected; see
np.kernels for the precise contract and remedies.
npksum computes , where
represents a row vector extracted from . That is, it computes
the kernel weighted sum of the outer product of the rows of
and . In the examples, the uses of such sums are illustrated.
npksum may be invoked either with a formula-like
symbolic
description of variables on which the sum is to be
performed or through a simpler interface whereby data is passed
directly to the function via the txdat and tydat
parameters. Use of these two interfaces is mutually exclusive.
Data contained in the data frame txdat (and also exdat)
may be a mix of continuous (default), unordered discrete (to be
specified in the data frame txdat using the
factor command), and ordered discrete (to be specified
in the data frame txdat using the ordered
command). Data can be entered in an arbitrary order and data types
will be detected automatically by the routine (see np
for details).
Data for which bandwidths are to be estimated may be specified
symbolically. A typical description has the form dependent data
~ explanatory data, where dependent data and explanatory
data are both series of variables specified by name, separated by the
separation character '+'. For example, y1 ~ x1 + x2 specifies
that y1 is to be kernel-weighted by x1 and x2
throughout the sum. See below for further examples.
A variety of kernels may be specified by the user. Kernels implemented
for continuous data types include the second, fourth, sixth, and
eighth order Gaussian, Epanechnikov, and beta associated kernels, and the
uniform kernel. The beta family uses finite-support coordinate-aware routes
described below. Unordered discrete data types use a variation on Aitchison and
Aitken's (1976) kernel, while ordered data types use a variation of
the Wang and van Ryzin (1981) kernel (see np for
details).
For ckertype="beta", npksum uses Chen's second-order
associated PDF kernel as the base contribution on each declared interval.
If , its
per-observation contribution is
The complete density scaling is part of this contribution.
Consequently, a univariate beta density estimate is
npksum(...)$ksum/n, not npksum(...)$ksum/(n*h).
Local-constant regression uses the ordinary ratio of beta-weighted response
and unit sums. Do not set bandwidth.divide=TRUE; that legacy
normalization is intentionally rejected for beta kernels.
For order , the PDF and CDF operators use
. Thus the coefficient
vectors for orders 2, 4, 6, and 8 are , ,
, and . Higher-order PDF and CDF
contributions are signed and are returned without clipping.
For operator="integral", the univariate beta contribution is
This observation-centered analytic CDF is not the integral of the
evaluation-centered PDF contribution with respect to . It is exactly
zero and one at the declared endpoints, is monotone for order 2, and has the
uniform-CDF limit as diverges. In several dimensions,
operator may mix "normal", "integral", and
"convolution" beta factors coordinate by coordinate.
For operator="convolution", the training and evaluation values are
interpreted as the centers of two associated beta weights in the common
observation coordinate. If their shapes are
and , the returned factor is
This symmetric analytic overlap includes its complete
original-scale normalization. Its diagonal is the local beta
roughness. It is neither a translation convolution nor the
target-coordinate integrated-square term used by bounded density
cv.ls; those objectives retain their existing quadrature of the
actual estimator. Beta PDF, CDF, and overlap factors may be mixed across
dimensions.
This beta surface requires continuous txdat,
ckerorder in c(2,4,6,8),
ckerbound="fixed" or "range", finite lower and upper bounds for every
dimension, operator="normal", operator="integral", and/or
operator="convolution", and kernel.pow=1. It supports
multiple continuous dimensions, response and case-weight columns,
leave-one-out sums, and returned kernel weights. All three operators support
bwtype="fixed". The PDF, CDF, and convolution operators additionally support
bwtype="generalized_nn" and bwtype="adaptive_nn"; their
evaluation-specific and observation-specific metric bandwidths are the
distances returned by the existing observation-support nearest-neighbor
implementation, including its tie and extended-NN policy. Generalized
overlap evaluates generalized-NN distances at both centers. Adaptive
overlap keeps adaptive bandwidths attached to training centers; a genuinely
new evaluation center uses the established generalized-NN auxiliary
bandwidth. Fixed and adaptive order-2 CDF factors are monotone in their
target. Generalized-NN CDF factors remain in with exact
endpoints, but their target-varying bandwidth can produce local
nonmonotonicity. Orders 4, 6, and 8 may additionally leave or
be locally nonmonotone in every bandwidth mode; no clipping or monotone
repair is applied. One-coordinate analytic first derivatives and their
continuous-coordinate permutations are available as documented below.
Higher and mixed derivatives, categorical-product, score, OCG, and other
unsupported beta operations fail with an explicit condition. See
np.kernels
for the bandwidth convention, orientation, and references.
The option operator= can be used to ‘mix and match’
operator strings to create a ‘hybrid’ kernel provided they
match the dimension of the data. For example, for a two-dimensional
data frame of numeric datatypes,
operator=c("normal","derivative") will use the normal
(i.e. PDF) kernel for variable one and the derivative of the PDF
kernel for variable two. Please note that applying operators will scale the
results by factors of or where appropriate.
The option permutation.operator= can be used to ‘mix and match’
operator strings to create a ‘hybrid’ kernel, in addition to
the kernel sum with no operators applied, one for each continuous
dimension in the data. For example, for a two-dimensional
data frame of numeric datatypes,
permutation.operator=c("derivative") will return the usual
kernel sum as if operator = c("normal","normal") in the
ksum member, and in the p.ksum member, it will return
kernel sums for operator = c("derivative","normal"), and
operator = c("normal","derivative"). This makes the computation
of gradients much easier.
For ckertype="beta", operator="derivative" is the analytic
first derivative of the associated PDF contribution with respect to its
evaluation coordinate. A direct operator vector may contain one derivative
coordinate, while permutation.operator="derivative" returns one
derivative product per continuous coordinate. Set
bandwidth.divide=FALSE; beta contributions already carry their
original-scale units. Generalized- and adaptive-NN bandwidths are held fixed
during differentiation. Exact matching support endpoints can produce signed
infinite scalar derivatives; see np.kernels for the endpoint
and ratio-cancellation conventions. Signed infinities are returned as
-Inf/Inf, not recoded as missing values; NA_real_ is
reserved for unavailable or indeterminate results.
The option compute.score= can be used to compute the gradients
with respect to in addition to the normal kernel sum. Like
permutations, the additional results are returned in the
p.ksum. This option does not work in conjunction with
permutation.operator.
For categorical variables with kernel.pow=1, the score differentiates
the requested operator with respect to its categorical bandwidth: ordinary
weights for "normal", overlap weights for "convolution",
and ordered cumulative weights for "integral". An unordered
"integral" retains its ordinary-weight convention. Convolution
scores include both factors and, where applicable, both normalizers.
The option compute.ocg= works much like permutation.operator,
but for discrete variables. The kernel is evaluated at a reference
category in each dimension: for ordered data, the next lowest category
is selected, except in the case of the lowest category, where the
second lowest category is selected; for unordered data, the first
category is selected. These additional data are returned in the
p.ksum member. This option can be set simultaneously with
permutation.operator.
Ordered evaluation values used with compute.ocg=TRUE must belong
to the bandwidth object's retained category table, because this operation
requires an adjacent reference category. Other ordered kernel evaluations
retain their usual numeric extrapolation behavior.
When a permutation, score, or OCG operation selects only a subset of
variables, the corresponding blocks in p.ksum and, when requested
internally, derivative kernel weights are packed without empty coordinates
and follow the original data-column order among the selected variables.
The option return.kernel.weights=TRUE returns a matrix of
dimension ‘number of training observations’ by ‘number
of evaluation observations’ containing generalized product kernel weights,
not response- or observation-weighted sums. The bandwidth.divide
flag controls normalization of ksum, not this raw kw export.
For purely continuous data with fixed physical bandwidths
h and unbounded ordinary location kernels,
colMeans(foo$kw)/prod(h) gives a density estimate
when every operator is "normal". With every operator
"integral", the corresponding distribution estimate is
colMeans(foo$kw), without division by the bandwidth product.
Mixed operators require their coordinate-specific normalizations.
Nearest-neighbor and associated beta kernels must use their own
bandwidth/normalization conventions; one global bandwidth product is
not a general reconstruction rule.
npksum returns a npkernelsum object
with the following components:
eval |
the evaluation points |
ksum |
the sum at the evaluation points |
kw |
the kernel weights (when |
p.ksum |
packed permutation, score, or OCG sums, when requested |
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “ Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2003), “Nonparametric estimation of distributions with categorical and continuous data,” Journal of Multivariate Analysis, 86, 266-292.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Scott, D.W. (1992), Multivariate Density Estimation. Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
Chen, S.X. (1999), “Beta kernel estimators for density functions,” Computational Statistics & Data Analysis, 31(2), 131-145. doi:10.1016/S0167-9473(99)00010-9.
## Not run: # EXAMPLE 1: For this example, we generate 100,000 observations from a # N(0, 1) distribution, then evaluate the kernel density on a grid of 50 # equally spaced points using the npksum() function, then compare # results with the (identical) npudens() function output n <- 100000 x <- rnorm(n) x.eval <- seq(-4, 4, length=50) # Compute the bandwidth with the normal-reference rule-of-thumb bw <- npudensbw(dat=x, bwmethod="normal-reference") # Compute the univariate kernel density estimate using the 100,000 # training data points evaluated on the 50 evaluation data points, # i.e., 1/nh times the sum of the kernel function evaluated at each of # the 50 points den.ksum <- npksum(txdat=x, exdat=x.eval, bws=bw$bw)$ksum/(n*bw$bw[1]) # Note that, alternatively (easier perhaps), you could use the # bandwidth.divide=TRUE argument and drop the *bw$bw[1] term in the # denominator, as in # npksum(txdat=x, exdat=x.eval, bws=bw$bw, bandwidth.divide=TRUE)$ksum/n # Compute the density directly with the npudens() function... den <- fitted(npudens(tdat=x, edat=x.eval, bws=bw$bw)) # Plot the true DGP, the npksum()/(nh) estimate and (identical) # npudens() estimate if (interactive()) plot(x.eval, dnorm(x.eval), xlab="X", ylab="Density", type="l") points(x.eval, den.ksum, col="blue") points(x.eval, den, col="red", cex=0.2) legend(1, .4, c("DGP", "npksum()", "npudens()"), col=c("black", "blue", "red"), lty=c(1, 1, 1)) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 2: For this example, we first obtain residuals from a # parametric regression model, then compute a vector of leave-one-out # kernel weighted sums of squared residuals where the kernel function is # raised to the power 2. Note that this returns a vector of kernel # weighted sums, one for each element of the error vector. Note also # that you can specify the bandwidth type, kernel function, kernel order # etc. data("cps71") with(cps71, { error <- residuals(lm(logwage~age+I(age^2))) bw <- npreg(error~age) ksum <- npksum(txdat=age, tydat=error^2, bws=bw$bw, leave.one.out=TRUE, kernel.pow=2) ksum # Obviously, if we wanted the sum of these weighted kernel sums then, # trivially, sum(ksum$ksum) }) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Note that weighted leave-one-out sums of squared residuals are used to # construct consistent model specification tests. In fact, the # npcmstest() routine in this package is constructed purely from calls # to npksum(). You can type npcmstest to see the npcmstest() # code and also examine some examples of the many uses of # npksum(). # EXAMPLE 3: For this example, we conduct local-constant (i.e., # Nadaraya-Watson) kernel regression. We shall use cross-validated # bandwidths using npregbw() by way of example. Note we extract # the kernel sum from npksum() via the `$ksum' argument in both # the numerator and denominator. data("cps71") with(cps71, { bw <- npregbw(xdat=age, ydat=logwage) fit.lc <- npksum(txdat=age, tydat=logwage, bws=bw$bw)$ksum/ npksum(txdat=age, bws=bw$bw)$ksum if (interactive()) plot(age, logwage, xlab="Age", ylab="log(wage)") lines(age, fit.lc) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you wished to compute the kernel sum for a set of evaluation points, # you first generate the set of points then feed this to npksum, # e.g., for the set (20, 30, ..., 60) we would use age.seq <- seq(20, 60, 10) fit.lc <- npksum(txdat=age, exdat=age.seq, tydat=logwage, bws=bw$bw)$ksum/ npksum(txdat=age, exdat=age.seq, bws=bw$bw)$ksum # Note that now fit.lc contains the 5 values of the local constant # estimator corresponding to age.seq... fit.lc }) # EXAMPLE 4: For this example, we conduct least-squares cross-validation # for the fixed-bandwidth local-constant regression estimator. We first write an R # function `ss' that computes the leave-one-out sum of squares using the # npksum() function, and then feed this function, along with # random starting values for the bandwidth vector, to the nlm() routine # in R (nlm = Non-Linear Minimization). Finally, we compare results with # the function npregbw() that is written solely in C and calls # a tightly coupled C-level search routine. Note that one could make # repeated calls to nlm() using different starting values for h (highly # recommended in general). # Increase the number of digits printed out by default in R and avoid # using scientific notation for this example (we wish to compare # objective function minima), then restore the user's options on exit. old <- options(scipen=100, digits=12) on.exit(options(old), add = TRUE) # Generate 100 observations from a simple DGP where one explanatory # variable is irrelevant. n <- 100 x1 <- runif(n) x2 <- rnorm(n) x3 <- runif(n) txdat <- data.frame(x1, x2, x3) # Note - x3 is irrelevant tydat <- x1 + sin(x2) + rnorm(n) # Write an R function that returns the average leave-one-out sum of # squared residuals for the local constant estimator based upon # npksum(). This function accepts one argument and presumes that # txdat and tydat have been defined already. ss <- function(h) { # Test for valid (non-negative) bandwidths - return infinite penalty # when this occurs if(min(h)<=0) { return(.Machine$double.xmax) } else { mean <- npksum(txdat, tydat, leave.one.out=TRUE, bwtype="fixed", bandwidth.divide=TRUE, bws=h)$ksum/ npksum(txdat, leave.one.out=TRUE, bwtype="fixed", bandwidth.divide=TRUE, bws=h)$ksum return(sum((tydat-mean)^2)/length(tydat)) } } # Now pass this function to R's nlm() routine along with random starting # values and place results in `nlm.return'. nlm.return <- nlm(ss, runif(length(txdat))) bw <- npregbw(xdat=txdat, ydat=tydat, bwtype="fixed") # Bandwidths from nlm() nlm.return$estimate # Bandwidths from npregbw() bw$bw # Function value (minimum) from nlm() nlm.return$minimum # Function value (minimum) from npregbw() bw$fval # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 5: For this example, we use npksum() to plot the kernel # function itself. Our `training data' is the singleton, 0, and our # evaluation data a grid in [-4,4], while we use a bandwidth of 1. By # way of example we plot a sixth order Gaussian kernel (note that this # kernel function can assume negative values) x <- 0 x.eval <- seq(-4,4,length=500) kernel <- npksum(txdat=x,exdat=x.eval,bws=1, bandwidth.divide=TRUE, ckertype="gaussian", ckerorder=6)$ksum plot(x.eval,kernel,type="l",xlab="X",ylab="Kernel Function") abline(0,0) # EXAMPLE 6: The beta associated kernel for bounded data. Its complete # original-scale normalization is already included, so divide the sum by n, # not by n*h. The same weights can be used directly in a local-constant # numerator/denominator ratio. x <- c(0, 0.01, 0.04, 0.15, 0.4, 0.75, 1) x.eval <- seq(0, 1, length.out=101) h <- 0.12 beta.args <- list(txdat=data.frame(x=x), exdat=data.frame(x=x.eval), bws=h, ckertype="beta", ckerorder=2, ckerbound="fixed", ckerlb=0, ckerub=1) beta.density <- do.call(npksum, beta.args)$ksum/length(x) y <- sqrt(x) beta.mean <- do.call(npksum, c(beta.args, list(tydat=y)))$ksum/ do.call(npksum, beta.args)$ksum beta.cdf <- do.call(npksum, c(beta.args, list(operator="integral")))$ksum/length(x) beta.overlap <- do.call(npksum, c(beta.args, list(operator="convolution")))$ksum ## End(Not run)## Not run: # EXAMPLE 1: For this example, we generate 100,000 observations from a # N(0, 1) distribution, then evaluate the kernel density on a grid of 50 # equally spaced points using the npksum() function, then compare # results with the (identical) npudens() function output n <- 100000 x <- rnorm(n) x.eval <- seq(-4, 4, length=50) # Compute the bandwidth with the normal-reference rule-of-thumb bw <- npudensbw(dat=x, bwmethod="normal-reference") # Compute the univariate kernel density estimate using the 100,000 # training data points evaluated on the 50 evaluation data points, # i.e., 1/nh times the sum of the kernel function evaluated at each of # the 50 points den.ksum <- npksum(txdat=x, exdat=x.eval, bws=bw$bw)$ksum/(n*bw$bw[1]) # Note that, alternatively (easier perhaps), you could use the # bandwidth.divide=TRUE argument and drop the *bw$bw[1] term in the # denominator, as in # npksum(txdat=x, exdat=x.eval, bws=bw$bw, bandwidth.divide=TRUE)$ksum/n # Compute the density directly with the npudens() function... den <- fitted(npudens(tdat=x, edat=x.eval, bws=bw$bw)) # Plot the true DGP, the npksum()/(nh) estimate and (identical) # npudens() estimate if (interactive()) plot(x.eval, dnorm(x.eval), xlab="X", ylab="Density", type="l") points(x.eval, den.ksum, col="blue") points(x.eval, den, col="red", cex=0.2) legend(1, .4, c("DGP", "npksum()", "npudens()"), col=c("black", "blue", "red"), lty=c(1, 1, 1)) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 2: For this example, we first obtain residuals from a # parametric regression model, then compute a vector of leave-one-out # kernel weighted sums of squared residuals where the kernel function is # raised to the power 2. Note that this returns a vector of kernel # weighted sums, one for each element of the error vector. Note also # that you can specify the bandwidth type, kernel function, kernel order # etc. data("cps71") with(cps71, { error <- residuals(lm(logwage~age+I(age^2))) bw <- npreg(error~age) ksum <- npksum(txdat=age, tydat=error^2, bws=bw$bw, leave.one.out=TRUE, kernel.pow=2) ksum # Obviously, if we wanted the sum of these weighted kernel sums then, # trivially, sum(ksum$ksum) }) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Note that weighted leave-one-out sums of squared residuals are used to # construct consistent model specification tests. In fact, the # npcmstest() routine in this package is constructed purely from calls # to npksum(). You can type npcmstest to see the npcmstest() # code and also examine some examples of the many uses of # npksum(). # EXAMPLE 3: For this example, we conduct local-constant (i.e., # Nadaraya-Watson) kernel regression. We shall use cross-validated # bandwidths using npregbw() by way of example. Note we extract # the kernel sum from npksum() via the `$ksum' argument in both # the numerator and denominator. data("cps71") with(cps71, { bw <- npregbw(xdat=age, ydat=logwage) fit.lc <- npksum(txdat=age, tydat=logwage, bws=bw$bw)$ksum/ npksum(txdat=age, bws=bw$bw)$ksum if (interactive()) plot(age, logwage, xlab="Age", ylab="log(wage)") lines(age, fit.lc) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you wished to compute the kernel sum for a set of evaluation points, # you first generate the set of points then feed this to npksum, # e.g., for the set (20, 30, ..., 60) we would use age.seq <- seq(20, 60, 10) fit.lc <- npksum(txdat=age, exdat=age.seq, tydat=logwage, bws=bw$bw)$ksum/ npksum(txdat=age, exdat=age.seq, bws=bw$bw)$ksum # Note that now fit.lc contains the 5 values of the local constant # estimator corresponding to age.seq... fit.lc }) # EXAMPLE 4: For this example, we conduct least-squares cross-validation # for the fixed-bandwidth local-constant regression estimator. We first write an R # function `ss' that computes the leave-one-out sum of squares using the # npksum() function, and then feed this function, along with # random starting values for the bandwidth vector, to the nlm() routine # in R (nlm = Non-Linear Minimization). Finally, we compare results with # the function npregbw() that is written solely in C and calls # a tightly coupled C-level search routine. Note that one could make # repeated calls to nlm() using different starting values for h (highly # recommended in general). # Increase the number of digits printed out by default in R and avoid # using scientific notation for this example (we wish to compare # objective function minima), then restore the user's options on exit. old <- options(scipen=100, digits=12) on.exit(options(old), add = TRUE) # Generate 100 observations from a simple DGP where one explanatory # variable is irrelevant. n <- 100 x1 <- runif(n) x2 <- rnorm(n) x3 <- runif(n) txdat <- data.frame(x1, x2, x3) # Note - x3 is irrelevant tydat <- x1 + sin(x2) + rnorm(n) # Write an R function that returns the average leave-one-out sum of # squared residuals for the local constant estimator based upon # npksum(). This function accepts one argument and presumes that # txdat and tydat have been defined already. ss <- function(h) { # Test for valid (non-negative) bandwidths - return infinite penalty # when this occurs if(min(h)<=0) { return(.Machine$double.xmax) } else { mean <- npksum(txdat, tydat, leave.one.out=TRUE, bwtype="fixed", bandwidth.divide=TRUE, bws=h)$ksum/ npksum(txdat, leave.one.out=TRUE, bwtype="fixed", bandwidth.divide=TRUE, bws=h)$ksum return(sum((tydat-mean)^2)/length(tydat)) } } # Now pass this function to R's nlm() routine along with random starting # values and place results in `nlm.return'. nlm.return <- nlm(ss, runif(length(txdat))) bw <- npregbw(xdat=txdat, ydat=tydat, bwtype="fixed") # Bandwidths from nlm() nlm.return$estimate # Bandwidths from npregbw() bw$bw # Function value (minimum) from nlm() nlm.return$minimum # Function value (minimum) from npregbw() bw$fval # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 5: For this example, we use npksum() to plot the kernel # function itself. Our `training data' is the singleton, 0, and our # evaluation data a grid in [-4,4], while we use a bandwidth of 1. By # way of example we plot a sixth order Gaussian kernel (note that this # kernel function can assume negative values) x <- 0 x.eval <- seq(-4,4,length=500) kernel <- npksum(txdat=x,exdat=x.eval,bws=1, bandwidth.divide=TRUE, ckertype="gaussian", ckerorder=6)$ksum plot(x.eval,kernel,type="l",xlab="X",ylab="Kernel Function") abline(0,0) # EXAMPLE 6: The beta associated kernel for bounded data. Its complete # original-scale normalization is already included, so divide the sum by n, # not by n*h. The same weights can be used directly in a local-constant # numerator/denominator ratio. x <- c(0, 0.01, 0.04, 0.15, 0.4, 0.75, 1) x.eval <- seq(0, 1, length.out=101) h <- 0.12 beta.args <- list(txdat=data.frame(x=x), exdat=data.frame(x=x.eval), bws=h, ckertype="beta", ckerorder=2, ckerbound="fixed", ckerlb=0, ckerub=1) beta.density <- do.call(npksum, beta.args)$ksum/length(x) y <- sqrt(x) beta.mean <- do.call(npksum, c(beta.args, list(tydat=y)))$ksum/ do.call(npksum, beta.args)$ksum beta.cdf <- do.call(npksum, c(beta.args, list(operator="integral")))$ksum/length(x) beta.overlap <- do.call(npksum, c(beta.args, list(operator="convolution")))$ksum ## End(Not run)
nplsqreg computes a location-scale kernel estimate of the
conditional quantile function for a one dimensional dependent variable
and mixed continuous, unordered factor, and ordered factor explanatory
data. Unlike npqreg, which obtains conditional quantiles
by inverting an estimated conditional distribution, nplsqreg
estimates the requested conditional quantile surface directly using a
locally weighted quantile-kernel construction.
nplsqreg(bws, ...) ## S3 method for class 'lsqregression' predict(object, se.fit = FALSE, ..., tau = NULL) ## S3 method for class 'formula' nplsqreg(bws, data = NULL, newdata = NULL, tau = 0.5, gradients = FALSE, residuals = FALSE, subset, na.action, gradient.order = 1L, se = FALSE, ...) ## S3 method for class 'lsqregressionbandwidth' nplsqreg(bws, txdat = NULL, tydat = NULL, tau = bws$tau, se = FALSE, ...) ## Default S3 method: nplsqreg(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), tau = 0.5, exdat, gradients = FALSE, residuals = FALSE, gradient.order = 1L, se = FALSE, ...)nplsqreg(bws, ...) ## S3 method for class 'lsqregression' predict(object, se.fit = FALSE, ..., tau = NULL) ## S3 method for class 'formula' nplsqreg(bws, data = NULL, newdata = NULL, tau = 0.5, gradients = FALSE, residuals = FALSE, subset, na.action, gradient.order = 1L, se = FALSE, ...) ## S3 method for class 'lsqregressionbandwidth' nplsqreg(bws, txdat = NULL, tydat = NULL, tau = bws$tau, se = FALSE, ...) ## Default S3 method: nplsqreg(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), tau = 0.5, exdat, gradients = FALSE, residuals = FALSE, gradient.order = 1L, se = FALSE, ...)
object |
a fitted |
se.fit |
logical; whether prediction standard errors are returned.
Defaults to |
These arguments identify the bandwidth specification, formula/data interface, and training data.
bws |
a formula, an |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment containing the variables
in the model. If not found in |
subset |
an optional vector specifying a subset of observations to be used by
the formula method. When using a formula-based regression bandwidth
object as a starting bandwidth, a row-changing subset requires explicit
|
na.action |
a function specifying the action to take when missing values are found by the formula method. |
txdat |
a |
tydat |
a one dimensional numeric vector of dependent data. Defaults to the
training response stored in |
These arguments control where the quantile regression is evaluated and which fitted quantities are returned.
newdata |
an optional data frame in which to look for evaluation covariates for formula fits. If omitted, the training data are used. |
exdat |
a |
gradients |
a logical value indicating whether gradients and categorical effects
of the conditional quantile with respect to the conditioning variables
should be computed and returned. Defaults to |
se |
a logical value indicating whether asymptotic standard errors should be
computed and retained. Defaults to |
gradient.order |
for a final |
residuals |
a logical value indicating whether residuals should be returned for
training-data fits. Defaults to |
These arguments control the requested quantile probability and the bandwidth selection, prediction, or plotting route.
tau |
a numeric scalar or vector specifying the quantile probability or
probabilities |
... |
additional arguments supplied to |
The tau prediction argument must be named. Selecting one stored
quantile returns the ordinary scalar prediction vector (or the scalar
prediction list when se.fit = TRUE). Selecting several returns
prediction and standard-error matrices with columns in the requested order,
preserving the stored quantile labels and aligning residual.scale.
Omitting tau, or supplying NULL, preserves the fitted
object's original scalar or matrix output shape.
Prediction with se.fit = TRUE reports known training mean squared
error in residual.scale, retaining MSE units, or NA when
training provenance is unavailable. Evaluation outcomes do not replace this
training score. No additional fit is performed to recover it.
This score concerns the regression on the transformed quantile response.
For vector tau, residual.scale is a named vector with one
training MSE for each requested quantile, matching the prediction columns.
A stored lsqregressionbandwidth object retains its training
sample, pilots and transformed response. Replacement data, a
row-changing subset, or a new na.action is an error:
use nplsqregbw() to construct bandwidth state on the new sample.
Use newdata or exdat for prediction instead.
Formula fits retain trained terms and prediction expressions, so
data-dependent transformations are reused for newdata rather than
recalculated on each prediction grid. The same terms are retained by the
scalar children of vector-tau fits. Native exdat already
contains model coordinates and is not transformed again. An unnamed
evaluation argument in ... follows newdata for formula
predictions and exdat for native predictions; name se.fit
explicitly when using this positional form. Older saved
objects without trained terms retain their formula-based fallback.
Omitted training rows are restored as NA in fitted values and
residuals, including fits obtained from a retained bandwidth object and
multiple quantile probabilities. Prediction restores omitted evaluation
rows in both estimates and standard errors. Explicit training inputs own
their row positions; a complete-case replacement is not padded using an
older bandwidth object's omissions.
For native (non-formula) objects, named newdata columns are matched
to the retained variable names and reordered as needed. Extra columns are
ignored; missing, duplicate or ambiguous names are errors. An unnamed
matrix or vector remains positional for a single evaluation role.
Explicit native evaluation arguments retain their positional contract and
take precedence over newdata.
Formula variables of class ts, including lagged variables, are
aligned on their common time support before fitting. Other variables
must already have the length of that intersection. Supply explicitly
aligned rows when using native data arguments instead of a formula.
The estimator follows the locally weighted quantile-kernel approach of
Racine and Li (2017). Given a conditional scale pilot
, define
where and is the standard normal
quantile function. For a requested quantile probability
, nplsqregbw selects the bandwidths and
by leave-one-out check-loss cross-validation. With
the selected bandwidths and , nplsqreg then
fits a kernel regression of on using the
ordinary mixed-data machinery in npreg. The fitted mean
of the transformed response is the estimated conditional quantile.
The scale pilot is interpreted as a conditional standard deviation. The
default pilot estimates the conditional mean, smooths squared residuals,
floors the fitted variance before taking square roots, and then uses the
resulting positive scale vector in the quantile-kernel transformation.
The local-linear residual-variance pilot follows the idea of Fan and
Yao (1998); regtype.pilot can be used to select the pilot
regression type independently of the final quantile fit.
If tau has length greater than one, tau.search="full"
performs a separate bandwidth/ search for each
quantile while sharing the same pilot scale. The explicit
tau.search="refined" route fits the central quantile first and
warm-starts the remaining quantiles, recording the search order and
warm-start provenance in the returned object. The conservative default
is tau.search="full".
Gradients and categorical effects are those returned by the final
npreg fit on the transformed response. Thus ordered-factor
effects are finite-difference contrasts and unordered-factor effects
follow the corresponding mixed-data regression semantics. For a
local-polynomial fit, gradient.order is applied coordinate by
coordinate to continuous predictors. Availability follows npreg:
Apart from the established all-degree-zero first-derivative compatibility
route, components whose order exceeds their fitted polynomial degree are returned
as NA with a warning whenever another continuous derivative or
categorical first-difference effect is available; plots retain those
components as empty panels. A request with no available component is
rejected. No mixed partials, Hessians, derivative tensors, or multiple
derivative orders are stored. With vector tau, the
existing evaluation-by-coordinate-by-tau array layout is retained.
The gradients method extracts exactly the stored order and
rejects any different requested order; it does not recompute derivatives
after fitting.
A scalar quantile can be displayed as a surface by explicitly supplying
perspective=TRUE when there are two continuous or numeric-labelled
ordered conditioning variables. Omitting perspective, or supplying
perspective=FALSE, retains the usual slice layout. Vector quantiles
and gradient plots also retain their slice layout. Surface uncertainty is
calibrated over the complete displayed grid for that one tau.
Both the base renderer and renderer="rgl", view="fixed" support
level surfaces and their interval meshes. Returned evaluation rows retain
the trained predictor names and ordered-factor support; numeric axis
coordinates are used only for drawing. The data overlay can be disabled
with data.overlay=FALSE.
Asymptotic plot(..., band="simultaneous") and band="all"
use the accepted local regression response maps for each fitted
transformed-response curve. Level, continuous-derivative and paired
categorical-effect factors retain common observation columns, the selected
local-constant or local-polynomial specification, and the actual native
moment/ridge convention. Residual normalization uses the training fit map;
reconstruction checks reject numerically unidentifiable maps instead of
changing the fitted estimator. The fixed-regression fitting and bandwidth
selection algorithms are unchanged.
Calibration is over the retained finite grid within one panel and one
tau; it is not joint over taus or panels. gaussian.draws
controls the Gaussian maximum simulation, and random.seed preserves
reproducibility without changing the caller's RNG state. These are
variability bands under the frozen transformation convention below; they
do not add uncertainty from transformation selection or remove smoothing
bias, and do not cover points between the declared grid. Coverage requires
a valid joint Gaussian approximation and consistent local marginal scales;
arbitrary growing or data-dependent grids do not carry a uniform-coverage
guarantee. Unavailable marginal errors, unidentified influences or resource
limits produce a specific unavailable joint-band notice.
Standard errors are the asymptotic standard errors from that final
transformed-response regression, conditional on the selected
bandwidths, pilot scale, and . They inherit the
residual normalization described under Standard Errors in
npreg (Ruppert et al., 1997), applied to the transformed
response. This does not add uncertainty from estimating the pilot scale
or transformation. Local-polynomial fits inherit the numerical-ridging
policy documented there. For vector
tau, quantiles are fitted separately, so estimated quantile
curves are not monotonized and may cross in finite samples. Separate
fits on the same observations do not imply zero cross-quantile
sampling covariance.
nplsqreg returns an object of class lsqregression. The
generic functions fitted, quantile,
se, predict, residuals, and
gradients extract estimated conditional quantiles,
asymptotic standard errors from the transformed-response regression,
predictions, residuals when requested, and gradients or categorical
effects. The functions summary,
print, and plot support objects of this type.
Local-polynomial fit objects retain the compact continuous-coordinate
derivative order in $gradient.order.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When converting a formula-based rbandwidth without replacement
data, an explicitly supplied scale vector must follow the
retained complete training sample in its stored order. With replacement
data, scale follows the formula's ordinary subset and missing-data
handling.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Fan, J. and Q. Yao (1998), “Efficient Estimation of Conditional Variance Functions in Stochastic Regression,” Biometrika, 85, 645-660. doi:10.1093/biomet/85.3.645
Racine, J.S. and K. Li (2017), “Nonparametric conditional quantile estimation: A locally weighted quantile kernel approach,” Journal of Econometrics, 201, 72-94. doi:10.1016/j.jeconom.2017.06.020
Racine, J.S. and I. Van Keilegom (2020), “A smooth nonparametric, multivariate, mixed-data location-scale test,” Journal of Business & Economic Statistics, 38, 784-795. doi:10.1080/07350015.2019.1574227
nplsqregbw, npreg, npqreg,
np.kernels, np.options, plot.np
## Not run: data("Italy") model.q <- nplsqreg(gdp ~ ordered(year), data = Italy, tau = c(0.25, 0.50, 0.75)) plot(model.q) model.med <- nplsqreg(gdp ~ ordered(year), data = Italy, tau = 0.50) model.q2 <- nplsqreg(bws = model.med$bws, tau = 0.50) plot(model.med, gradient = TRUE) ## End(Not run)## Not run: data("Italy") model.q <- nplsqreg(gdp ~ ordered(year), data = Italy, tau = c(0.25, 0.50, 0.75)) plot(model.q) model.med <- nplsqreg(gdp ~ ordered(year), data = Italy, tau = 0.50) model.q2 <- nplsqreg(bws = model.med$bws, tau = 0.50) plot(model.med, gradient = TRUE) ## End(Not run)
nplsqregbw selects bandwidths and the scalar location-scale shift
parameter delta for nplsqreg by minimizing
leave-one-out check loss.
nplsqregbw(bws, ...) ## S3 method for class 'formula' nplsqregbw(bws, data = NULL, tau = 0.5, subset, na.action, ...) ## S3 method for class 'lsqregressionbandwidth' nplsqregbw(bws, tau = bws$tau, ...) ## Default S3 method: nplsqregbw(bws, xdat = stop("invoked without data 'xdat'"), ydat = stop("invoked without data 'ydat'"), tau = 0.5, tau.search = c("full", "refined"), delta = NULL, scale = NULL, regtype = c("lc", "ll", "lp"), regtype.pilot = c("auto", "ll", "lc", "lp"), nomad = FALSE, nomad.pilot = FALSE, pilot.args = list(), bandwidth.compute = TRUE, delta.bounds = c(1e-4, 1 - 1e-4), optim.control = list(maxit = 50L), ..., nomad.opts = list())nplsqregbw(bws, ...) ## S3 method for class 'formula' nplsqregbw(bws, data = NULL, tau = 0.5, subset, na.action, ...) ## S3 method for class 'lsqregressionbandwidth' nplsqregbw(bws, tau = bws$tau, ...) ## Default S3 method: nplsqregbw(bws, xdat = stop("invoked without data 'xdat'"), ydat = stop("invoked without data 'ydat'"), tau = 0.5, tau.search = c("full", "refined"), delta = NULL, scale = NULL, regtype = c("lc", "ll", "lp"), regtype.pilot = c("auto", "ll", "lc", "lp"), nomad = FALSE, nomad.pilot = FALSE, pilot.args = list(), bandwidth.compute = TRUE, delta.bounds = c(1e-4, 1 - 1e-4), optim.control = list(maxit = 50L), ..., nomad.opts = list())
These arguments identify the bandwidth specification, formula/data interface, and training data.
bws |
a formula, an |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment containing the variables
in the model. If not found in |
subset |
an optional vector specifying a subset of observations to be used by the formula method. |
na.action |
a function specifying the action to take when missing values are found by the formula method. |
xdat |
a |
ydat |
a one dimensional numeric vector of dependent data. |
These arguments identify the quantile probabilities and how vector-tau
fits are orchestrated.
tau |
a numeric scalar or vector specifying the quantile probability or
probabilities |
tau.search |
either |
These arguments control or supply the conditional standard deviation used in the location-scale transformation.
scale |
an optional strictly positive scale vector interpreted as the
conditional standard deviation at the training observations. If
omitted, a pilot scale is computed automatically.
In formula calls, a full-length vector follows the formula's time
alignment, |
regtype.pilot |
regression type used for the pilot mean and residual-variance
smooths. The default |
nomad.pilot |
logical value indicating whether the pilot regressions should use the
automatic NOMAD local-polynomial route when compatible with
|
pilot.args |
optional named list of additional arguments supplied to the pilot
|
These arguments control the main check-loss bandwidth and
delta optimization.
regtype |
regression type for the main transformed-response fit and check-loss
bandwidth search. This is independent of |
delta |
optional starting value for the shift parameter. If omitted, the
first start uses |
delta.bounds |
two numeric values giving the lower and upper bounds for
|
nomad |
logical value or the character string |
nomad.opts |
optional named list of native NOMAD parameters forwarded to the
crs NOMAD C API for NOMAD-backed bandwidth searches.
|
bandwidth.compute |
logical value indicating whether automatic bandwidth selection should
be performed. Defaults to |
optim.control |
a list of controls passed to the Powell optimizer used for fixed degree searches and NOMAD hot-start refinement. |
... |
additional bandwidth, kernel, local-polynomial, and search controls
forwarded to the package bandwidth machinery. Common examples include
|
Regression searches and pilot fits inherit numerical ridging from
npregbw and npreg.
For a requested quantile probability ,
nplsqregbw chooses bandwidths and delta for the
transformed response
by minimizing the leave-one-out check loss. The selected bandwidths
are then used by nplsqreg for the final mixed-data
npreg fit of the transformed response.
When the response fitted inside a leave-one-out fold differs from the response entering the requested check loss, the deleted fitted value is reconstructed with the fitted response while the residual is formed with the requested loss response. Invalid search guidance is the exact constrained constant-quantile check-loss null. A final NOMAD or Powell payload is accepted only when replay of its selected point returns a raw finite objective.
The default pilot scale is a residual scale: first npreg
estimates the conditional mean, then npreg smooths
squared residuals using the same bandwidth object, and the square root
of the floored fitted variance is used as the scale. The local-linear
pilot option follows Fan and Yao (1998). A user-supplied scale
must be strictly positive and is interpreted as a conditional standard
deviation, not a variance.
When nomad=TRUE, the search can include the continuous
local-polynomial degree vector in addition to bandwidths and
delta. The search.engine="nomad+powell" route uses NOMAD
for degree search and Powell for hot-start refinement at the selected
degree. When nomad="auto", a one-dimensional smoothing problem
instead evaluates the complete requested degree lattice and jointly
optimizes bandwidth and delta at every degree; higher-dimensional
problems use the NOMAD/Powell policy. nomad.pilot remains an
independent logical control and is not enabled by primary AUTO.
nplsqregbw returns an object of class
lsqregressionbandwidth. For vector tau, the object stores
the per-tau bandwidth objects, selected delta values,
objectives, fit order, warm-start provenance, and shared pilot scale.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Fan, J. and Q. Yao (1998), “Efficient Estimation of Conditional Variance Functions in Stochastic Regression,” Biometrika, 85, 645-660. doi:10.1093/biomet/85.3.645
Racine, J.S. and K. Li (2017), “Nonparametric conditional quantile estimation: A locally weighted quantile kernel approach,” Journal of Econometrics, 201, 72-94. doi:10.1016/j.jeconom.2017.06.020
Racine, J.S. and I. Van Keilegom (2020), “A smooth nonparametric, multivariate, mixed-data location-scale test,” Journal of Business & Economic Statistics, 38, 784-795. doi:10.1080/07350015.2019.1574227
nplsqreg, npregbw, npreg,
np.kernels, np.options
npplreg computes a partially linear kernel regression estimate
of a one (1) dimensional dependent variable on -variate
explanatory data, using the model given a set of estimation
points, training points (consisting of explanatory data and dependent
data), and a bandwidth specification, which can be a rbandwidth
object, or a bandwidth vector, bandwidth type and kernel type.
npplreg(bws, ...) ## S3 method for class 'formula' npplreg(bws, data = NULL, newdata = NULL, y.eval = FALSE, ..., se = FALSE) ## Default S3 method: npplreg(bws, txdat, tydat, tzdat, nomad = FALSE, ..., se = FALSE) ## S3 method for class 'plbandwidth' npplreg(bws, txdat = stop("training data txdat missing"), tydat = stop("training data tydat missing"), tzdat = stop("training data tzdat missing"), exdat, eydat, ezdat, residuals = FALSE, ..., se = FALSE)npplreg(bws, ...) ## S3 method for class 'formula' npplreg(bws, data = NULL, newdata = NULL, y.eval = FALSE, ..., se = FALSE) ## Default S3 method: npplreg(bws, txdat, tydat, tzdat, nomad = FALSE, ..., se = FALSE) ## S3 method for class 'plbandwidth' npplreg(bws, txdat = stop("training data txdat missing"), tydat = stop("training data tydat missing"), tzdat = stop("training data tzdat missing"), exdat, eydat, ezdat, residuals = FALSE, ..., se = FALSE)
These arguments identify the bandwidth specification, formula/data interface, and partially linear training data.
bws |
a bandwidth specification. This can be set as a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
txdat |
a |
tydat |
a one (1) dimensional numeric or integer vector of dependent data, each
element |
tzdat |
a |
This argument controls the recommended automatic local-polynomial NOMAD route, which jointly selects continuous polynomial degree and bandwidths when these are computed inside npplreg.
nomad |
logical shortcut passed through to |
These arguments control where the partially linear regression is evaluated and which fitted quantities are returned.
exdat |
a |
eydat |
a one (1) dimensional numeric or integer vector of the true values
of the dependent variable. Optional, and used only to calculate the
true errors. By default,
evaluation takes place on the data provided by |
ezdat |
a |
newdata |
An optional data frame in which to look for evaluation data. If omitted, the training data are used. |
se |
a scalar logical value indicating whether to compute and retain
coefficient standard errors and their asymptotic covariance matrix.
Defaults to |
residuals |
a logical value indicating that you want residuals computed and
returned in the resulting |
y.eval |
If |
Further arguments are passed to npplregbw and its component npregbw searches when bandwidths are computed internally.
... |
additional arguments supplied to |
With a formula-derived bandwidth object, supplying only tydat
replaces the evaluated response in retained-training-sample order: one row
per observation retained after the original subset and missing-value selection.
Original excluded rows are not restored; row names or equal lengths do not
imply original-data order. The effective na.action is then applied
jointly to the retained predictors and replacement response; any new omission
indices refer to this retained sample. The selected bandwidths remain fixed,
and the returned object retains the replacement sample for subsequent refits.
Use data for full formula-data replacement, not together with a partial
response replacement. Explicit native training arguments retain their separate
positional contract.
For native (non-formula) objects, named newdata columns are matched
to the retained variable names and reordered as needed. Extra columns are
ignored; missing, duplicate or ambiguous names are errors. An unnamed
matrix or vector remains positional for a single evaluation role.
Explicit native evaluation arguments retain their positional contract and
take precedence over newdata.
For a native bandwidth object, newdata is split into
exdat and ezdat using the retained linear and nonparametric
predictor names. Names must identify both roles unambiguously;
explicitly supplied native evaluation arguments take precedence. This
evaluates at the requested rows without repeating bandwidth selection.
Nuisance regressions inherit numerical ridging from npreg.
Their point fits do not apply its residual uncertainty correction to the
separate partially linear coefficient covariance described below.
Documentation guide: see npplregbw for partially linear
bandwidth selection, npregbw for the component
nonparametric regression search controls, np.kernels
for kernels, np.options for global options, and
plot, plot.np for plotting options.
When bws is omitted, the formula and default methods call
npplregbw first and pass bandwidth-selection arguments
from ... to that call. When bws is already a
plbandwidth object, npplreg estimates with the stored
bandwidth metadata in that object.
Argument groups for bandwidth selection are documented on
npplregbw and, for the component nonparametric
regressions, npregbw. The most common workflow is to
choose the linear X variables and nonparametric Z
variables first, then bandwidth/search controls for the
Z-side nonparametric regressions, and finally
local-polynomial/NOMAD controls when using polynomial-adaptive fits.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
npplreg uses a combination of OLS and nonparametric
regression to estimate the parameter in the model
.
npplreg implements a variety of methods for
nonparametric regression on multivariate (-variate) explanatory
data defined over a set of possibly continuous and/or discrete
(unordered, ordered) data. The approach is based on Li and Racine
(2003) who employ ‘generalized product kernels’ that admit a mix
of continuous and discrete data types.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating the
density at the point . Generalized nearest-neighbor bandwidths change
with the point at which the density is estimated, . Fixed bandwidths
are constant over the support of .
Data contained in the data frame tzdat may be a mix of
continuous (default), unordered discrete (to be specified in the data
frame tzdat using factor), and ordered discrete
(to be specified in the data frame tzdat using
ordered). Data can be entered in an arbitrary order and
data types will be detected automatically by the routine (see
np for details).
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth order Gaussian and Epanechnikov kernels, and the uniform kernel. Unordered discrete data types use a variation on Aitchison and Aitken's (1976) kernel, while ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
For practitioners who want the recommended automatic local-polynomial degree-and-bandwidth NOMAD route
without spelling out all LP tuning arguments,
npplreg(..., nomad=TRUE) and npplregbw(..., nomad=TRUE)
expand missing settings to the same documented preset. Explicit
incompatible settings fail fast rather than being silently rewritten.
npplreg returns a plregression object. The generic
accessor functions coef, fitted,
residuals, predict, and
vcov, extract (or
estimate) coefficients, estimated values, residuals,
predictions, and variance-covariance matrices,
respectively, from
the returned object. Furthermore, the functions summary
and plot support objects of this type. The returned object
has the following components:
For plregression objects, predict(object, se.fit = TRUE)
returns a list with components fit and se.fit. The
se.fit component contains asymptotic prediction standard errors
computed from the partially linear fitted-value linear operator and
the squared residuals from the training fit. This explicit prediction
request works even when the original model used se = FALSE;
it does not require coefficient covariance or alter the original object.
With se = TRUE, coefficient covariance allows conditional
heteroskedasticity. Let
be the residualized linear design, the residuals
from the training fit, and . The returned
covariance is
,
where is the number of complete training observations, is
the number of linear regressors and the number of smoothing
variables. The multiplier retains the package's finite-sample convention;
it is not an estimate of a smoother's effective degrees of freedom.
Coefficient standard errors are square roots of its diagonal. This
coefficient covariance and the fitted-value prediction errors above are
different targets; neither changes the coefficient or bandwidth estimates.
evalx |
evaluation points |
evalz |
evaluation points |
mean |
estimation of the regression, or conditional mean, at the evaluation points |
xcoef |
coefficient(s) corresponding to the components
|
xcoeferr |
standard errors of the coefficients, or |
xcoefvcov |
covariance matrix of the coefficients, or |
se |
whether coefficient uncertainty was requested |
bws |
the canonical bandwidth object, stored as a
|
bw |
backward-compatible alias for |
resid |
if |
R2 |
coefficient of determination (Doksum and Samarov (1995)) |
MSE |
mean squared error |
MAE |
mean absolute error |
MAPE |
mean absolute percentage error |
CORR |
absolute value of Pearson's correlation coefficient |
SIGN |
fraction of observations where fitted and observed values agree in sign |
The partially linear model is
. The Robinson-style construction
residualizes and each column of on , then
solves the final least-squares problem using those residualized
variables. Thus the nonparametric part of the problem is a sequence
of conditional-mean regressions and
, followed by the parametric solve for
. In local-polynomial/NOMAD fits, the nuisance regressions
may select child-specific continuous polynomial degrees.
For book-length derivations, see Li and Racine (2007), Chapter 7 Semiparametric Partially Linear Models, especially Sections 7.1, 7.2, and 7.4, and Racine (2019), Chapter 8 Semiparametric Conditional Mean Function Estimation, especially Robinson's partially linear model.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Doksum, K. and A. Samarov (1995), “Nonparametric estimation of global functionals and a measure of the explanatory power of covariates in regression,” The Annals of Statistics, 23 1443-1473.
Gao, Q. and L. Liu and J.S. Racine (2015), “A partially linear kernel estimator for categorical data,” Econometric Reviews, 34 (6-10), 958-977.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2004), “Cross-validated local linear nonparametric regression,” Statistica Sinica, 14, 485-512.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Racine, J.S. and Q. Li (2004), “Nonparametric estimation of regression functions with both categorical and continuous data,” Journal of Econometrics, 119, 99-130.
Robinson, P.M. (1988), “Root-n-consistent semiparametric regression,” Econometrica, 56, 931-954.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np
npregbw, npreg
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we simulate an # example for a partially linear model and compare the coefficient # estimates from the partially linear model with those from a correctly # specified parametric model... set.seed(42) n <- 250 x1 <- rnorm(n) x2 <- rbinom(n, 1, .5) z1 <- rbinom(n, 1, .5) z2 <- rnorm(n) y <- 1 + x1 + x2 + z1 + sin(z2) + rnorm(n) # First, compute data-driven bandwidths. This may take a few minutes # depending on the speed of your computer... bw <- npplregbw(formula=y~x1+factor(x2)|factor(z1)+z2) # Next, compute the partially linear fit pl <- npplreg(bws=bw, se=TRUE) # Print a summary of the model... summary(pl) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Retrieve the coefficient estimates and their standard errors... coef(pl) coef(pl, se = TRUE) # Compare the partially linear results to those from a correctly # specified model's coefficients for x1 and x2 ols <- lm(y~x1+factor(x2)+factor(z1)+I(sin(z2))) # The intercept is coef()[1], and those for x1 and x2 are coef()[2] and # coef()[3]. The standard errors are the square root of the diagonal of # the variance-covariance matrix (elements 2 and 3) coef(ols)[2:3] sqrt(diag(vcov(ols)))[2:3] # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Plot the regression surfaces via plot() (i.e., plot the `partial # regression surface plots'). if (interactive()) plot(bw) # Note - to plot regression surfaces with variability bounds constructed # from bootstrapped standard errors, use the following (note that this # may take a minute or two depending on the speed of your computer as # the bootstrapping is done in real time, and note also that we override # the default number of bootstrap replications (9999) reducing them to 25 # in order to quickly compute standard errors in this instance - don't # of course do this in general) plot(bw, B=25, errors="bootstrap") # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we simulate an # example for a partially linear model and compare the coefficient # estimates from the partially linear model with those from a correctly # specified parametric model... set.seed(42) n <- 250 x1 <- rnorm(n) x2 <- rbinom(n, 1, .5) z1 <- rbinom(n, 1, .5) z2 <- rnorm(n) y <- 1 + x1 + x2 + z1 + sin(z2) + rnorm(n) X <- data.frame(x1, factor(x2)) Z <- data.frame(factor(z1), z2) # First, compute data-driven bandwidths. This may take a few minutes # depending on the speed of your computer... bw <- npplregbw(xdat=X, zdat=Z, ydat=y) # Next, compute the partially linear fit pl <- npplreg(bws=bw, se=TRUE) # Print a summary of the model... summary(pl) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Retrieve the coefficient estimates and their standard errors... coef(pl) coef(pl, se = TRUE) # Compare the partially linear results to those from a correctly # specified model's coefficients for x1 and x2 ols <- lm(y~x1+factor(x2)+factor(z1)+I(sin(z2))) # The intercept is coef()[1], and those for x1 and x2 are coef()[2] and # coef()[3]. The standard errors are the square root of the diagonal of # the variance-covariance matrix (elements 2 and 3) coef(ols)[2:3] sqrt(diag(vcov(ols)))[2:3] # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Plot the regression surfaces via plot() (i.e., plot the `partial # regression surface plots'). if (interactive()) plot(bw) # Note - to plot regression surfaces with variability bounds constructed # from bootstrapped standard errors, use the following (note that this # may take a minute or two depending on the speed of your computer as # the bootstrapping is done in real time, and note also that we override # the default number of bootstrap replications (9999) reducing them to 25 # in order to quickly compute standard errors in this instance - don't # of course do this in general) plot(bw, B=25, errors="bootstrap") ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we simulate an # example for a partially linear model and compare the coefficient # estimates from the partially linear model with those from a correctly # specified parametric model... set.seed(42) n <- 250 x1 <- rnorm(n) x2 <- rbinom(n, 1, .5) z1 <- rbinom(n, 1, .5) z2 <- rnorm(n) y <- 1 + x1 + x2 + z1 + sin(z2) + rnorm(n) # First, compute data-driven bandwidths. This may take a few minutes # depending on the speed of your computer... bw <- npplregbw(formula=y~x1+factor(x2)|factor(z1)+z2) # Next, compute the partially linear fit pl <- npplreg(bws=bw, se=TRUE) # Print a summary of the model... summary(pl) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Retrieve the coefficient estimates and their standard errors... coef(pl) coef(pl, se = TRUE) # Compare the partially linear results to those from a correctly # specified model's coefficients for x1 and x2 ols <- lm(y~x1+factor(x2)+factor(z1)+I(sin(z2))) # The intercept is coef()[1], and those for x1 and x2 are coef()[2] and # coef()[3]. The standard errors are the square root of the diagonal of # the variance-covariance matrix (elements 2 and 3) coef(ols)[2:3] sqrt(diag(vcov(ols)))[2:3] # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Plot the regression surfaces via plot() (i.e., plot the `partial # regression surface plots'). if (interactive()) plot(bw) # Note - to plot regression surfaces with variability bounds constructed # from bootstrapped standard errors, use the following (note that this # may take a minute or two depending on the speed of your computer as # the bootstrapping is done in real time, and note also that we override # the default number of bootstrap replications (9999) reducing them to 25 # in order to quickly compute standard errors in this instance - don't # of course do this in general) plot(bw, B=25, errors="bootstrap") # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we simulate an # example for a partially linear model and compare the coefficient # estimates from the partially linear model with those from a correctly # specified parametric model... set.seed(42) n <- 250 x1 <- rnorm(n) x2 <- rbinom(n, 1, .5) z1 <- rbinom(n, 1, .5) z2 <- rnorm(n) y <- 1 + x1 + x2 + z1 + sin(z2) + rnorm(n) X <- data.frame(x1, factor(x2)) Z <- data.frame(factor(z1), z2) # First, compute data-driven bandwidths. This may take a few minutes # depending on the speed of your computer... bw <- npplregbw(xdat=X, zdat=Z, ydat=y) # Next, compute the partially linear fit pl <- npplreg(bws=bw, se=TRUE) # Print a summary of the model... summary(pl) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Retrieve the coefficient estimates and their standard errors... coef(pl) coef(pl, se = TRUE) # Compare the partially linear results to those from a correctly # specified model's coefficients for x1 and x2 ols <- lm(y~x1+factor(x2)+factor(z1)+I(sin(z2))) # The intercept is coef()[1], and those for x1 and x2 are coef()[2] and # coef()[3]. The standard errors are the square root of the diagonal of # the variance-covariance matrix (elements 2 and 3) coef(ols)[2:3] sqrt(diag(vcov(ols)))[2:3] # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Plot the regression surfaces via plot() (i.e., plot the `partial # regression surface plots'). if (interactive()) plot(bw) # Note - to plot regression surfaces with variability bounds constructed # from bootstrapped standard errors, use the following (note that this # may take a minute or two depending on the speed of your computer as # the bootstrapping is done in real time, and note also that we override # the default number of bootstrap replications (9999) reducing them to 25 # in order to quickly compute standard errors in this instance - don't # of course do this in general) plot(bw, B=25, errors="bootstrap") ## End(Not run)
npplregbw computes a bandwidth object for a partially linear
kernel regression estimate of a one (1) dimensional dependent variable
on -variate explanatory data, using the model given a set of
estimation points, training points (consisting of explanatory data and
dependent data), and a bandwidth specification, which can be a
rbandwidth object, or a bandwidth vector, bandwidth type and
kernel type.
npplregbw(...) ## S3 method for class 'formula' npplregbw(formula, data, subset, na.action, call, ...) ## Default S3 method: npplregbw(xdat = stop("invoked without data `xdat'"), ydat = stop("invoked without data `ydat'"), zdat = stop("invoked without data `zdat'"), bandwidth.compute = TRUE, bws, degree = NULL, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, scale.factor.search.lower = NULL, ftol, itmax, nmulti, nomad.remin, powell.remin, small, tol, ...) ## S3 method for class 'plbandwidth' npplregbw(xdat = stop("invoked without data `xdat'"), ydat = stop("invoked without data `ydat'"), zdat = stop("invoked without data `zdat'"), bws, nmulti, ...)npplregbw(...) ## S3 method for class 'formula' npplregbw(formula, data, subset, na.action, call, ...) ## Default S3 method: npplregbw(xdat = stop("invoked without data `xdat'"), ydat = stop("invoked without data `ydat'"), zdat = stop("invoked without data `zdat'"), bandwidth.compute = TRUE, bws, degree = NULL, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, scale.factor.search.lower = NULL, ftol, itmax, nmulti, nomad.remin, powell.remin, small, tol, ...) ## S3 method for class 'plbandwidth' npplregbw(xdat = stop("invoked without data `xdat'"), ydat = stop("invoked without data `ydat'"), zdat = stop("invoked without data `zdat'"), bws, nmulti, ...)
These arguments identify the linear, nonparametric, formula, and bandwidth inputs.
bandwidth.compute |
a logical value which specifies whether to do a numerical search for
bandwidths or not. If set to |
bws |
a bandwidth specification. This can be set as a If left unspecified, |
call |
the original function call. This is passed internally by
|
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
formula |
a symbolic description of variables on which bandwidth selection is to be performed. The details of constructing a formula are described below. |
na.action |
a function which indicates what should happen when the data contain
|
subset |
an optional vector specifying a subset of observations to be used in the fitting process. |
xdat |
a |
ydat |
a one (1) dimensional numeric or integer vector of dependent data, each
element |
zdat |
a |
These arguments control automatic local-polynomial degree search.
degree.max |
optional scalar or integer vector giving upper bounds for automatic
degree search over continuous |
degree.max.cycles |
positive integer giving the maximum number of coordinate-search
sweeps over the degree vector. Ignored for |
degree.min |
optional scalar or integer vector giving lower bounds for automatic
degree search over continuous |
degree.restarts |
non-negative integer giving the number of additional deterministic
coordinate-search restarts. Ignored for |
degree.select |
character string controlling local-polynomial degree handling for
the nuisance regressions of |
degree.start |
optional starting degree vector for automatic coordinate search. If
omitted, the search starts from the degree-zero local-constant
baseline on the continuous |
degree.verify |
logical value indicating whether a coordinate-search solution should
be exhaustively verified over the admissible degree grid after the
heuristic phase completes. Available only for
|
These controls define lower admissibility bounds for continuous fixed-bandwidth search.
scale.factor.search.lower |
optional nonnegative scalar giving the hard lower admissibility
bound for continuous fixed-bandwidth search candidates. Defaults to
|
These arguments control fixed local-polynomial specification for the nonparametric component.
degree |
for local-polynomial partially linear fits, polynomial degree
specification for each continuous nonparametric regressor in
|
These arguments control the optional NOMAD direct-search route for local-polynomial degree and bandwidth search.
nomad |
logical or character shortcut for the recommended automatic local-polynomial
NOMAD route for the partially linear nuisance regressions. When
|
nomad.nmulti |
non-negative integer controlling the inner
the native crs NOMAD C API multistart count used within each outer
NOMAD restart when |
nomad.remin |
logical flag controlling the optional second NOMAD hot start. When
|
search.engine |
character string controlling the automatic local-polynomial search
backend for each nuisance regression when
|
These controls set optimizer tolerances and restart behavior.
ftol |
tolerance on the value of the cross-validation function
evaluated at located minima. Defaults to |
itmax |
integer number of iterations before failure in the numerical
optimization routine. Defaults to |
nmulti |
integer number of times to restart the process of finding extrema of
the cross-validation function from different (random) initial
points. Defaults to |
powell.remin |
logical flag controlling Powell restart-from-minimum behavior. For
ordinary fixed-degree Powell-style search, |
small |
a small number, at about the precision of the data type
used. Defaults to |
tol |
tolerance on the position of located minima of the
cross-validation function. Defaults to |
These arguments collect remaining controls passed through S3 methods.
... |
additional arguments supplied to specify the regression type,
bandwidth type, kernel types, selection methods, and so on. To do
this, you may specify any of |
Formula bandwidth objects retain the prepared training sample (after alignment,
subsetting and missing-value handling) and the resolved missing-value policy.
Later refits use that sample even if constructor variables are rebound.
Supplying explicit training data to the estimator replaces the training data;
evaluation via newdata does not. Retention requires storage proportional
to the sample size times the number of variables, not a pairwise weight matrix.
Older saved objects without this retained state still rely on their original
data bindings; rebuild their bandwidth object from the intended data before
changing those bindings. User-defined transformation and missing-value
functions should not rely on subsequently modified closure state.
The scale.factor.* controls are dimensionless search
controls. The package converts scale factors to bandwidths using the
estimator-specific scaling encoded in the bandwidth object, including
kernel order and the number of continuous variables relevant for the
estimator. Users should not pre-multiply these controls by sample-size
or standard-deviation factors.
scale.factor.init controls the deterministic first search
start when that control is exposed. scale.factor.init.lower
and scale.factor.init.upper define the random multistart
interval when exposed. scale.factor.search.lower is the lower
admissibility bound for continuous fixed-bandwidth search candidates.
The effective first start is max(scale.factor.init,
scale.factor.search.lower) when both controls are present, and the
effective random-start lower endpoint is
max(scale.factor.init.lower, scale.factor.search.lower).
scale.factor.init.upper must be at least that effective lower
endpoint; the package errors rather than silently expanding the user's
interval.
When scale.factor.search.lower is NULL, an existing
bandwidth object's stored floor is inherited when available;
otherwise the package default 0.1 is used. Explicit bandwidths
supplied for storage with bandwidth.compute = FALSE are not
rewritten by the search floor.
Categorical search-start controls such as dfac.init,
lbd.init, and hbd.init have separate semantics and are
not affected by scale.factor.search.lower.
Documentation guide: see npregbw for component
nonparametric regression bandwidth controls, np.kernels
for kernels, np.options for global options, and
plot, plot.np for plotting options.
The partially linear bandwidth-selection argument surface is easiest
to read by decision group: linear xdat inputs,
nonparametric zdat inputs, and existing bandwidth inputs;
local-polynomial/NOMAD controls for the nonparametric component;
numerical search and feasibility controls; formula-interface
controls; and additional bandwidth, kernel, and support controls that
are passed to the component npregbw searches.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
npplregbw implements a variety of methods for nonparametric
regression on multivariate (-variate) explanatory data defined
over a set of possibly continuous and/or discrete (unordered, ordered)
data. The approach is based on Li and Racine (2003), who employ
‘generalized product kernels’ that admit a mix of continuous and
discrete data types.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating the
density at the point . Generalized nearest-neighbor bandwidths change
with the point at which the density is estimated, . Fixed bandwidths
are constant over the support of .
npplregbw may be invoked either with a formula-like
symbolic
description of variables on which bandwidth selection is to be
performed or through a simpler interface whereby data is passed
directly to the function via the xdat, ydat, and
zdat
parameters. Use of these two interfaces is mutually exclusive.
Data contained in the data frame zdat may be a mix of continuous
(default), unordered discrete (to be specified in the data frame
zdat using factor), and ordered discrete (to be
specified in the data frame zdat using
ordered). Data can be entered in an arbitrary order and
data types will be detected automatically by the routine (see
np for details).
Data for which bandwidths are to be estimated may be specified
symbolically. A typical description has the form dependent
data ~ parametric explanatory data
| nonparametric explanatory data,
where dependent data is a univariate response, and
parametric explanatory data and
nonparametric explanatory
data are both series of variables specified by name, separated by
the separation character '+'. For example, y1 ~ x1 + x2 | z1
specifies that the bandwidth object for the partially linear model with
response y1, linear parametric regressors x1 and
x2, and
nonparametric regressor z1 is to be estimated. See below for
further examples.
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth order Gaussian and Epanechnikov kernels, and the uniform kernel. Unordered discrete data types use a variation on Aitchison and Aitken's (1976) kernel, while ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
When the nonparametric component is estimated with
regtype="lp" and degree.select != "manual",
npplregbw determines the zdat-side degree vector and
associated bandwidth coordinates separately for the nuisance
regressions and . With
search.engine="cell", the criterion is profiled over the degree
grid using cached coordinate-wise or exhaustive search together with
repeated fixed-degree bandwidth solves. With
search.engine="nomad" or "nomad+powell", each nuisance
criterion is optimized directly over that child's degree/bandwidth
space using the native crs NOMAD C API; "nomad+powell" then performs
one Powell hot start for that child and keeps the better of the direct
NOMAD and polished solutions. For the nonparametric regression
components, this
polynomial-adaptive joint-search route follows Hall and Racine (2015).
Setting nomad=TRUE is a convenience preset for this automatic
LP route, not a generic optimizer alias. For partially linear
regression it expands any missing values to the equivalent long-form
call
npplregbw(...,
regtype = "lp",
search.engine = "nomad+powell",
degree.select = "coordinate",
bernstein.basis = TRUE,
degree.min = 0L,
degree.max = 10L,
degree.verify = FALSE,
bwtype = "fixed")
Compatible explicit tuning arguments are respected. Incompatible
explicit settings fail fast so the shortcut never silently changes
user-selected semantics.
The character value nomad="auto" applies the same LP shortcut
but leaves search.engine and degree.select eligible for
data-driven resolution when both were not supplied explicitly: scalar
continuous degree searches use the exhaustive degree-grid route, while
higher-dimensional degree searches keep the NOMAD/Powell route.
Explicit search.engine or degree.select choices are
honored.
if bwtype is set to fixed, an object containing bandwidths
(or scale factors if bwscaling = TRUE) is returned. If it is set to
generalized_nn or adaptive_nn, then instead the th nearest
neighbors are returned for the continuous variables while the discrete
kernel bandwidths are returned for the discrete variables. Bandwidths
are stored in a list under the component name bw. Each element
is an rbandwidth object. The first
element of the list corresponds to the regression of on .
Each subsequent element is the bandwidth object corresponding to the
regression of the th column of on . See examples
for more information.
The component regression searches inherit numerical ridging from
npregbw; its motivation is described in npreg.
npplregbw selects the bandwidths and, for local-polynomial
routes, child-specific degree/search metadata used by
npplreg. The target model is
; the bandwidth object controls the
nuisance regressions and used in
the final partially linear solve.
For book-length derivations, see Li and Racine (2007), Chapter 7 Semiparametric Partially Linear Models, especially Sections 7.1, 7.2, and 7.4, and Racine (2019), Chapter 8 Semiparametric Conditional Mean Function Estimation.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Caution: multivariate data-driven bandwidth selection methods are, by
their nature, computationally intensive. Virtually all methods
require dropping the th observation from the data set, computing an
object, repeating this for all observations in the sample, then
averaging each of these leave-one-out estimates for a given
value of the bandwidth vector, and only then repeating this a large
number of times in order to conduct multivariate numerical
minimization/maximization. Furthermore, due to the potential for local
minima/maxima, restarting this procedure a large number of times may
often be necessary. This can be frustrating for users possessing
large datasets. For exploratory purposes, you may wish to override the
default search tolerances, say, setting ftol=.01 and tol=.01 and
conduct multistarting (the default is to restart min(2, ncol(zdat))
times) as is done for a number of examples. Once the procedure
terminates, you can restart search with default tolerances using those
bandwidths obtained from the less rigorous search (i.e., set
bws=bw on subsequent calls to this routine where bw is
the initial bandwidth object). A version of this package using the
Rmpi wrapper is under development that allows one to deploy
this software in a clustered computing environment to facilitate
computation involving large datasets.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Gao, Q. and L. Liu and J.S. Racine (2015), “A partially linear kernel estimator for categorical data,” Econometric Reviews, 34 (6-10), 958-977.
Hall, P. and J.S. Racine (2015), “Infinite Order Cross-Validated Local Polynomial Regression,” Journal of Econometrics, 185, 510-525.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2004), “Cross-validated local linear nonparametric regression,” Statistica Sinica, 14, 485-512.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Racine, J.S. and Q. Li (2004), “Nonparametric estimation of regression functions with both categorical and continuous data,” Journal of Econometrics, 119, 99-130.
Robinson, P.M. (1988), “Root-n-consistent semiparametric regression,” Econometrica, 56, 931-954.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np
npregbw, npreg
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we simulate an # example for a partially linear model and perform bandwidth selection set.seed(42) n <- 250 x1 <- rnorm(n) x2 <- rbinom(n, 1, .5) z1 <- rbinom(n, 1, .5) z2 <- rnorm(n) y <- 1 + x1 + x2 + z1 + sin(z2) + rnorm(n) X <- data.frame(x1, factor(x2)) Z <- data.frame(factor(z1), z2) # Compute data-driven bandwidths... this may take a minute or two # depending on the speed of your computer... bw <- npplregbw(formula=y~x1+factor(x2)|factor(z1)+z2) summary(bw) # Note - the default is to use the local constant estimator. If you wish # to use instead a local linear estimator, this is accomplished via # npplregbw(xdat=X, zdat=Z, ydat=y, regtype="ll") # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. # You may want to manually specify your bandwidths bw.mat <- matrix(data = c(0.19, 0.34, # y on Z 0.00, 0.74, # X[,1] on Z 0.29, 0.23), # X[,2] on Z ncol = ncol(Z), byrow=TRUE) bw <- npplregbw(formula=y~x1+factor(x2)|factor(z1)+z2, bws=bw.mat, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # You may want to tweak some of the bandwidths bw$bw[[1]] # y on Z, alternatively bw$bw$yzbw bw$bw[[1]]$bw <- c(0.17, 0.30) bw$bw[[2]] # X[,1] on Z bw$bw[[2]]$bw[1] <- 0.00054 summary(bw) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we simulate an # example for a partially linear model and perform bandwidth selection set.seed(42) n <- 250 x1 <- rnorm(n) x2 <- rbinom(n, 1, .5) z1 <- rbinom(n, 1, .5) z2 <- rnorm(n) y <- 1 + x1 + x2 + z1 + sin(z2) + rnorm(n) X <- data.frame(x1, factor(x2)) Z <- data.frame(factor(z1), z2) # Compute data-driven bandwidths... this may take a minute or two # depending on the speed of your computer... bw <- npplregbw(xdat=X, zdat=Z, ydat=y) summary(bw) # Note - the default is to use the local constant estimator. If you wish # to use instead a local linear estimator, this is accomplished via # npplregbw(xdat=X, zdat=Z, ydat=y, regtype="ll") # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. # You may want to manually specify your bandwidths bw.mat <- matrix(data = c(0.19, 0.34, # y on Z 0.00, 0.74, # X[,1] on Z 0.29, 0.23), # X[,2] on Z ncol = ncol(Z), byrow=TRUE) bw <- npplregbw(xdat=X, zdat=Z, ydat=y, bws=bw.mat, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # You may want to tweak some of the bandwidths bw$bw[[1]] # y on Z, alternatively bw$bw$yzbw bw$bw[[1]]$bw <- c(0.17, 0.30) bw$bw[[2]] # X[,1] on Z bw$bw[[2]]$bw[1] <- 0.00054 summary(bw) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we simulate an # example for a partially linear model and perform bandwidth selection set.seed(42) n <- 250 x1 <- rnorm(n) x2 <- rbinom(n, 1, .5) z1 <- rbinom(n, 1, .5) z2 <- rnorm(n) y <- 1 + x1 + x2 + z1 + sin(z2) + rnorm(n) X <- data.frame(x1, factor(x2)) Z <- data.frame(factor(z1), z2) # Compute data-driven bandwidths... this may take a minute or two # depending on the speed of your computer... bw <- npplregbw(formula=y~x1+factor(x2)|factor(z1)+z2) summary(bw) # Note - the default is to use the local constant estimator. If you wish # to use instead a local linear estimator, this is accomplished via # npplregbw(xdat=X, zdat=Z, ydat=y, regtype="ll") # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. # You may want to manually specify your bandwidths bw.mat <- matrix(data = c(0.19, 0.34, # y on Z 0.00, 0.74, # X[,1] on Z 0.29, 0.23), # X[,2] on Z ncol = ncol(Z), byrow=TRUE) bw <- npplregbw(formula=y~x1+factor(x2)|factor(z1)+z2, bws=bw.mat, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # You may want to tweak some of the bandwidths bw$bw[[1]] # y on Z, alternatively bw$bw$yzbw bw$bw[[1]]$bw <- c(0.17, 0.30) bw$bw[[2]] # X[,1] on Z bw$bw[[2]]$bw[1] <- 0.00054 summary(bw) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we simulate an # example for a partially linear model and perform bandwidth selection set.seed(42) n <- 250 x1 <- rnorm(n) x2 <- rbinom(n, 1, .5) z1 <- rbinom(n, 1, .5) z2 <- rnorm(n) y <- 1 + x1 + x2 + z1 + sin(z2) + rnorm(n) X <- data.frame(x1, factor(x2)) Z <- data.frame(factor(z1), z2) # Compute data-driven bandwidths... this may take a minute or two # depending on the speed of your computer... bw <- npplregbw(xdat=X, zdat=Z, ydat=y) summary(bw) # Note - the default is to use the local constant estimator. If you wish # to use instead a local linear estimator, this is accomplished via # npplregbw(xdat=X, zdat=Z, ydat=y, regtype="ll") # Note - see the example for npudensbw() for multiple illustrations # of how to change the kernel function, kernel order, and so forth. # You may want to manually specify your bandwidths bw.mat <- matrix(data = c(0.19, 0.34, # y on Z 0.00, 0.74, # X[,1] on Z 0.29, 0.23), # X[,2] on Z ncol = ncol(Z), byrow=TRUE) bw <- npplregbw(xdat=X, zdat=Z, ydat=y, bws=bw.mat, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # You may want to tweak some of the bandwidths bw$bw[[1]] # y on Z, alternatively bw$bw$yzbw bw$bw[[1]]$bw <- c(0.17, 0.30) bw$bw[[2]] # X[,1] on Z bw$bw[[2]]$bw[1] <- 0.00054 summary(bw) ## End(Not run)
npqcmstest implements a consistent test for correct
specification of parametric quantile regression models (linear or
nonlinear) as described in Racine (2006) which extends the work of
Zheng (1998).
npqcmstest(formula, data = NULL, subset, xdat, ydat, model = stop(paste(sQuote("model")," has not been provided")), tau = 0.5, distribution = c("bootstrap", "asymptotic"), bwydat = c("y","varepsilon"), boot.method = c("iid","wild","wild-rademacher"), B = 399, pivot = TRUE, density.weighted = TRUE, random.seed = 42, ...)npqcmstest(formula, data = NULL, subset, xdat, ydat, model = stop(paste(sQuote("model")," has not been provided")), tau = 0.5, distribution = c("bootstrap", "asymptotic"), bwydat = c("y","varepsilon"), boot.method = c("iid","wild","wild-rademacher"), B = 399, pivot = TRUE, density.weighted = TRUE, random.seed = 42, ...)
These arguments identify the model formula/data interface and explicit data inputs.
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
formula |
a symbolic description of the quantile regression model to be
tested. If |
model |
a model object obtained from a call to |
subset |
an optional vector specifying a subset of observations to be used. |
xdat |
a |
ydat |
a one (1) dimensional numeric or integer vector of dependent data, each
element |
These arguments control the quantile level, test statistic, bootstrap procedure, and reproducibility settings.
boot.method |
a character string used to specify the bootstrap method.
|
B |
an integer value specifying the number of bootstrap replications to
use. Defaults to |
bwydat |
a character string used to specify the left hand side variable used
in bandwidth selection. |
density.weighted |
a logical value specifying whether the statistic should be
weighted by the density of |
distribution |
a character string used to specify the method of estimating the
distribution of the statistic to be calculated. |
pivot |
a logical value specifying whether the statistic should be
normalised such that it approaches |
random.seed |
an integer used to seed R's random number generator. This is to ensure replicability. Defaults to 42. |
tau |
a finite scalar in (0,1) specifying the desired |
Further arguments are passed to the bandwidth-selection routines used by the test.
... |
additional arguments supplied to control bandwidth selection on the
residuals. One can specify the bandwidth type,
kernel types, and so on. To do this, you may specify any of |
Documentation guide: see np.kernels for kernels,
np.options for global options, and
plot for plotting options.
For distribution = "bootstrap", each quantile model is still
refitted separately using the selected bootstrap law. The resulting score
vectors are collected in bounded groups, and the fixed-design kernel
contractions for and, when requested, are
evaluated as multi-response kernel sums. This reuses kernel geometry
without forming a dense observation-by-observation weight matrix or
changing score order, tau, bwydat, pivoting, density
weighting, or random draws.
The selected bandwidth's effective kernel metadata are shared by the observed and bootstrap statistics. Manual bandwidth inputs and selection controls are not forwarded a second time as kernel-sum arguments.
Bootstrap refits preserve the model's observation weights. Weighted quantile models supply their raw design and response through the retained model frame; zero observation weights need not be inverted.
Model residuals, fitted values, response and design use the model's compact
complete-observation sample, including when it was fitted with
na.exclude. The supplied test data must represent those same complete
observations in the same order. Row counts and response values are checked;
when those agree, the caller remains responsible for supplying the matching
covariate rows. The test does not infer a new pairing or reorder observations.
The original model and its missing-value restoration policy are not modified.
npqcmstest returns an object of type cmstest with the
following components. Components will contain information
related to Jn or In depending on the value of pivot:
Jn |
the statistic |
In |
the statistic |
Omega.hat |
as described in Racine, J.S. (2006). |
q.* |
the various quantiles of the statistic |
P |
the P-value of the statistic |
Jn.bootstrap |
if |
In.bootstrap |
if |
summary supports object of type cmstest.
The bootstrap upper-tail p-value is the proportion of bootstrap statistics greater than or equal to the observed statistic. Ties count as at least as extreme, giving the conservative tie convention for discrete statistics. This is the ordinary bootstrap proportion, without an add-one correction; a reported zero is possible with a finite number of replications.
npqcmstest tests a parametric conditional-quantile
specification against a nonparametric conditional-quantile
alternative at the supplied . The test therefore sits at the
intersection of conditional CDF/quantile estimation and model
specification testing.
For book-length background, see Li and Racine (2007), Chapter 12 Model Specification Tests and Chapter 6 Conditional CDF and Quantile Estimation. For the later workflow treatment of conditional CDFs and quantiles, see Racine (2019), Chapter 4 Conditional Probability Density and Cumulative Distribution Functions.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Koenker, R.W. and G.W. Bassett (1978), “Regression quantiles,” Econometrica, 46, 33-50.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Murphy, K. M. and F. Welch (1990), “Empirical age-earnings profiles,” Journal of Labor Economics, 8, 202-229.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Racine, J.S. (2006), “Consistent specification testing of heteroskedastic parametric regression quantile models with mixed data,” manuscript.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
Zheng, J. (1998), “A consistent nonparametric test of parametric regression models under conditional quantile restrictions,” Econometric Theory, 14, 123-138.
np.kernels, np.options,
plot, npregbw.
## Not run: # EXAMPLE 1: For this example, we conduct a consistent quantile regression # model specification test for a parametric wage quantile regression # model that is quadratic in age. The work of Murphy and Welch (1990) # would suggest that this parametric quantile regression model is # misspecified. library("quantreg") data("cps71") with(cps71, { model <- rq(logwage~age+I(age^2), tau=0.5, model=TRUE) if (interactive()) plot(age, logwage) lines(age, fitted(model)) X <- data.frame(age) # Note - this may take a few minutes depending on the speed of your # computer... npqcmstest(model = model, xdat = X, ydat = logwage, tau=0.5) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next try Murphy & Welch's (1990) suggested quintic specification. model <- rq(logwage~age+I(age^2)+I(age^3)+I(age^4)+I(age^5), model=TRUE) if (interactive()) plot(age, logwage) lines(age, fitted(model)) X <- data.frame(age) # Note - this may take a few minutes depending on the speed of your # computer... npqcmstest(model = model, xdat = X, ydat = logwage, tau=0.5) }) ## End(Not run)## Not run: # EXAMPLE 1: For this example, we conduct a consistent quantile regression # model specification test for a parametric wage quantile regression # model that is quadratic in age. The work of Murphy and Welch (1990) # would suggest that this parametric quantile regression model is # misspecified. library("quantreg") data("cps71") with(cps71, { model <- rq(logwage~age+I(age^2), tau=0.5, model=TRUE) if (interactive()) plot(age, logwage) lines(age, fitted(model)) X <- data.frame(age) # Note - this may take a few minutes depending on the speed of your # computer... npqcmstest(model = model, xdat = X, ydat = logwage, tau=0.5) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next try Murphy & Welch's (1990) suggested quintic specification. model <- rq(logwage~age+I(age^2)+I(age^3)+I(age^4)+I(age^5), model=TRUE) if (interactive()) plot(age, logwage) lines(age, fitted(model)) X <- data.frame(age) # Note - this may take a few minutes depending on the speed of your # computer... npqcmstest(model = model, xdat = X, ydat = logwage, tau=0.5) }) ## End(Not run)
npqreg computes a kernel quantile regression estimate of a one
(1) dimensional dependent variable on -variate explanatory
data, given a set of evaluation points, training points (consisting of
explanatory data and dependent data), and a bandwidth specification
using the methods of Li and Racine (2008) and Li, Lin and Racine
(2013). A bandwidth specification can be a condbandwidth object,
or a bandwidth vector, bandwidth type and kernel type.
npqreg(bws, ...) ## S3 method for class 'formula' npqreg(bws, data = NULL, newdata = NULL, ..., se = FALSE) ## S3 method for class 'condbandwidth' npqreg(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), exdat, tau = 0.5, gradients = FALSE, tol = 1.490116e-04, small = 1.490116e-05, itmax = 10000, ..., se = FALSE) ## Default S3 method: npqreg(bws, txdat, tydat, nomad = FALSE, ..., se = FALSE) ## S3 method for class 'qregression' predict(object, se.fit = FALSE, ...) ## S3 method for class 'qregression' plot(x, ...)npqreg(bws, ...) ## S3 method for class 'formula' npqreg(bws, data = NULL, newdata = NULL, ..., se = FALSE) ## S3 method for class 'condbandwidth' npqreg(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), exdat, tau = 0.5, gradients = FALSE, tol = 1.490116e-04, small = 1.490116e-05, itmax = 10000, ..., se = FALSE) ## Default S3 method: npqreg(bws, txdat, tydat, nomad = FALSE, ..., se = FALSE) ## S3 method for class 'qregression' predict(object, se.fit = FALSE, ...) ## S3 method for class 'qregression' plot(x, ...)
These arguments identify the bandwidth specification, formula/data interface, and training data.
bws |
a bandwidth specification. This can be set as a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
txdat |
a |
tydat |
a one (1) dimensional numeric or integer vector of dependent data, each
element |
object |
an object of class |
x |
an object of class |
This argument controls the recommended automatic local-polynomial NOMAD route, which jointly selects continuous polynomial degree and bandwidths when conditional-distribution bandwidths are computed inside npqreg.
nomad |
logical shortcut passed through to |
These arguments control where the quantile regression is evaluated and which fitted quantities are returned.
exdat |
a |
gradients |
a logical value indicating that you want gradients of the conditional
quantile with respect to the conditioning variables computed and returned
in the resulting |
newdata |
An optional data frame in which to look for evaluation data. If omitted, the training data are used. |
se.fit |
logical value. If |
se |
a scalar logical controlling asymptotic standard-error computation.
Defaults to |
tau |
a numeric scalar or vector specifying the quantile probability or
probabilities |
These arguments control the one-dimensional numerical quantile extraction step.
itmax |
integer maximum number of iterations allowed in the one-dimensional
quantile refinement. Defaults to |
small |
absolute interval-width allowance, in response units, added to the
relative stopping tolerance in the one-dimensional quantile refinement.
Defaults to |
tol |
relative tolerance on the one-dimensional quantile location refinement.
Refinement stops when the bracket width is at most |
Further arguments are passed to the bandwidth-selection counterpart, prediction/evaluation route, or plot route as appropriate.
... |
additional arguments supplied to |
Conditional fitting and replay use the literal categorical kernels for
both explanatory and response variables. Near-upper categorical bandwidths
are not replaced by approximate constant factors. The same target is used
for levels, gradients, standard errors, conditional hats, and reconstructed
plot uncertainty. This conditional-family policy does not change direct
regression or unconditional kernel-sum evaluation and does not modify the
caller's np.largelambda option.
With a formula-derived bandwidth object, supplying only tydat
replaces the evaluated response in retained-training-sample order: one row
per observation retained after the original subset and missing-value selection.
Original excluded rows are not restored; row names or equal lengths do not
imply original-data order. The effective na.action is then applied
jointly to the retained predictors and replacement response; any new omission
indices refer to this retained sample. The selected bandwidths remain fixed,
and the returned object retains the replacement sample for subsequent refits.
Use data for full formula-data replacement, not together with a partial
response replacement. Explicit native training arguments retain their separate
positional contract.
For native (non-formula) objects, named newdata columns are matched
to the retained variable names and reordered as needed. Extra columns are
ignored; missing, duplicate or ambiguous names are errors. An unnamed
matrix or vector remains positional for a single evaluation role.
Explicit native evaluation arguments retain their positional contract and
take precedence over newdata.
For a native bandwidth object, newdata supplies exdat;
explicitly supplied native evaluation arguments take precedence. This
evaluates at the requested rows without repeating bandwidth selection.
Formula variables of class ts, including lagged variables, are
aligned on their common time support before fitting. Other variables
must already have the length of that intersection. Supply explicitly
aligned rows when using native data arguments instead of a formula.
Local-polynomial calculations inherit numerical ridging from
npcdist. See that estimator's help for the solve
policy and its distinct conditional uncertainty formula.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot, plot.np for plotting options.
Given a conditional distribution bandwidth object, npqreg
estimates the conditional distribution function
and extracts the requested conditional quantile. For
, the conditional quantile at probability
is
Equivalently, is a quasi-inverse of the conditional
distribution in the sense of Nelsen (2006): an inverse agrees with
on the range of , while outside that range the
generalized inverse is defined by the lower endpoint at which
reaches or exceeds the requested probability. Numerically,
npqreg inverts the selected conditional distribution estimator
represented by bws. This includes the selected bandwidth type,
kernels, local-polynomial regression type, selected polynomial degree,
basis, and Bernstein-basis setting inherited from npcdistbw.
If the bandwidth object was selected with nomad=TRUE, the returned
conditional-distribution bandwidth object is an LP object: its
regtype/regtype.engine metadata identify the selected
local-polynomial route and its degree/degree.engine metadata
record the selected continuous-coordinate polynomial degree. npqreg,
predict, and plot reuse this stored LP metadata;
plotting additional tau values does not recompute or downgrade the
selected degree.
The one-dimensional inversion is carried out over the observed support
of the dependent variable using the same selected conditional CDF
estimator that is later used for quantile standard errors and gradients.
The arguments tol, small, and itmax control this
one-dimensional refinement. Conditional quantile inversion requires a
monotone dependent-variable conditional distribution estimate; therefore
npqreg supports cykerorder = 2 for this route and rejects
higher-order dependent-variable CDF kernels, which can be nonmonotone.
During this inversion, an external predictor row identified by the selected
CDF as having no kernel support returns NA for its quantiles and
requested standard errors and gradients. Supported rows retain their
original order, including repeated evaluation points and vector-tau
requests. An unavailable categorical counterfactual affects only the
corresponding contrast, not an otherwise supported base quantile. One
warning summarizes affected external rows after the public evaluation or
plot call completes. Other numerical failures, and required training or
bootstrap evaluations, retain their strict error behavior.
The existing point-only shortcut for an exactly constant response is unchanged: it returns that response value without evaluating the conditional CDF. External predictor support is not checked by this shortcut; requests for standard errors or gradients still enter the conditional evaluation machinery.
Let denote the conditional
density. The asymptotic standard error of the conditional quantile is
computed by the first-order delta method,
using the selected conditional distribution standard-error machinery and the selected conditional density evaluated at the fitted quantile. This corresponds to the quantile variance expression in Li, Lin and Racine (2013).
Conditional-quantile plots support first derivatives only. The default
and explicit gradient.order=1 retain that target; other derivative
orders are rejected before plot fitting or drawing. Higher polynomial
degrees in the fitted bandwidth object do not add higher-order quantile
derivatives. This restriction does not apply to nplsqreg or
conditional-distribution gradient plots.
A scalar quantile can be displayed as a surface by explicitly supplying
perspective=TRUE when there are two continuous or numeric-labelled
ordered conditioning variables. Omitting perspective, or supplying
perspective=FALSE, retains the usual slice layout. Vector quantiles
and gradient plots also retain their slice layout. Surface uncertainty is
calibrated over the complete displayed grid for that one tau.
Both the base renderer and renderer="rgl", view="fixed" support
level surfaces and their interval meshes. Returned evaluation rows retain
the trained predictor names and ordered-factor support; numeric axis
coordinates are used only for drawing. The data overlay can be disabled
with data.overlay=FALSE.
Local-polynomial conditional-response factors use local response moments as a working covariance approximation conditional on the accepted design and response map. At fixed nonshrinking bandwidths they need not equal the full empirical-caseweight derivative, which also perturbs the design map. Their leading interpretation requires smooth shrinking neighborhoods and nondegenerate local response variation.
Asymptotic plot(..., band="simultaneous") calibrates a joint
Gaussian maximum over the retained grid within one panel and one
tau; calibration is not joint across quantiles or panels. Levels
use inverse-CDF influence rows at their own fitted quantiles. Continuous
gradients use the selected CDF-derivative influence and the existing
leading plug-in standard error. Positive-degree categorical effects use
paired own-quantile endpoint influences with shared observation columns.
Local-constant and degree-zero categorical effects retain their different
public target, the same-root CDF contrast divided by the selected density:
their joint bands include density and root-evaluation terms in a full local
delta calculation, with separately computed joint-band standard errors.
band="all" retains existing pointwise and Bonferroni widths even
when the simultaneous calculation uses this different scale.
Local-constant and local-polynomial routes retain the fitted kernel, bandwidth type, degree and basis. Quantile inversion still requires a second-order response kernel. A valid joint grid requires finite positive slopes, interior unclamped quantiles, negligible inversion residuals, identifiable local influence and regular kernel/support geometry. The nearest-neighbor same-root calculation holds the realized neighbor counts and geometry fixed in its empirical-mass approximation, while retaining movement of a generalized-neighbor query radius when differentiating in the response coordinate. It does not claim an unconditional law for estimating the counts or radii.
These are selected-smoothing variability approximations, not smoothing-bias
corrections or continuum confidence bands. An asymptotic coverage
interpretation additionally requires independent observations, consistent
local covariance and marginal scales, negligible smoothing/ridge bias and
non-dominating influence rows. The continuous-gradient leading
approximation requires shrinking explanatory bandwidth , with
, and sufficient local derivative sample
size; fixed nonshrinking smoothing retains a working approximation.
A growing or data-dependent grid needs a corresponding uniform
linearization and Gaussian-maximum approximation. Unsupported or
nonregular grids receive a specific unavailable-band notice.
gaussian.draws controls simulation precision and
random.seed restores the caller's RNG state.
If gradients=TRUE, npqreg also computes gradients of
the conditional quantile with respect to the conditioning variables
for which gradients are defined. Differentiating
gives
where is the derivative of the same selected conditional
distribution estimator with respect to . For regtype="lc",
this uses the local-constant conditional-gradient machinery; for
regtype="ll" it uses the canonical local-polynomial degree-one
route; and for regtype="lp" it uses the selected or supplied
degree vector. The corresponding first-order gradient standard errors
are computed componentwise as
This is a plug-in estimate of the population implicit-CDF identity, using the selected density in the denominator. It is not in general the exact derivative of the fitted finite-smoothing quantile curve. In particular, bounded and beta response kernels use observation-centred CDFs and target-centred densities, so numerical differentiation of the fitted quantiles need not reproduce the reported plug-in gradients. The same selected-density convention is used for the delta-method standard errors.
For categorical conditioning variables in positive-degree local-polynomial
fits (including local-linear fits), first-difference standard errors retain
the paired covariance between the two category endpoints. Each endpoint uses
its own fitted quantile and positive conditional-density slope in the
implicit-CDF calculation. The selected basis, smoothing parameters and
realized neighbour radii are held fixed. This requested-only calculation
supports fixed, generalized nearest-neighbour and adaptive nearest-neighbour
bandwidths; a nonpositive density slope or nonsmooth/nonfinite influence
produces NA uncertainty with a notice.
For continuous conditioning variables, these gradient standard errors are
componentwise leading asymptotic approximations. They propagate the
conditional CDF-gradient uncertainty but do not jointly propagate
fluctuations of the density denominator and estimated quantile location.
Their use requires appropriate smoothness, positive-density and relative
bandwidth-rate conditions. They are not a full finite-smoothing covariance
or a joint covariance across coordinates or tau values.
In a heterogeneous fitted local-polynomial degree vector, a degree-zero
coordinate has no available first-derivative estimate and is returned as
NA; the established all-degree-zero compatibility route is unchanged.
Its plot
panel remains present but empty when another derivative or categorical
first-difference effect is available; a request with no available component
is rejected.
When npqreg is called without an explicit bws object, it
first computes conditional distribution bandwidths using
npcdistbw and stores them in the returned object's
bws component. If a scalar tau was used initially and
additional quantiles are later desired as fitted objects, reuse those
selected bandwidths directly, for example
npqreg(bws = fit$bws, tau = c(0.25, 0.5, 0.75)). If the goal
is only to inspect additional quantiles graphically, use
plot(fit, tau = c(0.25, 0.5, 0.75)); this reuses the stored
bandwidths and recomputes only the one-dimensional quantile extraction
step for the requested tau values. Vector-tau plots are
overlaid and include a legend; use legend=FALSE,
legend=NULL, or a legend=list(...) control to suppress
or customize it.
The predict method follows the usual S3
newdata convention. For formula fits, supply a data frame of
evaluation covariates via predict(fit, newdata=...). For
non-formula fits, newdata is translated to the native
evaluator argument exdat when exdat is not supplied.
The native exdat argument remains available for advanced
workflows, contains already transformed predictor coordinates for formula
fits, and takes precedence if both newdata and
exdat are supplied. If tau is omitted in
predict, the fitted object's stored tau value is used.
npqreg returns a qregression object. The generic
functions fitted (or quantile),
se, predict, and gradients
extract stored estimated values, asymptotic standard errors, and
gradients, or compute predictions from the retained bandwidth object.
predict uses the object's stored tau
value by default; supply tau= to override it. Furthermore, the functions
summary and plot support objects of this
type. The returned object has the following components:
eval |
evaluation points |
quantile |
estimation of the quantile regression function
(conditional quantile) at the evaluation points. If |
quanterr |
asymptotic standard errors of the quantile
regression estimates, obtained from the conditional distribution
standard error and the estimated conditional density at the fitted
quantile. If |
quantgrad |
gradients of the conditional quantile with respect
to the conditioning variables at each evaluation point, when
|
quantgerr |
asymptotic standard errors for gradients, when
|
se |
whether asymptotic uncertainty was requested |
tau |
the quantile probability or probabilities computed |
fit.controls |
resolved |
The conditional quantile target is the generalized inverse
of the conditional
distribution. The standard errors and gradients described above are
first-order delta-method quantities evaluated using the same selected
conditional CDF, conditional density, bandwidths, kernels, and
local-polynomial degree inherited from the supplied
npcdistbw object.
For book-length derivations, see Li and Racine (2007), Chapter 6 Conditional CDF and Quantile Estimation, especially Sections 6.3-6.5, and Racine (2019), Chapter 4 Conditional Probability Density and Cumulative Distribution Functions. The quasi-inverse terminology follows Nelsen (2006).
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Hall, P. and J.S. Racine and Q. Li (2004), “Cross-validation and the estimation of conditional probability densities,” Journal of the American Statistical Association, 99, 1015-1026.
Koenker, R. W. and G.W. Bassett (1978), “Regression quantiles,” Econometrica, 46, 33-50.
Koenker, R. (2005), Quantile Regression, Econometric Society Monograph Series, Cambridge University Press.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2008), “Nonparametric estimation of conditional CDF and quantile functions with mixed categorical and continuous data,” Journal of Business and Economic Statistics, 26, 423-434.
Li, Q. and J. Lin and J.S. Racine (2013), “Optimal Bandwidth Selection for Nonparametric Conditional Distribution and Quantile Functions”, Journal of Business and Economic Statistics, 31, 57-65.
Nelsen, R.B. (2006), An Introduction to Copulas, Second Edition, Springer.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np, quantreg
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we compute a # bivariate nonparametric quantile regression estimate for Giovanni # Baiocchi's Italian income panel (see Italy for details) data("Italy") with(Italy, { # Compute conditional distribution bandwidths and extract three # conditional quantiles using the same selected bandwidths. model.q <- npqreg(gdp~ordered(year), tau=c(0.25, 0.50, 0.75)) # Plot the overlaid quantiles. plot(model.q) # If a scalar tau was used first, additional quantiles can reuse the # selected bandwidths without recomputing cross-validation. Use npqreg() # when the additional fitted values are needed as an object, or plot() # when graphical inspection is all that is desired. model.med <- npqreg(gdp~ordered(year), tau=0.50) model.q <- npqreg(bws=model.med$bws, tau=c(0.25, 0.50, 0.75)) plot(model.med, tau=c(0.25, 0.50, 0.75)) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we compute a # bivariate nonparametric quantile regression estimate for Giovanni # Baiocchi's Italian income panel (see Italy for details) data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # First, compute the likelihood cross-validation bandwidths (default). # Note - this may take a few minutes depending on the speed of your # computer... bw <- npcdistbw(xdat=ordered(year), ydat=gdp) # Note - numerical search for computing the quantiles will take a # minute or so... model.q <- npqreg(bws=bw, tau=c(0.25, 0.50, 0.75)) plot(model.q) }) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we compute a # bivariate nonparametric quantile regression estimate for Giovanni # Baiocchi's Italian income panel (see Italy for details) data("Italy") with(Italy, { # Compute conditional distribution bandwidths and extract three # conditional quantiles using the same selected bandwidths. model.q <- npqreg(gdp~ordered(year), tau=c(0.25, 0.50, 0.75)) # Plot the overlaid quantiles. plot(model.q) # If a scalar tau was used first, additional quantiles can reuse the # selected bandwidths without recomputing cross-validation. Use npqreg() # when the additional fitted values are needed as an object, or plot() # when graphical inspection is all that is desired. model.med <- npqreg(gdp~ordered(year), tau=0.50) model.q <- npqreg(bws=model.med$bws, tau=c(0.25, 0.50, 0.75)) plot(model.med, tau=c(0.25, 0.50, 0.75)) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we compute a # bivariate nonparametric quantile regression estimate for Giovanni # Baiocchi's Italian income panel (see Italy for details) data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # First, compute the likelihood cross-validation bandwidths (default). # Note - this may take a few minutes depending on the speed of your # computer... bw <- npcdistbw(xdat=ordered(year), ydat=gdp) # Note - numerical search for computing the quantiles will take a # minute or so... model.q <- npqreg(bws=bw, tau=c(0.25, 0.50, 0.75)) plot(model.q) }) ## End(Not run)
npquantile computes smooth quantiles from a univariate
unconditional kernel cumulative distribution estimate given data and,
optionally, a bandwidth specification i.e. a dbandwidth object
using the bandwidth selection method of Li, Li and Racine (2017).
npquantile(x = NULL, tau = c(0.01,0.05,0.25,0.50,0.75,0.95,0.99), num.eval = 10000, bws = NULL, f = 1, ...)npquantile(x = NULL, tau = c(0.01,0.05,0.25,0.50,0.75,0.95,0.99), num.eval = 10000, bws = NULL, f = 1, ...)
These arguments identify the distribution object, data, and bandwidth controls used for quantile extraction.
bws |
an optional |
x |
a univariate vector of type |
These arguments control the target quantile level, evaluation size, and distribution interpolation.
f |
an optional argument fed to |
num.eval |
an optional integer specifying the length of the grid on which the
quasi-inverse is computed. Defaults to |
tau |
an optional vector containing the probabilities for quantile(s) to
be estimated (must contain numbers in |
Further arguments are passed to bandwidth or distribution routines as needed.
... |
additional arguments supplied to specify the bandwidth type, kernel
types, bandwidth selection methods, and so on. See
|
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
Typical usage is
x <- rchisq(100,df=10)
npquantile(x)
The quantile function is defined to be the
left-continuous inverse of the distribution function ,
i.e. .
A traditional estimator of is the th sample
quantile. However, these estimates suffer from lack of efficiency
arising from variability of individual order statistics; see Sheather
and Marron (1990) and Hyndman and Fan (1996) for methods that
interpolate/smooth the order statistics, each of which discussed in
the latter can be invoked through quantile via
type=j, j=1,...,9.
The function npquantile implements a method for estimating
smooth quantiles based on the quasi-inverse of a npudist
object where is replaced with its kernel estimator and
bandwidth selection is that appropriate for such objects; see
Definition 2.3.6, page 21, Nelsen 2006 for a definition of the
quasi-inverse of .
For construction of the quasi-inverse we create a grid of evaluation
points based on the function extendrange along with the
sample quantiles themselves computed from invocation of
quantile. The coarseness of the grid defined by
extendrange (which has been passed the option
f=1) is controlled by num.eval.
Note that for any value of less/greater than the
smallest/largest value of computed for the evaluation data
(i.e. that outlined in the paragraph above), the quantile returned for
such values is that associated with the smallest/largest value of
, respectively.
npquantile returns a vector of quantiles corresponding
to tau.
Cross-validated bandwidth selection is used by default
(npudistbw). For large datasets this can be
computationally demanding. In such cases one might instead consider a
rule-of-thumb bandwidth (bwmethod="normal-reference") or bounded
kernels such as ckertype="epanechnikov". The default
options(np.tree="auto") uses kd-trees for eligible bounded-kernel
continuous routes; options(np.tree=TRUE) remains available to force
kd-tree use explicitly.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Cheng, M.-Y. and Sun, S. (2006), “Bandwidth selection for kernel quantile estimation,” Journal of the Chinese Statistical Association, 44, 271-295.
Hyndman, R.J. and Fan, Y. (1996), “Sample quantiles in statistical packages,” American Statistician, 50, 361-365.
Li, Q. and J.S. Racine (2017), “Smooth Unconditional Quantile Estimation,” Manuscript.
Li, C. and H. Li and J.S. Racine (2017), “Cross-Validated Mixed Datatype Bandwidth Selection for Nonparametric Cumulative Distribution/Survivor Functions,” Econometric Reviews, 36, 970-987.
Nelsen, R.B. (2006), An Introduction to Copulas, Second Edition, Springer-Verlag.
Sheather, S. and J.S. Marron (1990), “Kernel quantile estimators,” Journal of the American Statistical Association, Vol. 85, No. 410, 410-416.
Yang, S.-S. (1985), “A Smooth Nonparametric Estimator of a Quantile Function,” Journal of the American Statistical Association, 80, 1004-1011.
quantile for various types of sample quantiles;
ecdf for empirical distributions of which
quantile is an inverse; boxplot.stats and
fivenum for computing other versions of quartiles;
qlogspline for logspline density quantiles;
qkde for alternative kernel quantiles, etc.
## Not run: ## Simulate data from a chi-square distribution df <- 50 x <- rchisq(100,df=df) ## Vector of quantiles desired tau <- c(0.01,0.05,0.25,0.50,0.75,0.95,0.99) ## Compute kernel smoothed sample quantiles npquantile(x,tau) ## Compute sample quantiles using the default method in R (Type 7) quantile(x,tau) ## True quantiles based on known distribution qchisq(tau,df=df) ## End(Not run)## Not run: ## Simulate data from a chi-square distribution df <- 50 x <- rchisq(100,df=df) ## Vector of quantiles desired tau <- c(0.01,0.05,0.25,0.50,0.75,0.95,0.99) ## Compute kernel smoothed sample quantiles npquantile(x,tau) ## Compute sample quantiles using the default method in R (Type 7) quantile(x,tau) ## True quantiles based on known distribution qchisq(tau,df=df) ## End(Not run)
npreg computes a kernel regression estimate of a one
(1) dimensional dependent variable on -variate explanatory
data, given a set of evaluation points, training points (consisting of
explanatory data and dependent data), and a bandwidth specification
using the method of Racine and Li (2004) and Li and Racine (2004). A
bandwidth specification can be a rbandwidth object, or a
bandwidth vector, bandwidth type and kernel type.
npreg(bws, ...) ## S3 method for class 'formula' npreg(bws, data = NULL, newdata = NULL, y.eval = FALSE, se = FALSE, ...) ## Default S3 method: npreg(bws, txdat, tydat, nomad = FALSE, se = FALSE, ...) ## S3 method for class 'rbandwidth' npreg(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), exdat, eydat, gradient.order = 1L, gradients = FALSE, residuals = FALSE, se = FALSE, ...)npreg(bws, ...) ## S3 method for class 'formula' npreg(bws, data = NULL, newdata = NULL, y.eval = FALSE, se = FALSE, ...) ## Default S3 method: npreg(bws, txdat, tydat, nomad = FALSE, se = FALSE, ...) ## S3 method for class 'rbandwidth' npreg(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), exdat, eydat, gradient.order = 1L, gradients = FALSE, residuals = FALSE, se = FALSE, ...)
These arguments identify the bandwidth specification, formula/data interface, and training data.
bws |
a bandwidth specification. This can be set as a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
txdat |
a |
tydat |
a one (1) dimensional numeric or integer vector of dependent data, each
element |
This argument controls the recommended automatic local-polynomial NOMAD route, which jointly selects continuous polynomial degree and bandwidths when these are computed inside npreg.
nomad |
logical shortcut passed through to |
These arguments control where the regression is evaluated and which fitted quantities are returned.
se |
a logical value indicating whether the residual-normalized sandwich
standard errors described below are computed and retained.
Defaults to |
exdat |
a |
eydat |
a one (1) dimensional numeric or integer vector of the true values
of the dependent variable. Optional, and used only to calculate the
true errors. When evaluation predictors are supplied without evaluation
outcomes, goodness-of-fit scores (including |
gradient.order |
for |
gradients |
a logical value indicating that you want gradients computed and
returned in the resulting |
newdata |
An optional data frame in which to look for evaluation data. If omitted, the training data are used. |
residuals |
a logical value indicating that you want residuals computed and
returned in the resulting |
y.eval |
If |
Further arguments are passed to npregbw when bandwidths are computed internally, or used to interpret a numeric bws vector.
... |
additional arguments supplied to |
With generalized nearest-neighbor bandwidths, query identity matters when
selecting a radius: a training observation excludes its own occurrence,
whereas explicit evaluation data remain external queries even if their
values equal training observations. Consequently,
predict(fit, newdata = training.data) can differ from
fitted(fit). This does not omit the training contribution from the
fitted estimator. See np.kernels for the radius convention.
With a formula-derived bandwidth object, supplying only tydat
replaces the evaluated response in retained-training-sample order: one row
per observation retained after the original subset and missing-value selection.
Original excluded rows are not restored; row names or equal lengths do not
imply original-data order. The effective na.action is then applied
jointly to the retained predictors and replacement response; any new omission
indices refer to this retained sample. The selected bandwidths remain fixed,
and the returned object retains the replacement sample for subsequent refits.
Use data for full formula-data replacement, not together with a partial
response replacement. Explicit native training arguments retain their separate
positional contract.
For native (non-formula) objects, named newdata columns are matched
to the retained variable names and reordered as needed. Extra columns are
ignored; missing, duplicate or ambiguous names are errors. An unnamed
matrix or vector remains positional for a single evaluation role.
Explicit native evaluation arguments retain their positional contract and
take precedence over newdata.
For a native bandwidth object, newdata supplies exdat;
explicitly supplied native evaluation arguments take precedence. This
evaluates at the requested rows without repeating bandwidth selection.
Documentation guide: see npregbw for bandwidth
selection and search controls, np.kernels for kernels,
np.options for global options, and plot,
plot.np for plotting options.
When bws is omitted, the formula and default methods call
npregbw first and pass bandwidth-selection arguments
from ... to that call. When bws is already an
rbandwidth object, npreg estimates with the stored
bandwidth metadata in that object.
Argument groups for bandwidth selection are documented on
npregbw. The most common workflow is to choose data and
bandwidth inputs first, then bandwidth criterion and representation,
then kernel/support controls, and finally local-polynomial/NOMAD
controls when using polynomial-adaptive fits.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
Typical usages are (see below for a complete list of options and also the examples at the end of this help file)
Usage 1: first compute the bandwidth object via npregbw and then
compute the conditional mean:
bw <- npregbw(y~x)
ghat <- npreg(bw)
Usage 2: alternatively, compute the bandwidth object indirectly:
ghat <- npreg(y~x)
Usage 3: modify the default kernel and order:
ghat <- npreg(y~x, ckertype="epanechnikov", ckerorder=4)
Usage 4: use the data frame interface rather than the formula
interface:
ghat <- npreg(tydat=y, txdat=x, ckertype="epanechnikov", ckerorder=4)
npreg implements a variety of methods for regression on
multivariate (-variate) data, the types of which are possibly
continuous and/or discrete (unordered, ordered). The approach is
based on Li and Racine (2003) who employ ‘generalized product kernels’
that admit a mix of continuous and discrete data types.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating the
density at the point . Generalized nearest-neighbor bandwidths change
with the point at which the density is estimated, . Fixed bandwidths
are constant over the support of .
Data contained in the data frame txdat may be a mix of
continuous (default), unordered discrete (to be specified in the data
frame txdat using factor), and ordered discrete
(to be specified in the data frame txdat using
ordered). Data can be entered in an arbitrary order and
data types will be detected automatically by the routine (see
np for details).
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth order Gaussian and Epanechnikov kernels, and the uniform kernel. Beta associated kernels of orders 2, 4, 6, and 8 are also available for local-constant and local-polynomial regression. Unordered discrete data types use a variation on Aitchison and Aitken's (1976) kernel, while ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
For ckertype="beta", suppose continuous predictor has
declared finite support , width
, public metric bandwidth , evaluation coordinate
, and observation . Define
The local-constant product weight is
and the fitted conditional mean is the Nadaraya–Watson ratio
This uses Chen's evaluation-centred beta associated-kernel contribution
inside the established np local-constant ratio. It should not be
confused with the Gasser–Muller beta regression smoother studied by Chen
(2000). The support scale is already present in each contribution, and the
implementation applies neither the legacy factor nor the generic
bounded-kernel normalizer. Although that normalizer cancels from ordinary
local-constant numerator/denominator ratios, the beta kernel is not merely
such a correction: its shape parameters change with the evaluation point.
At orders 4, 6, and 8, each displayed order-2 coordinate factor is replaced
by the signed Igarashi–Kakizawa multiscale combination documented in
np.kernels. The resulting product weights and denominator may
be signed; no absolute-value, order-2 substitution, or positivity repair is
applied.
Products and ratios are evaluated in the log domain, so representable beta
regression results are retained even when every unscaled product would
underflow to zero. In the local-constant case,
. The reported standard error uses
the residual-normalized sandwich formula below, also for beta kernels;
it is not a local residual-variance estimate multiplied by an
effective-sample factor.
The beta regression route requires ckerorder in
c(2,4,6,8) and finite fixed or sample-range bounds for each continuous
predictor. It supports local-constant, local-linear and local-polynomial
fits, including mixed continuous and categorical predictors. Local-constant
first derivatives requested with gradients=TRUE are analytic C
implementations; their standard errors use the derivative of the normalized
weights. At exact support endpoints,
normalized numerator/denominator jumps are cancelled first. A genuine
estimator jump is returned as a signed infinity with gerr=NA; an
indeterminate numerical cancellation is returned as NA with a
warning. This extended-real gradient is retained in fitted and plot-data
objects. Plot methods omit the non-finite coordinate only from their
temporary drawing geometry, so an endpoint singularity breaks the plotted
line without changing the returned estimate. Manual and
cross-validated bandwidth objects support fixed, generalized-NN, and
adaptive-NN modes. An evaluation point
with no supported observation weight also produces an explicit error.
Ordinary regression standard errors use a residual-normalized sandwich
for the actual fitted linear map, conditional on the selected bandwidths,
polynomial specification and realized predictor geometry. Let
map training responses to their fitted values, let , and
define
For , the normalized training residual is
. This is the pre-smoothing residual normalization
in Ruppert, Wand, Holst, and Hössjer
(1997, Section 1.1, equation (3)),
not their separate variance-function smoothing procedure. If
is the influence of response on the fitted mean
at , the reported standard error is
A derivative uses its corresponding influence row. A categorical finite difference uses the difference between the two endpoint influence rows, retaining their covariance. Its estimate and error use the same paired influence calculation rather than subtracting nearly equal fitted values. Requesting or omitting standard errors does not change the computation of a requested categorical effect.
For generalized nearest-neighbor bandwidths, categorical effects at fitted training rows retain that row's training identity when selecting the radius for both endpoints, for all regression types, polynomial degrees and bases. The identity is excluded only from radius selection, not from the fitted response weights. Explicit evaluation data use external-query radii, even when their coordinates equal training observations. Consequently fitted-row and explicitly evaluated effects can differ under this bandwidth type.
The training smoother and influence rows use the actual fitted basis
and accepted regularized solve where needed. The residual-row norm is
not generally ; that identity requires a symmetric,
idempotent projection. Nor is necessarily at most one.
No additional degrees-of-freedom multiplier or positive variance floor
is applied. The corresponding influence representation is used without
retaining a full training-by-training matrix.
Treating the smoother as fixed, under independent homoskedastic errors
and a mean reproduced by that smoother,
. The normalization corrects fitted
residual noise contraction in that setting, not smoothing bias.
With a general mean, squared residual bias also contributes.
Under heteroskedasticity, mixes donor variances and need
not be unbiased for the variance of observation . Finite-sample
calibration under arbitrary bias, heteroskedasticity or model selection
is not guaranteed.
A zero residual-row norm leaves no residual information for that donor.
Requested errors depending on such unidentified information are
NA, with a warning; finite point estimates remain available.
A separately certified zero influence does not require that donor's
variance. Small positive residual norms are not replaced by zero or
by a numerical variance floor.
This convention applies to fixed, generalized-NN and adaptive-NN
bandwidths and beta kernels on supported regression routes.
External evaluation errors use the training smoother's normalized
residuals, not residuals centred on each external evaluation mean.
Bandwidth- and degree-selection uncertainty is not incorporated.
se(), derivative-error accessors, prediction standard errors and
asymptotic plot intervals consume the corresponding retained errors.
Pivotal npsigtest statistics use these gradient
errors, recomputed from each bootstrap response when bootstrapping.
Local-linear and local-polynomial moment solves use numerical ridging when needed, motivated by Seifert and Gasser (2000). The package uses bounded implementation-specific ridge policies, not that paper's complete data-adaptive ridge selector. Ridging stabilizes the fit; it is distinct from the residual normalization above, which uses the actual accepted smoother, including any ridge adjustment. A local system with fewer nonzero-weight donor rows than basis coefficients is structurally rank deficient and uses this same ridge policy for fitting and related hat operators. Bootstrap multiplicities do not create additional independent donor rows. This check does not assert full rank when the donor count reaches the basis dimension.
When bandwidths are obtained with regtype="lp", C-level
npreg supports heterogeneous continuous polynomial degrees via
degree. The basis selector currently supports
basis="glp", "additive", and "tensor".
For continuous predictors with degree vector
, additive basis size is
, tensor basis size is
, and GLP uses admissible
multi-indices with
and
plus
an intercept. Thus, for , GLP contains
; the additive
basis omits , while the tensor basis additionally
contains .
The optional flag bernstein.basis controls basis construction:
FALSE (default) uses raw local-polynomial powers. These can be
numerically unstable, particularly above degree one or when predictor
offsets are large relative to their spread. The option
bernstein.basis=TRUE is provided to improve numerical conditioning;
it does not remedy genuine collinearity. Centring/scaling continuous
predictors is another explicit user choice. Existing conditioning warnings
and errors assess the selected basis; numerical rank deficiency need not
imply genuinely redundant predictors. No automatic basis switch is made.
For
basis="glp", the historical selector TRUE uses a
degree-graded, orthonormal shifted-Legendre representation. On the unit-scaled support
, its order- factor is
, where
is a Legendre polynomial. This is an exact
degree- linear combination of Bernstein polynomials and, because
the GLP multi-index set is downward closed, spans exactly the same
heterogeneous polynomial space as the raw representation. It is evaluated
by a deterministic Legendre recurrence, not by sample-dependent
Gram–Schmidt or QR orthogonalization. Additive and
tensor bases retain their fixed-coordinate-degree Bernstein
representation. The
homogeneous degree-0 and degree-1 cases remain
equivalent to lc and ll, respectively. For continuous
predictors, gradients=TRUE returns the derivative order(s)
requested by gradient.order; the associated gerr
entries are standard errors for those same derivative orders. Both
raw and shifted-Legendre representations report fitted values and derivatives
on the original response/predictor scale. In mixed-data GLP settings,
unordered and ordered predictors contribute first-order
effects/contrasts rather than higher-order derivatives.
When npregbw(..., regtype="lp") is used with
degree.select="manual", the degree vector remains fixed user
input. When degree.select != "manual", npregbw can
jointly select polynomial degree and bandwidth using either the
cached cell-search backend or the direct
search.engine="nomad"/"nomad+powell" route described in
npregbw; the latter follows Hall and Racine (2015). For
practitioners who want that recommended route without spelling out all
LP tuning arguments, npreg(..., nomad=TRUE) and
npregbw(..., nomad=TRUE) expand missing settings to the same
documented automatic-LP NOMAD preset. Explicit incompatible settings
fail fast rather than being silently rewritten. The direct NOMAD
backend is provided by the suggested package crs, so install
crs before using search.engine="nomad",
"nomad+powell", or nomad=TRUE. For
bernstein.basis=TRUE, evaluation points for continuous predictors
must lie within training support; use bernstein.basis=FALSE for
extrapolation. For regtype="ll" and regtype="lp", the
training continuous design is checked for rank deficiency and extreme
condition number before estimation proceeds.
The use of compactly supported kernels or the occurrence of small bandwidths can lead to numerical problems for the local linear estimator when computing the locally weighted least squares solution. To overcome this problem we rely on a form or ‘ridging’ proposed by Cheng, Hall, and Titterington (1997), modified so that we solve the problem pointwise rather than globally (i.e. only when it is needed).
npreg returns a npregression object.
The generic
functions fitted, residuals,
se, predict, and
gradients, extract (or generate) estimated values,
residuals, asymptotic standard
errors on estimates, predictions, and gradients, respectively, from
the returned object. Furthermore, the functions summary
and plot support objects of this type. The returned object
has the following components:
With se.fit=TRUE, predict() returns fit,
se.fit, df, and residual.scale. The last field
uses training MSE in its historical units, not its square root or an
evaluation MSE. It reuses a known training fit's MSE without an additional
fit. It is NA when training MSE is unavailable, including an object
created at external evaluation points or scored against explicit
eydat, and external predictions with explicit training-data or
model-frame overrides. A prediction evaluated on replacement training data
can use that new training fit's MSE. Evaluation outcomes do not substitute
for training residual information.
eval |
evaluation points |
mean |
estimates of the regression function (conditional mean) at the
evaluation points. An evaluation row whose required kernel normalization is
exactly zero or non-finite is returned as |
merr |
standard errors of the regression function estimates, or
|
grad |
estimates of the gradients at each evaluation point. Undefined
normalization rows are returned as |
gerr |
standard errors of the gradient estimates, or |
resid |
if |
R2 |
coefficient of determination (Doksum and Samarov (1995)) |
MSE |
mean squared error |
MAE |
mean absolute error |
MAPE |
mean absolute percentage error |
CORR |
absolute value of Pearson's correlation coefficient |
SIGN |
fraction of observations where fitted and observed values agree in sign |
The regression target is the conditional mean
. Local-constant estimation can be written
schematically as , where the weights
are normalized generalized product-kernel weights over the continuous,
unordered, and ordered components of . Local-polynomial
regression replaces this scalar weighted average by a weighted least
squares fit in powers of the original continuous
coordinates, with kernel weights centered at . If
denotes that local weighted fit, the
reported level and derivative are respectively
and
.
For the downward-closed GLP space this uncentered representation is
numerically equivalent, up to floating-point solution paths, to fitting
powers of and reading the corresponding intercept and
derivative coefficients.
For book-length derivations, see Li and Racine (2007), Chapter 2 Regression, especially Sections 2.1, 2.2, 2.4, and 2.5, and Chapter 4 Kernel Estimation with Mixed Data, especially Sections 4.2 and 4.4. The later workflow treatment is Racine (2019), Chapter 6 Conditional Mean Function Estimation, including the local polynomial and mixed-data marginal-effect discussion.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available. With explicit replacement
training data, an explicit na.action overrides the retained policy,
including NULL; any incomplete rows subsequently excluded by native
fitting are recorded in the effective training sample. User formula and
custom-function environments remain available and can retain unrelated
caller objects in serialized files. See npregbw for storage
and missing-value policy details.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Cheng, M.-Y. and P. Hall and D.M. Titterington (1997), “On the shrinkage of local linear curve estimators,” Statistics and Computing, 7, 11-17.
Chen, S.X. (1999), “Beta kernel estimators for density functions,” Computational Statistics and Data Analysis, 31, 131-145.
Chen, S.X. (2000), “Beta kernel smoothers for regression curves,” Statistica Sinica, 10, 73-91.
Igarashi, G. and Kakizawa, Y. (2020), “Higher-order bias corrections for asymmetric kernel density estimators,” Journal of Nonparametric Statistics, 32(3), 716–752. doi:10.1080/10485252.2020.1770754.
Cohen, A. and G. Migliorati (2018), “Multivariate approximation in downward closed polynomial spaces,” in R. Cools and D. Nuyens (eds.), Contemporary Computational Mathematics, Springer, 233-282.
Dung, D. and T. Ullrich (2011), “Whitney type inequalities for local anisotropic polynomial approximation,” Journal of Approximation Theory, 163, 1590-1605.
Fan, J. and I. Gijbels (1996), Local Polynomial Modelling and Its Applications, Chapman and Hall.
Doksum, K. and A. Samarov (1995), “Nonparametric estimation of global functionals and a measure of the explanatory power of covariates in regression,” The Annals of Statistics, 23 1443-1473.
Hall, P. and Q. Li and J.S. Racine (2007), “Nonparametric estimation of regression functions in the presence of irrelevant regressors,” The Review of Economics and Statistics, 89, 784-789.
Hall, P. and J.S. Racine (2015), “Infinite Order Cross-Validated Local Polynomial Regression,” Journal of Econometrics, 185, 510-525.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2004), “Cross-validated local linear nonparametric regression,” Statistica Sinica, 14, 485-512.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Racine, J.S. and Q. Li (2004), “Nonparametric estimation of regression functions with both categorical and continuous data,” Journal of Econometrics, 119, 99-130.
Ruppert, D. and M.P. Wand (1994), “Multivariate locally weighted least squares regression,” The Annals of Statistics, 22, 1346-1370.
Ruppert, D., M.P. Wand, U. Holst, and O. Hössjer (1997), “Local Polynomial Variance-Function Estimation,” Technometrics, 39(3), 262-273. doi:10.1080/00401706.1997.10485117.
Seifert, B. and T. Gasser (2000), “Data Adaptive Ridging in Local Polynomial Regression,” Journal of Computational and Graphical Statistics, 9(2), 338-360. doi:10.1080/10618600.2000.10474884.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np
loess
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we compute a # bivariate nonparametric regression estimate for Giovanni Baiocchi's # Italian income panel (see Italy for details) data("Italy") with(Italy, { # First, compute the least-squares cross-validated bandwidths for the # local constant estimator (default). bw <- npregbw(formula=gdp~ordered(year)) # Now take these bandwidths and fit the model and gradients model <- npreg(bws = bw, gradients = TRUE) summary(model) # Use plot() to visualize the regression function, add bootstrap # error bars, and overlay the data on the same plot. # Note - this may take a minute or two depending on the speed of your # computer due to bootstrapping being conducted (<ctrl>-C will # interrupt). Note - nothing will appear in the graphics window until # all computations are completed (if you use # errors="asymptotic" the figure will instantly appear). if (interactive()) plot(bw, errors="bootstrap") points(ordered(year), gdp, cex=.2, col="red") }) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we compute a # bivariate nonparametric regression estimate for Giovanni Baiocchi's # Italian income panel (see Italy for details) data("Italy") with(Italy, { # First, compute the least-squares cross-validated bandwidths for the # local constant estimator (default). bw <- npregbw(xdat=ordered(year), ydat=gdp) # Now take these bandwidths and fit the model and gradients model <- npreg(bws = bw, gradients = TRUE) summary(model) # Use plot() to visualize the regression function, add bootstrap # error bars, and overlay the data on the same plot. # Note - this may take a minute or two depending on the speed of your # computer due to bootstrapping being conducted (<ctrl>-C will # interrupt). Note - nothing will appear in the graphics window until # all computations are completed (if you use # errors="asymptotic" the figure will instantly appear). if (interactive()) plot(bw, errors="bootstrap") points(ordered(year), gdp, cex=.2, col="red") }) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 2 (INTERFACE=FORMULA): For this example, we compute a local # linear fit using the AIC_c bandwidth selection criterion. We then plot # the estimator and its gradient using asymptotic standard errors. data("cps71", package = "np") bw <- npregbw(logwage~age, regtype="ll", bwmethod="cv.aic", data = cps71) # Next, plot the regression function... if (interactive()) plot(bw, errors="asymptotic") with(cps71, points(age, logwage, cex=.2, col="red")) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, plot the derivative... if (interactive()) plot(bw, errors="asymptotic", gradient=TRUE) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 2 (INTERFACE=DATA FRAME): For this example, we compute a local # linear fit using the AIC_c bandwidth selection criterion. We then plot # the estimator and its gradient using asymptotic standard errors. data("cps71", package = "np") bw <- npregbw(xdat=cps71$age, ydat=cps71$logwage, regtype="ll", bwmethod="cv.aic") # Next, plot the regression function... if (interactive()) plot(bw, errors="asymptotic") with(cps71, points(age, logwage, cex=.2, col="red")) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, plot the derivative... if (interactive()) plot(bw, errors="asymptotic", gradient=TRUE) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 3 (INTERFACE=FORMULA): For this example, we replicate the # nonparametric regression in Maasoumi, Racine, and Stengos # (2007) (see oecdpanel for details). Note that X is multivariate # containing a mix of unordered, ordered, and continuous data types. Note # - this may take a few minutes depending on the speed of your computer. data("oecdpanel") with(oecdpanel, { bw <- npregbw(formula=growth~ factor(oecd)+ factor(year)+ initgdp+ popgro+ inv+ humancap) if (interactive()) plot(bw, errors="asymptotic") }) # EXAMPLE 3 (INTERFACE=DATA FRAME): For this example, we replicate the # nonparametric regression in Maasoumi, Racine, and Stengos # (2007) (see oecdpanel for details). Note that X is multivariate # containing a mix of unordered, ordered, and continuous data types. Note # - this may take a few minutes depending on the speed of your computer. data("oecdpanel") with(oecdpanel, { y <- growth X <- data.frame(factor(oecd), factor(year), initgdp, popgro, inv, humancap) bw <- npregbw(xdat=X, ydat=y) if (interactive()) plot(bw, errors="asymptotic") }) # EXAMPLE 4 (INTERFACE=FORMULA): Experimental data - the effect of # vitamin C on tooth growth in guinea pigs # # Description: # # The response is the length of odontoblasts (teeth) in each of 10 # guinea pigs at each of three dose levels of Vitamin C (0.5, 1, and # 2 mg) with each of two delivery methods (orange juice or ascorbic # acid). # # Usage: # # ToothGrowth # # Format: # # A data frame with 60 observations on 3 variables. # # [,1] len numeric Tooth length # [,2] supp factor Supplement type (VC or OJ). # [,3] dose numeric Dose in milligrams. library("datasets") with(ToothGrowth, { # Note - in this example, there are six cells. bw <- npregbw(formula=len~factor(supp)+ordered(dose)) # Now plot the partial regression surfaces with bootstrapped # nonparametric confidence bounds if (interactive()) plot(bw, errors="bootstrap", band="simultaneous") }) # EXAMPLE 4 (INTERFACE=DATA FRAME): Experimental data - the effect of # vitamin C on tooth growth in guinea pigs # # Description: # # The response is the length of odontoblasts (teeth) in each of 10 # guinea pigs at each of three dose levels of Vitamin C (0.5, 1, and # 2 mg) with each of two delivery methods (orange juice or ascorbic # acid). # # Usage: # # ToothGrowth # # Format: # # A data frame with 60 observations on 3 variables. # # [,1] len numeric Tooth length # [,2] supp factor Supplement type (VC or OJ). # [,3] dose numeric Dose in milligrams. library("datasets") with(ToothGrowth, { # Note - in this example, there are six cells. y <- len X <- data.frame(supp=factor(supp), dose=ordered(dose)) bw <- npregbw(X, y) # Now plot the partial regression surfaces with bootstrapped # nonparametric confidence bounds if (interactive()) plot(bw, errors="bootstrap", band="simultaneous") }) # EXAMPLE 5 (INTERFACE=FORMULA): a pretty 2-d smoothing example adapted # from the R mgcv library which was written by Simon N. Wood. set.seed(12345) # This function generates a smooth nonlinear DGP dgp.func <- function(x, z, sx=0.3, sz=0.4) { (pi**sx*sz)*(1.2*exp(-(x-0.2)^2/sx^2-(z-0.3)^2/sz^2)+ 0.8*exp(-(x-0.7)^2/sx^2-(z-0.8)^2/sz^2)) } # Generate 500 observations, compute the true DGP (i.e., no noise), # then a noisy sample n <- 500 x <- runif(n) z <- runif(n) xs <- seq(0, 1, length=30) zs <- seq(0, 1, length=30) X.eval <- data.frame(x=rep(xs, 30), z=rep(zs, rep(30, 30))) dgp <- matrix(dgp.func(X.eval$x, X.eval$z), 30, 30) y <- dgp.func(x, z)+rnorm(n)*0.1 # Prepare the screen for output... first, plot the true DGP split.screen(c(2, 1)) screen(1) persp(xs, zs, dgp, xlab="x1", ylab="x2", zlab="y", main="True DGP") # Next, compute a local linear fit and plot that bw <- npregbw(formula=y~x+z, regtype="ll", bwmethod="cv.aic") fit <- fitted(npreg(bws=bw, newdata=X.eval)) fit.mat <- matrix(fit, 30, 30) screen(2) persp(xs, zs, fit.mat, xlab="x1", ylab="x2", zlab="y", main="Local linear estimate") # EXAMPLE 5 (INTERFACE=DATA FRAME): a pretty 2-d smoothing example # adapted from the R mgcv library which was written by Simon N. Wood. set.seed(12345) # This function generates a smooth nonlinear DGP dgp.func <- function(x, z, sx=0.3, sz=0.4) { (pi**sx*sz)*(1.2*exp(-(x-0.2)^2/sx^2-(z-0.3)^2/sz^2)+ 0.8*exp(-(x-0.7)^2/sx^2-(z-0.8)^2/sz^2)) } # Generate 500 observations, compute the true DGP (i.e., no noise), # then a noisy sample n <- 500 x <- runif(n) z <- runif(n) xs <- seq(0, 1, length=30) zs <- seq(0, 1, length=30) X <- data.frame(x, z) X.eval <- data.frame(x=rep(xs, 30), z=rep(zs, rep(30, 30))) dgp <- matrix(dgp.func(X.eval$x, X.eval$z), 30, 30) y <- dgp.func(x, z)+rnorm(n)*0.1 # Prepare the screen for output... first, plot the true DGP split.screen(c(2, 1)) screen(1) persp(xs, zs, dgp, xlab="x1", ylab="x2", zlab="y", main="True DGP") # Next, compute a local linear fit and plot that bw <- npregbw(xdat=X, ydat=y, regtype="ll", bwmethod="cv.aic") fit <- fitted(npreg(exdat=X.eval, bws=bw)) fit.mat <- matrix(fit, 30, 30) screen(2) persp(xs, zs, fit.mat, xlab="x1", ylab="x2", zlab="y", main="Local linear estimate") ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we compute a # bivariate nonparametric regression estimate for Giovanni Baiocchi's # Italian income panel (see Italy for details) data("Italy") with(Italy, { # First, compute the least-squares cross-validated bandwidths for the # local constant estimator (default). bw <- npregbw(formula=gdp~ordered(year)) # Now take these bandwidths and fit the model and gradients model <- npreg(bws = bw, gradients = TRUE) summary(model) # Use plot() to visualize the regression function, add bootstrap # error bars, and overlay the data on the same plot. # Note - this may take a minute or two depending on the speed of your # computer due to bootstrapping being conducted (<ctrl>-C will # interrupt). Note - nothing will appear in the graphics window until # all computations are completed (if you use # errors="asymptotic" the figure will instantly appear). if (interactive()) plot(bw, errors="bootstrap") points(ordered(year), gdp, cex=.2, col="red") }) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we compute a # bivariate nonparametric regression estimate for Giovanni Baiocchi's # Italian income panel (see Italy for details) data("Italy") with(Italy, { # First, compute the least-squares cross-validated bandwidths for the # local constant estimator (default). bw <- npregbw(xdat=ordered(year), ydat=gdp) # Now take these bandwidths and fit the model and gradients model <- npreg(bws = bw, gradients = TRUE) summary(model) # Use plot() to visualize the regression function, add bootstrap # error bars, and overlay the data on the same plot. # Note - this may take a minute or two depending on the speed of your # computer due to bootstrapping being conducted (<ctrl>-C will # interrupt). Note - nothing will appear in the graphics window until # all computations are completed (if you use # errors="asymptotic" the figure will instantly appear). if (interactive()) plot(bw, errors="bootstrap") points(ordered(year), gdp, cex=.2, col="red") }) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 2 (INTERFACE=FORMULA): For this example, we compute a local # linear fit using the AIC_c bandwidth selection criterion. We then plot # the estimator and its gradient using asymptotic standard errors. data("cps71", package = "np") bw <- npregbw(logwage~age, regtype="ll", bwmethod="cv.aic", data = cps71) # Next, plot the regression function... if (interactive()) plot(bw, errors="asymptotic") with(cps71, points(age, logwage, cex=.2, col="red")) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, plot the derivative... if (interactive()) plot(bw, errors="asymptotic", gradient=TRUE) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 2 (INTERFACE=DATA FRAME): For this example, we compute a local # linear fit using the AIC_c bandwidth selection criterion. We then plot # the estimator and its gradient using asymptotic standard errors. data("cps71", package = "np") bw <- npregbw(xdat=cps71$age, ydat=cps71$logwage, regtype="ll", bwmethod="cv.aic") # Next, plot the regression function... if (interactive()) plot(bw, errors="asymptotic") with(cps71, points(age, logwage, cex=.2, col="red")) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, plot the derivative... if (interactive()) plot(bw, errors="asymptotic", gradient=TRUE) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # EXAMPLE 3 (INTERFACE=FORMULA): For this example, we replicate the # nonparametric regression in Maasoumi, Racine, and Stengos # (2007) (see oecdpanel for details). Note that X is multivariate # containing a mix of unordered, ordered, and continuous data types. Note # - this may take a few minutes depending on the speed of your computer. data("oecdpanel") with(oecdpanel, { bw <- npregbw(formula=growth~ factor(oecd)+ factor(year)+ initgdp+ popgro+ inv+ humancap) if (interactive()) plot(bw, errors="asymptotic") }) # EXAMPLE 3 (INTERFACE=DATA FRAME): For this example, we replicate the # nonparametric regression in Maasoumi, Racine, and Stengos # (2007) (see oecdpanel for details). Note that X is multivariate # containing a mix of unordered, ordered, and continuous data types. Note # - this may take a few minutes depending on the speed of your computer. data("oecdpanel") with(oecdpanel, { y <- growth X <- data.frame(factor(oecd), factor(year), initgdp, popgro, inv, humancap) bw <- npregbw(xdat=X, ydat=y) if (interactive()) plot(bw, errors="asymptotic") }) # EXAMPLE 4 (INTERFACE=FORMULA): Experimental data - the effect of # vitamin C on tooth growth in guinea pigs # # Description: # # The response is the length of odontoblasts (teeth) in each of 10 # guinea pigs at each of three dose levels of Vitamin C (0.5, 1, and # 2 mg) with each of two delivery methods (orange juice or ascorbic # acid). # # Usage: # # ToothGrowth # # Format: # # A data frame with 60 observations on 3 variables. # # [,1] len numeric Tooth length # [,2] supp factor Supplement type (VC or OJ). # [,3] dose numeric Dose in milligrams. library("datasets") with(ToothGrowth, { # Note - in this example, there are six cells. bw <- npregbw(formula=len~factor(supp)+ordered(dose)) # Now plot the partial regression surfaces with bootstrapped # nonparametric confidence bounds if (interactive()) plot(bw, errors="bootstrap", band="simultaneous") }) # EXAMPLE 4 (INTERFACE=DATA FRAME): Experimental data - the effect of # vitamin C on tooth growth in guinea pigs # # Description: # # The response is the length of odontoblasts (teeth) in each of 10 # guinea pigs at each of three dose levels of Vitamin C (0.5, 1, and # 2 mg) with each of two delivery methods (orange juice or ascorbic # acid). # # Usage: # # ToothGrowth # # Format: # # A data frame with 60 observations on 3 variables. # # [,1] len numeric Tooth length # [,2] supp factor Supplement type (VC or OJ). # [,3] dose numeric Dose in milligrams. library("datasets") with(ToothGrowth, { # Note - in this example, there are six cells. y <- len X <- data.frame(supp=factor(supp), dose=ordered(dose)) bw <- npregbw(X, y) # Now plot the partial regression surfaces with bootstrapped # nonparametric confidence bounds if (interactive()) plot(bw, errors="bootstrap", band="simultaneous") }) # EXAMPLE 5 (INTERFACE=FORMULA): a pretty 2-d smoothing example adapted # from the R mgcv library which was written by Simon N. Wood. set.seed(12345) # This function generates a smooth nonlinear DGP dgp.func <- function(x, z, sx=0.3, sz=0.4) { (pi**sx*sz)*(1.2*exp(-(x-0.2)^2/sx^2-(z-0.3)^2/sz^2)+ 0.8*exp(-(x-0.7)^2/sx^2-(z-0.8)^2/sz^2)) } # Generate 500 observations, compute the true DGP (i.e., no noise), # then a noisy sample n <- 500 x <- runif(n) z <- runif(n) xs <- seq(0, 1, length=30) zs <- seq(0, 1, length=30) X.eval <- data.frame(x=rep(xs, 30), z=rep(zs, rep(30, 30))) dgp <- matrix(dgp.func(X.eval$x, X.eval$z), 30, 30) y <- dgp.func(x, z)+rnorm(n)*0.1 # Prepare the screen for output... first, plot the true DGP split.screen(c(2, 1)) screen(1) persp(xs, zs, dgp, xlab="x1", ylab="x2", zlab="y", main="True DGP") # Next, compute a local linear fit and plot that bw <- npregbw(formula=y~x+z, regtype="ll", bwmethod="cv.aic") fit <- fitted(npreg(bws=bw, newdata=X.eval)) fit.mat <- matrix(fit, 30, 30) screen(2) persp(xs, zs, fit.mat, xlab="x1", ylab="x2", zlab="y", main="Local linear estimate") # EXAMPLE 5 (INTERFACE=DATA FRAME): a pretty 2-d smoothing example # adapted from the R mgcv library which was written by Simon N. Wood. set.seed(12345) # This function generates a smooth nonlinear DGP dgp.func <- function(x, z, sx=0.3, sz=0.4) { (pi**sx*sz)*(1.2*exp(-(x-0.2)^2/sx^2-(z-0.3)^2/sz^2)+ 0.8*exp(-(x-0.7)^2/sx^2-(z-0.8)^2/sz^2)) } # Generate 500 observations, compute the true DGP (i.e., no noise), # then a noisy sample n <- 500 x <- runif(n) z <- runif(n) xs <- seq(0, 1, length=30) zs <- seq(0, 1, length=30) X <- data.frame(x, z) X.eval <- data.frame(x=rep(xs, 30), z=rep(zs, rep(30, 30))) dgp <- matrix(dgp.func(X.eval$x, X.eval$z), 30, 30) y <- dgp.func(x, z)+rnorm(n)*0.1 # Prepare the screen for output... first, plot the true DGP split.screen(c(2, 1)) screen(1) persp(xs, zs, dgp, xlab="x1", ylab="x2", zlab="y", main="True DGP") # Next, compute a local linear fit and plot that bw <- npregbw(xdat=X, ydat=y, regtype="ll", bwmethod="cv.aic") fit <- fitted(npreg(exdat=X.eval, bws=bw)) fit.mat <- matrix(fit, 30, 30) screen(2) persp(xs, zs, fit.mat, xlab="x1", ylab="x2", zlab="y", main="Local linear estimate") ## End(Not run)
npregbw computes a bandwidth object for a
-variate kernel regression estimator defined over mixed
continuous and discrete (unordered, ordered) data using expected
Kullback-Leibler cross-validation, or least-squares cross validation
using the method of Racine and Li (2004) and Li and Racine (2004).
npregbw(...) ## S3 method for class 'formula' npregbw(formula, data, subset, na.action, call, ...) ## Default S3 method: npregbw(xdat = stop("invoked without data 'xdat'"), ydat = stop("invoked without data 'ydat'"), bws, bandwidth.compute = TRUE, basis, bernstein.basis, bwmethod, bwscaling, bwtype, cfac.dir, scale.factor.init, ckerbound, ckerlb, ckerorder, ckertype, ckerub, degree, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, dfac.dir, dfac.init, dfc.dir, ftol, scale.factor.init.upper, hbd.dir, hbd.init, initc.dir, initd.dir, invalid.penalty = c("baseline","dbmax"), itmax, lbc.dir, scale.factor.init.lower, lbd.dir, lbd.init, nmulti, okertype, penalty.multiplier = 10, regtype, nomad.remin = FALSE, powell.remin, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample, scale.factor.search.lower = NULL, small, tol, transform.bounds = FALSE, ukertype, ..., nomad.opts = list()) ## S3 method for class 'rbandwidth' npregbw(xdat = stop("invoked without data 'xdat'"), ydat = stop("invoked without data 'ydat'"), bws, bandwidth.compute = TRUE, cfac.dir = 2.5*(3.0-sqrt(5)), scale.factor.init = 0.5, dfac.dir = 0.25*(3.0-sqrt(5)), dfac.init = 0.375, dfc.dir = 3, ftol = 1.490116e-07, scale.factor.init.upper = 2.0, hbd.dir = 1, hbd.init = 0.9, initc.dir = 1.0, initd.dir = 1.0, invalid.penalty = c("baseline","dbmax"), itmax = 10000, lbc.dir = 0.5, scale.factor.init.lower = 0.1, lbd.dir = 0.1, lbd.init = 0.1, nmulti, penalty.multiplier = 10, powell.remin = TRUE, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample = FALSE, scale.factor.search.lower = NULL, small = 1.490116e-05, tol = 1.490116e-04, transform.bounds = FALSE, ..., nomad.opts = list())npregbw(...) ## S3 method for class 'formula' npregbw(formula, data, subset, na.action, call, ...) ## Default S3 method: npregbw(xdat = stop("invoked without data 'xdat'"), ydat = stop("invoked without data 'ydat'"), bws, bandwidth.compute = TRUE, basis, bernstein.basis, bwmethod, bwscaling, bwtype, cfac.dir, scale.factor.init, ckerbound, ckerlb, ckerorder, ckertype, ckerub, degree, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, dfac.dir, dfac.init, dfc.dir, ftol, scale.factor.init.upper, hbd.dir, hbd.init, initc.dir, initd.dir, invalid.penalty = c("baseline","dbmax"), itmax, lbc.dir, scale.factor.init.lower, lbd.dir, lbd.init, nmulti, okertype, penalty.multiplier = 10, regtype, nomad.remin = FALSE, powell.remin, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample, scale.factor.search.lower = NULL, small, tol, transform.bounds = FALSE, ukertype, ..., nomad.opts = list()) ## S3 method for class 'rbandwidth' npregbw(xdat = stop("invoked without data 'xdat'"), ydat = stop("invoked without data 'ydat'"), bws, bandwidth.compute = TRUE, cfac.dir = 2.5*(3.0-sqrt(5)), scale.factor.init = 0.5, dfac.dir = 0.25*(3.0-sqrt(5)), dfac.init = 0.375, dfc.dir = 3, ftol = 1.490116e-07, scale.factor.init.upper = 2.0, hbd.dir = 1, hbd.init = 0.9, initc.dir = 1.0, initd.dir = 1.0, invalid.penalty = c("baseline","dbmax"), itmax = 10000, lbc.dir = 0.5, scale.factor.init.lower = 0.1, lbd.dir = 0.1, lbd.init = 0.1, nmulti, penalty.multiplier = 10, powell.remin = TRUE, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample = FALSE, scale.factor.search.lower = NULL, small = 1.490116e-05, tol = 1.490116e-04, transform.bounds = FALSE, ..., nomad.opts = list())
These arguments identify the data, formula interface, and whether bandwidths are supplied or computed.
bandwidth.compute |
a logical value which specifies whether to do a numerical search for
bandwidths or not. If set to |
bws |
a bandwidth specification. This can be set as a |
call |
the original function call. This is passed internally by
|
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
formula |
a symbolic description of variables on which bandwidth selection is to be performed. The details of constructing a formula are described below. |
na.action |
a function which indicates what should happen when the data contain
|
subset |
an optional vector specifying a subset of observations to be used in the fitting process. |
xdat |
a |
ydat |
a one (1) dimensional numeric or integer vector of dependent data, each
element |
These arguments control automatic local-polynomial degree search when regtype="lp".
degree.max |
optional scalar or integer vector giving upper bounds for automatic
degree search when |
degree.max.cycles |
positive integer giving the maximum number of coordinate-search
sweeps over the continuous-predictor degree vector. Ignored for
|
degree.min |
optional scalar or integer vector giving lower bounds for automatic
degree search when |
degree.restarts |
non-negative integer giving the number of additional deterministic
restarts used by coordinate search. Ignored for
|
degree.select |
character string controlling local-polynomial degree handling when
|
degree.start |
optional starting degree vector for automatic degree search when
|
degree.verify |
logical value indicating whether a coordinate-search solution should
be exhaustively verified over the admissible degree grid after the
heuristic phase completes. Available only for
|
These arguments choose the selection criterion and the way continuous bandwidths are represented.
bwmethod |
which method to use to select bandwidths. |
bwscaling |
a logical value that when set to |
bwtype |
character string used for the continuous variable bandwidth type,
specifying the type of bandwidth to compute and return in the
|
These controls set categorical search starts and categorical direction-set initialization.
dfac.dir |
stretch factor for direction set search for Powell's algorithm for categorical variables. See Details |
dfac.init |
non-random initial values for scale factors for categorical variables for Powell's algorithm. See Details |
hbd.dir |
upper bound for direction set search for Powell's algorithm for categorical variables. See Details |
hbd.init |
upper bound for scale factors for categorical variables for Powell's algorithm. See Details |
initd.dir |
initial non-random values for direction set search for Powell's algorithm for categorical variables. See Details |
lbd.dir |
lower bound for direction set search for Powell's algorithm for categorical variables. See Details |
lbd.init |
lower bound for scale factors for categorical variables for Powell's algorithm. See Details |
scale.init.categorical.sample |
a logical value that when set
to |
These controls set Powell direction-set initialization for continuous variables.
cfac.dir |
stretch factor for direction set search for Powell's algorithm for |
dfc.dir |
chi-square degrees of freedom for direction set search for Powell's algorithm for |
initc.dir |
initial non-random values for direction set search for Powell's algorithm for |
lbc.dir |
lower bound for direction set search for Powell's algorithm for |
These controls choose and parameterize bounded support for continuous kernels.
ckerbound |
character string controlling continuous-kernel support handling.
Can be set as |
ckerlb |
numeric scalar/vector of lower bounds for continuous variables used
when |
ckerub |
numeric scalar/vector of upper bounds for continuous variables used
when |
These controls define deterministic and random continuous scale-factor starts and the lower admissibility floor for fixed-bandwidth search.
scale.factor.init |
deterministic initial scale factor for continuous fixed-bandwidth
search. Defaults to |
scale.factor.init.lower |
lower endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.init.upper |
upper endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.search.lower |
optional nonnegative scalar giving the hard lower admissibility
bound for continuous fixed-bandwidth search candidates. Defaults to
|
These controls choose continuous, unordered, and ordered kernels.
ckerorder |
numeric value specifying kernel order (one of
|
ckertype |
character string used to specify the continuous kernel type.
Can be set as |
okertype |
character string used to specify the ordered categorical kernel type.
Can be set as |
ukertype |
character string used to specify the unordered categorical kernel type.
Can be set as |
These arguments control the local-polynomial estimator, basis, and fixed degree specification.
basis |
basis selector relevant only when |
bernstein.basis |
logical flag relevant only when |
degree |
a user-supplied vector of fixed polynomial degrees for the
continuous predictors (exactly one degree per continuous predictor),
relevant only when |
regtype |
a character string specifying which type of kernel regression
estimator to use. |
These arguments control the optional NOMAD direct-search route for local-polynomial degree and bandwidth search.
nomad |
logical or character shortcut for the recommended automatic local-polynomial
NOMAD route. When |
nomad.nmulti |
non-negative integer controlling the inner
the native crs NOMAD C API multistart count used within each outer
NOMAD restart when |
nomad.opts |
optional named list of native NOMAD parameters forwarded to the
crs NOMAD C API for MADS/NOMAD-backed bandwidth searches.
|
nomad.remin |
logical flag controlling the optional second NOMAD hot start. When
|
search.engine |
character string controlling the automatic local-polynomial search
backend when |
These controls set optimizer tolerances, restart behavior, invalid-candidate penalties, and bounded search transformations.
ftol |
fractional tolerance on the value of the cross-validation function
evaluated at located minima (of order the machine precision or
perhaps slightly larger so as not to be diddled by
roundoff). Defaults to |
invalid.penalty |
a character string specifying the penalty
used when the optimizer encounters invalid bandwidths.
|
itmax |
integer number of iterations before failure in the numerical
optimization routine. Defaults to |
nmulti |
integer number of times to restart the process of finding extrema of
the cross-validation function from different (random) initial
points. Defaults to |
penalty.multiplier |
a numeric multiplier applied to the
baseline penalty when |
powell.remin |
logical flag controlling Powell restart-from-minimum behavior. For
ordinary fixed-degree Powell-style search, |
bwsolver |
bandwidth optimizer for fixed-degree searches. The default
|
small |
a small number used to bracket a minimum (it is hopeless to ask for
a bracketing interval of width less than sqrt(epsilon) times its
central value, a fractional width of only about 10-04 (single
precision) or 3x10-8 (double precision)). Defaults to |
tol |
tolerance on the position of located minima of the cross-validation
function (tol should generally be no smaller than the square root of
your machine's floating point precision). Defaults to |
transform.bounds |
a logical value that when set to |
These arguments collect remaining controls passed through S3 methods.
... |
additional arguments supplied to specify the bandwidth type, kernel types, selection methods, and so on, detailed below. |
Formula bandwidth objects retain the prepared training sample (after alignment,
subsetting and missing-value handling) and the resolved missing-value policy.
Later refits use that sample even if constructor variables are rebound.
Supplying explicit training data to the estimator replaces the training data;
evaluation via newdata does not. Retention requires storage proportional
to the sample size times the number of variables, not a pairwise weight matrix.
Older saved objects without this retained state still rely on their original
data bindings; rebuild their bandwidth object from the intended data before
changing those bindings. User-defined transformation and missing-value
functions should not rely on subsequently modified closure state. The resolved
NA policy is retained rather than re-read from later option settings. With
explicit replacement training data, an explicitly supplied na.action
overrides that policy, including NULL. Any remaining incomplete native
training rows are omitted and recorded; this does not make incomplete rows
valid estimator inputs. Character NA policies use the lookup owner of
stats::model.frame; pass a custom function object explicitly.
Retaining samples increases object size, and derived models can contain
separate retained samples in their child bandwidth objects. User formula and
custom-function environments are not generally pruned. They can retain
unrelated caller objects, so serialized file size may be much larger than
object.size() suggests. Sample ownership does not guarantee compact
serialization of arbitrary user environments.
The scale.factor.* controls are dimensionless search
controls. The package converts scale factors to bandwidths using the
estimator-specific scaling encoded in the bandwidth object, including
kernel order and the number of continuous variables relevant for the
estimator. Users should not pre-multiply these controls by sample-size
or standard-deviation factors.
scale.factor.init controls the deterministic first search
start. scale.factor.init.lower and
scale.factor.init.upper define the random multistart interval.
scale.factor.search.lower is the lower admissibility bound for
continuous fixed-bandwidth search candidates. The effective first
start is max(scale.factor.init, scale.factor.search.lower),
and the effective random-start lower endpoint is
max(scale.factor.init.lower, scale.factor.search.lower).
scale.factor.init.upper must be at least that effective lower
endpoint; the package errors rather than silently expanding the user's
interval.
When scale.factor.search.lower is NULL, an existing
bandwidth object's stored floor is inherited when available;
otherwise the package default 0.1 is used. Explicit bandwidths
supplied for storage with bandwidth.compute = FALSE are not
rewritten by the search floor.
Categorical search-start controls such as dfac.init,
lbd.init, and hbd.init have separate semantics and are
not affected by scale.factor.search.lower.
Documentation guide: see np.kernels for kernels,
np.options for global options, and
plot, plot.np for plotting options.
The bandwidth-selection argument surface is easiest to read by
decision group: data and existing bandwidth inputs;
local-polynomial/NOMAD controls when polynomial-adaptive regression
is requested; bandwidth criterion and representation; continuous
kernel and support controls beginning with cker*;
categorical kernel controls ukertype and okertype; and
numerical search initialization, tolerances, and feasibility
controls. Users who call npreg without a bandwidth
object can pass these same bandwidth-selection controls through that
function's ....
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
npregbw implements a variety of methods for choosing
bandwidths for multivariate (-variate) regression data defined
over a set of possibly continuous and/or discrete (unordered, ordered)
data. The approach is based on Li and Racine (2003) who employ
‘generalized product kernels’ that admit a mix of continuous
and discrete data types.
The cross-validation methods employ multivariate numerical search
algorithms. For fixed-degree local-constant/local-linear regression,
and for local-polynomial regression with degree.select="manual",
the bandwidth search uses multidimensional Powell direction-set
optimization.
Bandwidths can (and will) differ for each variable which is, of course, desirable.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating the
density at the point . Generalized nearest-neighbor bandwidths change
with the point at which the density is estimated, . Fixed bandwidths
are constant over the support of .
Exact ties can make the literal th continuous nearest-neighbor
radius zero. Such a bandwidth is undefined and is rejected; see
np.kernels for the precise contract and remedies.
npregbw may be invoked either with a formula-like
symbolic
description of variables on which bandwidth selection is to be
performed or through a simpler interface whereby data is passed
directly to the function via the xdat and ydat
parameters. Use of these two interfaces is mutually exclusive.
Data contained in the data frame xdat may be a mix of
continuous (default), unordered discrete (to be specified in the data
frame xdat using factor), and ordered discrete
(to be specified in the data frame xdat using
ordered). Data can be entered in an arbitrary order and
data types will be detected automatically by the routine (see
np for details).
Data for which bandwidths are to be estimated may be specified
symbolically. A typical description has the form dependent data
~ explanatory data,
where dependent data is a univariate response, and
explanatory data is a
series of variables specified by name, separated by
the separation character '+'. For example, y1 ~ x1 + x2
specifies that the bandwidths for the regression of response y1
and
nonparametric regressors x1 and x2 are to be estimated.
See below for further examples.
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth order Gaussian and Epanechnikov kernels, and the uniform kernel. Beta associated kernels of orders 2, 4, 6, and 8 are additionally available for local-constant, local-linear, and local-polynomial bandwidth objects. Unordered discrete data types use a variation on Aitchison and Aitken's (1976) kernel, while ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
The beta contract requires ckertype="beta",
ckerorder in c(2,4,6,8) and finite
ckerbound="fixed" bounds or ckerbound="range" for each
continuous predictor. Local-constant, local-linear and local-polynomial
regression support mixed continuous and categorical predictors.
Explicit bandwidth objects and automatic cv.ls/cv.aic
search support fixed, generalized-NN, and adaptive-NN modes.
Normal-reference selection is unsupported. Gradient and standard-error
support is described in npreg. See
npreg and np.kernels for the exact beta weight,
bandwidth convention, ratio estimator, and standard-error definition.
When regtype="lp" and degree.select != "manual",
npregbw can jointly determine the continuous-predictor degree
vector and bandwidth coordinates. With search.engine="cell",
the objective is profiled over the degree grid using cached
coordinate-wise or exhaustive search together with the existing
fixed-degree bandwidth optimizer. With
search.engine="nomad" or "nomad+powell", the package
instead evaluates the cross-validation criterion directly over the
joint space of fixed bandwidths and polynomial degrees using
the native crs NOMAD C API. "nomad+powell" then performs one Powell
hot start from the NOMAD solution and retains the better of the
direct NOMAD and polished solutions. This direct joint-search route
follows the polynomial-adaptive cross-validation rationale of Hall
and Racine (2015). When bernstein.basis is not explicitly
supplied, the automatic search route defaults to
bernstein.basis=TRUE for numerical stability; explicit
bernstein.basis=FALSE is honored but can be poorly conditioned
at higher degrees. NOMAD multistarts are initialized more
conservatively than the full degree search box: start 1 is the
user-supplied degree/bandwidth vector when provided and otherwise a
clipped degree-one vector, while later starts are reproducible random
draws from a reduced degree proposal box whose candidates are screened
using dim_basis(). This heuristic is used only to obtain
feasible, numerically safer, and quicker initial evaluations; it does
not restrict the admissible degree region searched by NOMAD. The
direct NOMAD backend is provided by the suggested package
crs, so install crs before using
search.engine="nomad", "nomad+powell",
nomad=TRUE, or nomad="auto".
Setting nomad=TRUE is a convenience preset for this automatic
LP route, not a generic optimizer alias. For regression it expands any
missing values to the equivalent long-form call
npregbw(...,
regtype = "lp",
search.engine = "nomad+powell",
degree.select = "coordinate",
bernstein.basis = TRUE,
degree.min = 0L,
degree.max = 10L,
degree.verify = FALSE,
bwtype = "fixed")
Compatible explicit tuning arguments are respected. Incompatible
explicit settings fail fast so the shortcut never silently changes
user-selected semantics.
The character value nomad="auto" applies the same LP
shortcut but leaves search.engine and degree.select
eligible for data-driven resolution when both were not supplied
explicitly: scalar continuous degree searches use the exhaustive
degree-grid route, while higher-dimensional degree searches keep the
NOMAD/Powell route. Explicit search.engine or
degree.select choices are honored.
When the direct NOMAD route is active, nmulti controls the
package-level outer restart count while nomad.nmulti
controls the inner native crs NOMAD API multistart count used within
each outer restart. The default nomad.nmulti=0L preserves the
current single-start inner NOMAD behavior. Advanced native NOMAD
parameters may be supplied through the explicit nomad.opts argument;
invalid or unsupported parameters are rejected by NOMAD rather than
silently ignored. Routes that evaluate R callbacks require serial
callback evaluation and reject parallel callback settings such as
NB_THREADS_PARALLEL_EVAL > 1.
The use of compactly supported kernels or the occurrence of small bandwidths during cross-validation can lead to numerical problems for the local linear estimator when computing the locally weighted least squares solution. To overcome this problem we rely on a form or ‘ridging’ proposed by Cheng, Hall, and Titterington (1997), modified so that we solve the problem pointwise rather than globally (i.e. only when it is needed).
The optimizer invoked for search is Powell's conjugate direction
method which requires the setting of (non-random) initial values and
search directions for bandwidths, and, when restarting, random values
for successive invocations. Bandwidths for numeric variables
are scaled by robust measures of spread, the sample size, and the
number of numeric variables where appropriate. Two sets of
parameters for bandwidths for numeric can be modified, those
for initial values for the parameters themselves, and those for the
directions taken (Powell's algorithm does not involve explicit
computation of the function's gradient). The default values are set by
considering search performance for a variety of difficult test cases
and simulated cases. We highly recommend restarting search a large
number of times to avoid the presence of local minima (achieved by
modifying nmulti). Further refinement for difficult cases can
be achieved by modifying these sets of parameters. However, these
parameters are intended more for the authors of the package to enable
‘tuning’ for various methods rather than for the user
themselves.
npregbw returns a rbandwidth object, with the
following components:
bw |
bandwidth(s), scale factor(s) or nearest neighbours for the
data, |
fval |
objective function value at minimum |
if bwtype is set to fixed, an object containing bandwidths
(or scale factors if bwscaling = TRUE) is returned. If it is set to
generalized_nn or adaptive_nn, then instead the th nearest
neighbors are returned for the continuous variables while the discrete
kernel bandwidths are returned for the discrete variables. Bandwidths
are stored under the component name bw, with each
element corresponding to column of input data
xdat.
Prediction follows a two-stage contract. Calling predict(bw)
on the returned bandwidth object is a convenience forwarder for
npreg(bws = bw) and returns a fitted npregression
object; it does not return a numeric vector of predictions. Call
fitted(fit), residuals(fit), or
predict(fit, newdata = ...) on that fitted object to obtain
numeric results. The canonical workflow is
bw <- npregbw(y ~ x, data = mydata)
fit <- predict(bw) # equivalent to npreg(bws = bw)
fitted(fit)
residuals(fit)
predict(fit, newdata = newdata)
The functions summary and plot also
support rbandwidth objects.
Local-polynomial search uses the numerical-ridging policies described in
npreg (Seifert and Gasser, 2000). This is solve
stabilization, not the fitted-residual uncertainty correction.
npregbw selects bandwidths and, when requested, local-polynomial
degree/search metadata for estimating the conditional mean
. For the estimator target and local-polynomial
interpretation, see npreg.
For book-length derivations, see Li and Racine (2007), Chapter 2 Regression, especially Sections 2.2, 2.4, and 2.5, and Chapter 4 Kernel Estimation with Mixed Data, especially Sections 4.2 and 4.4. The later workflow treatment is Racine (2019), Chapter 6 Conditional Mean Function Estimation.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Caution: multivariate data-driven bandwidth selection methods are, by
their nature, computationally intensive. Virtually all methods
require dropping the th observation from the data set, computing an
object, repeating this for all observations in the sample, then
averaging each of these leave-one-out estimates for a given
value of the bandwidth vector, and only then repeating this a large
number of times in order to conduct multivariate numerical
minimization/maximization. Furthermore, due to the potential for local
minima/maxima, restarting this procedure a large number of times may
often be necessary. This can be frustrating for users possessing
large datasets. For exploratory purposes, you may wish to override the
default search tolerances, say, setting ftol=.01 and tol=.01 and
conduct multistarting (the default is to restart min(2, ncol(xdat))
times) as is done for a number of examples. Once the procedure
terminates, you can restart search with default tolerances using those
bandwidths obtained from the less rigorous search (i.e., set
bws=bw on subsequent calls to this routine where bw is
the initial bandwidth object). A version of this package using the
Rmpi wrapper is under development that allows one to deploy
this software in a clustered computing environment to facilitate
computation involving large datasets.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Cheng, M.-Y. and P. Hall and D.M. Titterington (1997), “On the shrinkage of local linear curve estimators,” Statistics and Computing, 7, 11-17.
Chen, S.X. (1999), “Beta kernel estimators for density functions,” Computational Statistics and Data Analysis, 31, 131-145.
Chen, S.X. (2000), “Beta kernel smoothers for regression curves,” Statistica Sinica, 10, 73-91.
Fan, J. and I. Gijbels (1996), Local Polynomial Modelling and Its Applications, Chapman and Hall.
Hall, P. and J.S. Racine (2015), “Infinite Order Cross-Validated Local Polynomial Regression,” Journal of Econometrics, 185, 510-525.
Hall, P. and Q. Li and J.S. Racine (2007), “Nonparametric estimation of regression functions in the presence of irrelevant regressors,” The Review of Economics and Statistics, 89, 784-789.
Hurvich, C.M. and J.S. Simonoff and C.L. Tsai (1998), “Smoothing parameter selection in nonparametric regression using an improved Akaike information criterion,” Journal of the Royal Statistical Society B, 60, 271-293.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2004), “Cross-validated local linear nonparametric regression,” Statistica Sinica, 14, 485-512.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Racine, J.S. and Q. Li (2004), “Nonparametric estimation of regression functions with both categorical and continuous data,” Journal of Econometrics, 119, 99-130.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np
npreg
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we compute a # Bivariate nonparametric regression estimate for Giovanni Baiocchi's # Italian income panel (see Italy for details) data("Italy") with(Italy, { # Compute the least-squares cross-validated bandwidths for the local # constant estimator (default) bw <- npregbw(formula=gdp~ordered(year)) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Supply your own bandwidth... bw <- npregbw(formula=gdp~ordered(year), bws=c(0.75), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Treat year as continuous and supply your own scaling factor c in # c sigma n^{-1/(2p+q)} bw <- npregbw(formula=gdp~year, bws=c(1.06), bandwidth.compute=FALSE, bwscaling=TRUE) summary(bw) # Note - see also the example for npudensbw() for more extensive # multiple illustrations of how to change the kernel function, kernel # order, bandwidth type and so forth. }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we compute a # Bivariate nonparametric regression estimate for Giovanni Baiocchi's # Italian income panel (see Italy for details) data("Italy") with(Italy, { # Compute the least-squares cross-validated bandwidths for the local # constant estimator (default) bw <- npregbw(xdat=ordered(year), ydat=gdp) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Supply your own bandwidth... bw <- npregbw(xdat=ordered(year), ydat=gdp, bws=c(0.75), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Treat year as continuous and supply your own scaling factor c in # c sigma n^{-1/(2p+q)} bw <- npregbw(xdat=year, ydat=gdp, bws=c(1.06), bandwidth.compute=FALSE, bwscaling=TRUE) summary(bw) # Note - see also the example for npudensbw() for more extensive # multiple illustrations of how to change the kernel function, kernel # order, bandwidth type and so forth. }) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we compute a # Bivariate nonparametric regression estimate for Giovanni Baiocchi's # Italian income panel (see Italy for details) data("Italy") with(Italy, { # Compute the least-squares cross-validated bandwidths for the local # constant estimator (default) bw <- npregbw(formula=gdp~ordered(year)) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Supply your own bandwidth... bw <- npregbw(formula=gdp~ordered(year), bws=c(0.75), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Treat year as continuous and supply your own scaling factor c in # c sigma n^{-1/(2p+q)} bw <- npregbw(formula=gdp~year, bws=c(1.06), bandwidth.compute=FALSE, bwscaling=TRUE) summary(bw) # Note - see also the example for npudensbw() for more extensive # multiple illustrations of how to change the kernel function, kernel # order, bandwidth type and so forth. }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we compute a # Bivariate nonparametric regression estimate for Giovanni Baiocchi's # Italian income panel (see Italy for details) data("Italy") with(Italy, { # Compute the least-squares cross-validated bandwidths for the local # constant estimator (default) bw <- npregbw(xdat=ordered(year), ydat=gdp) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Supply your own bandwidth... bw <- npregbw(xdat=ordered(year), ydat=gdp, bws=c(0.75), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Treat year as continuous and supply your own scaling factor c in # c sigma n^{-1/(2p+q)} bw <- npregbw(xdat=year, ydat=gdp, bws=c(1.06), bandwidth.compute=FALSE, bwscaling=TRUE) summary(bw) # Note - see also the example for npudensbw() for more extensive # multiple illustrations of how to change the kernel function, kernel # order, bandwidth type and so forth. }) ## End(Not run)
Constructs nonparametric regression hat operators for npreg-compatible
bandwidth objects. The returned operator maps responses to fitted
values or derivative estimates via .
npreghat(bws, ...) ## S3 method for class 'formula' npreghat(bws, data = NULL, newdata = NULL, ...) ## S3 method for class 'rbandwidth' npreghat(bws, txdat = stop("training data 'txdat' missing"), exdat, y = NULL, output = c("matrix", "apply", "constraint"), basis = NULL, bernstein.basis = NULL, degree = NULL, deriv = NULL, leave.one.out = FALSE, ridge = 0, s = NULL, ...) ## S3 method for class 'npregression' npreghat(bws, txdat, y, ...) ## S3 method for class 'npreghat' predict(object, newdata = NULL, y = NULL, output = c("matrix", "apply", "constraint"), s = attr(object, "s"), leave.one.out = attr(object, "leave.one.out"), deriv = NULL, ...)npreghat(bws, ...) ## S3 method for class 'formula' npreghat(bws, data = NULL, newdata = NULL, ...) ## S3 method for class 'rbandwidth' npreghat(bws, txdat = stop("training data 'txdat' missing"), exdat, y = NULL, output = c("matrix", "apply", "constraint"), basis = NULL, bernstein.basis = NULL, degree = NULL, deriv = NULL, leave.one.out = FALSE, ridge = 0, s = NULL, ...) ## S3 method for class 'npregression' npreghat(bws, txdat, y, ...) ## S3 method for class 'npreghat' predict(object, newdata = NULL, y = NULL, output = c("matrix", "apply", "constraint"), s = attr(object, "s"), leave.one.out = attr(object, "leave.one.out"), deriv = NULL, ...)
These arguments identify the fitted bandwidth object, formula/data interface, training data, and evaluation data.
bws |
An object of class |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use |
exdat |
Optional evaluation predictors. |
newdata |
Optional evaluation data for formula and predict methods.
Without a new evaluation grid, prediction retains the operator's original
training-observation or external-query identity, including when changing
the derivative order. An explicit grid remains external even when its
coordinates equal the training data; this distinction can affect
nearest-neighbor radii. Formula newdata is evaluated with the trained
predictor transformations. Explicit native |
txdat |
Training predictors. |
These arguments control local-polynomial basis, degree, derivatives, leave-one-out behavior, and ridge stabilization.
basis |
Local polynomial basis: |
bernstein.basis |
Logical; select the stabilized LP representation. For
GLP, |
degree |
Optional local polynomial degree vector override (LP path). |
deriv |
Convenience alias for |
leave.one.out |
Logical; if |
ridge |
A finite nonnegative scalar. The default |
s |
Derivative multi-index over continuous predictors, with finite
non-negative integer entries. A named vector selects predictors by their
continuous-variable names; omitted coordinates have order zero. An unnamed
scalar selects the first continuous predictor. Unknown or duplicated names
are errors. Explicit |
This argument identifies a fitted hat-operator object supplied to an S3 method.
object |
An object returned by |
These arguments control whether the operator is returned as a matrix, applied directly, or returned as a quadratic-programming constraint design matrix.
output |
Either |
y |
Optional response vector or matrix for apply mode. For |
Further arguments are passed to methods.
... |
Additional arguments passed to methods. |
With a formula-derived bandwidth object, supplying only y
replaces the evaluated response in retained-training-sample order: one row
per observation retained after the original subset and missing-value selection.
Original excluded rows are not restored; row names or equal lengths do not
imply original-data order. The effective na.action is then applied
jointly to the retained predictors and replacement response; any new omission
indices refer to this retained sample. The selected bandwidths remain fixed,
and the returned object retains the replacement sample for subsequent refits.
Use data for full formula-data replacement, not together with a partial
response replacement. Explicit native training arguments retain their separate
positional contract.
Formula variables of class ts, including lagged variables, are
aligned on their common time support before fitting. Other variables
must already have the length of that intersection. Supply explicitly
aligned rows when using native data arguments instead of a formula.
Local-polynomial operators retain the fitted solve's numerical ridge
adjustment; see Numerical Ridging in npreg and its
Seifert–Gasser reference. A hat operator alone does not estimate residual
variance or apply the residual normalization used by regression inference.
Fewer nonzero-weight donor rows than basis coefficients trigger the same
existing ridge policy as fitting, for levels and derivative operators.
This is a structural rank bound, not a new numerical conditioning threshold.
For output = "matrix", the return value is a matrix with class
c("npreghat", "matrix") so it can be used directly in matrix products,
e.g. H %*% y. Attributes on the matrix store metadata used by
predict.npreghat.
For output = "apply", the function returns H^{(s)} y directly and
accepts matrix right-hand sides for one-shot bootstrap-style calculations.
An evaluation row whose required kernel normalization is exactly zero or
non-finite is returned as an NA hat row. Defined rows remain available,
and every finite nonzero normalization is used literally.
For non-beta local-polynomial mean operators with fixed or generalized
nearest-neighbor bandwidths, a failed external evaluation row is returned as
NA only when its pristine moment system is finite and every computed
kernel weight is exactly zero. One warning identifies the affected result rows
(after missing evaluation rows are omitted). This reports the computed weights;
it does not distinguish absence of geometric support from numerical underflow.
Defined rows retain their ordinary values. In matrix output, the corresponding
ridge.used entries are NA; apply output has undefined rows, and
constraint output has the corresponding undefined columns. Other solve failures
and zero nearest-neighbor radii remain errors. Training, leave-one-out and
internal complete-operator consumers retain strict failure behavior.
The same all-zero-weight certificate is used for external non-beta
local-constant (including degree-zero local-polynomial) first-derivative
operators with fixed, generalized-nearest-neighbor or adaptive-nearest-neighbor
bandwidths. Unsupported rows become NA, while supported derivative
rows keep their usual values. A zero sum formed by cancellation of nonzero
weights, non-finite arithmetic, and invalid nearest-neighbor radii remain
errors; they are not classified as empty rows.
Default higher and mixed local-polynomial derivative operators also use the
finite-pristine-system, all-zero-weight certificate for external rows. Their
ridge.used entries are then NA, with the same warning and output
shapes described above. An explicit positive ridge retains its requested
regularized operator; it is not replaced by automatic ridging or this default
unavailable-row policy.
For local-constant beta kernels, one first derivative is evaluated by the
same analytic C kernel used by npreg(..., gradients=TRUE). If an exact
support endpoint creates a raw-kernel jump, the hat operator cannot know
whether a future response will cancel it in the normalized ratio; the entire
affected row is therefore returned as NA with a warning. The compiled
estimator route can still return a finite response-specific gradient.
For output = "constraint", the function returns t(H^{(s)}) * y,
the row-weighted transpose commonly used as the design matrix in
shape-constrained quadratic-programming examples. This is a convenience route
that is exactly equivalent to obtaining H with output = "matrix"
and then computing t(H) * y; it does not solve a constrained estimation
problem.
Either a hat matrix (class "npreghat") or the applied result
H^{(s)} y, or the constraint design matrix t(H^{(s)}) * y,
depending on output.
## Not run: data(cps71) bw <- npregbw(xdat = cps71$age, ydat = cps71$logwage, regtype = "ll", bandwidth.compute = FALSE, bws = 1.0) H <- npreghat(bws = bw, txdat = data.frame(age = cps71$age)) H.fitted <- H A <- npreghat(bws = bw, txdat = data.frame(age = cps71$age), y = cps71$logwage, output = "constraint") all.equal(A, t(H) * cps71$logwage) ghat <- npreg(bws = bw) head(cbind(fitted(ghat), H.fitted), n = 2L) ## End(Not run)## Not run: data(cps71) bw <- npregbw(xdat = cps71$age, ydat = cps71$logwage, regtype = "ll", bandwidth.compute = FALSE, bws = 1.0) H <- npreghat(bws = bw, txdat = data.frame(age = cps71$age)) H.fitted <- H A <- npreghat(bws = bw, txdat = data.frame(age = cps71$age), y = cps71$logwage, output = "constraint") all.equal(A, t(H) * cps71$logwage) ghat <- npreg(bws = bw) head(cbind(fitted(ghat), H.fitted), n = 2L) ## End(Not run)
npregiv computes nonparametric estimation of an instrumental
regression function defined by conditional moment
restrictions stemming from a structural econometric model: , and involving
endogenous variables and and exogenous variables
and instruments . The function is the
solution of an ill-posed inverse problem.
When method="Tikhonov", npregiv uses the approach of
Darolles, Fan, Florens and Renault (2011) modified for local
polynomial kernel regression of any order (Darolles et al use local
constant kernel weighting which corresponds to setting p=0; see
below for details). When method="Landweber-Fridman",
npregiv uses the approach of Horowitz (2011) again using local
polynomial kernel regression (Horowitz uses B-spline weighting).
npregiv(y, ...) ## Default S3 method: npregiv(y, z, w, x = NULL, zeval = NULL, xeval = NULL, alpha = NULL, alpha.iter = NULL, alpha.max = 1e-01, alpha.min = 1e-10, alpha.tol = .Machine$double.eps^0.25, bw = NULL, constant = 0.5, iterate.diff.tol = 1.0e-08, iterate.max = 1000, iterate.Tikhonov = TRUE, iterate.Tikhonov.num = 1, method = c("Landweber-Fridman","Tikhonov"), nmulti = NULL, optim.abstol = .Machine$double.eps, optim.maxattempts = 10, optim.maxit = 500, optim.method = c("Nelder-Mead", "BFGS", "CG"), optim.reltol = sqrt(.Machine$double.eps), p = 1, penalize.iteration = TRUE, random.seed = 42, return.weights.phi = FALSE, return.weights.phi.deriv.1 = FALSE, return.weights.phi.deriv.2 = FALSE, smooth.residuals = TRUE, start.from = c("Eyz","EEywz"), starting.values = NULL, stop.on.increase = TRUE, regtype = NULL, degree = NULL, nomad = FALSE, ...) ## S3 method for class 'formula' npregiv(y, data = NULL, subset, na.action, newdata = NULL, zeval = NULL, xeval = NULL, ...) ## S3 method for class 'npregiv' plot(x, gradients = FALSE, data.overlay = TRUE, data.rug = FALSE, ...)npregiv(y, ...) ## Default S3 method: npregiv(y, z, w, x = NULL, zeval = NULL, xeval = NULL, alpha = NULL, alpha.iter = NULL, alpha.max = 1e-01, alpha.min = 1e-10, alpha.tol = .Machine$double.eps^0.25, bw = NULL, constant = 0.5, iterate.diff.tol = 1.0e-08, iterate.max = 1000, iterate.Tikhonov = TRUE, iterate.Tikhonov.num = 1, method = c("Landweber-Fridman","Tikhonov"), nmulti = NULL, optim.abstol = .Machine$double.eps, optim.maxattempts = 10, optim.maxit = 500, optim.method = c("Nelder-Mead", "BFGS", "CG"), optim.reltol = sqrt(.Machine$double.eps), p = 1, penalize.iteration = TRUE, random.seed = 42, return.weights.phi = FALSE, return.weights.phi.deriv.1 = FALSE, return.weights.phi.deriv.2 = FALSE, smooth.residuals = TRUE, start.from = c("Eyz","EEywz"), starting.values = NULL, stop.on.increase = TRUE, regtype = NULL, degree = NULL, nomad = FALSE, ...) ## S3 method for class 'formula' npregiv(y, data = NULL, subset, na.action, newdata = NULL, zeval = NULL, xeval = NULL, ...) ## S3 method for class 'npregiv' plot(x, gradients = FALSE, data.overlay = TRUE, data.rug = FALSE, ...)
These arguments identify the response, endogenous variables, instruments, exogenous covariates, and evaluation data.
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame used with the formula interface. Formula roles are
written explicitly as |
subset |
an optional expression selecting training rows in the formula interface. |
na.action |
a function specifying missing-value handling for the formula model frame. |
newdata |
an optional data frame supplying fit-time evaluation values for the
formula |
w |
a |
x |
for |
xeval |
an |
y |
a one (1) dimensional numeric or integer vector of dependent data, or a
formula using the explicit IV grammar described under |
z |
a |
zeval |
a |
gradients |
logical; display the stored first partial derivative instead of the
structural function. The current plot method supports one endogenous
coordinate. The default is |
data.overlay |
logical; overlay the training response on a structural-function display.
The default is |
data.rug |
logical; add a rug showing the training |
These arguments control the Landweber-Fridman iteration path.
constant |
the constant to use when using |
iterate.diff.tol |
the search tolerance for the difference in the stopping rule from
iteration to iteration when using |
iterate.max |
an integer indicating the maximum number of iterations permitted
before termination occurs when using |
iterate.Tikhonov |
a logical value controlling whether |
iterate.Tikhonov.num |
a positive integer giving the number of outer response-adaptive bandwidth/operator refinement cycles. It is not the order of iterated Tikhonov regularization. |
method |
the regularization method employed (defaults to
|
nmulti |
integer number of times to restart the process of finding extrema of the cross-validation function from different (random) initial points. |
These arguments control numerical optimization for the inverse problem.
optim.abstol |
the absolute convergence tolerance used by |
optim.maxattempts |
maximum number of attempts taken trying to achieve successful
convergence in |
optim.maxit |
maximum number of iterations used by |
optim.method |
method used by the default method is an implementation of that of Nelder and Mead (1965), that uses only function values and is robust but relatively slow. It will work reasonably well for non-differentiable functions. method method |
optim.reltol |
relative convergence tolerance used by |
p |
the order of the local polynomial regression (defaults to
|
regtype |
an optional modern fixed-degree spelling: |
degree |
one nonnegative integer supplied with |
nomad |
logical or |
These arguments control returned kernel weights, starting values, residual smoothing, and iteration stopping behavior.
penalize.iteration |
a logical value indicating whether to
penalize the norm by the number of iterations or not (default
|
random.seed |
an integer used to seed R's random number generator. This ensures replicability of the numerical search. Defaults to 42. |
return.weights.phi |
a logical value (defaults to |
return.weights.phi.deriv.1 |
a logical value (defaults to |
return.weights.phi.deriv.2 |
a logical value (defaults to |
smooth.residuals |
a logical value indicating whether to
optimize bandwidths for the regression of
|
start.from |
a character string indicating whether to start from
|
starting.values |
an optional finite numeric vector supplying the
training-row structural initialization. Its derivative state is estimated
from the corresponding local-polynomial interpolant using the selected
smoothing contract; it is not set to zero. When weights are requested,
this supplied initialization is treated as fixed with respect to |
stop.on.increase |
a logical value (defaults to |
These arguments control Tikhonov regularization and its bandwidth.
alpha |
a numeric scalar that, if supplied, is used rather than numerically
solving for |
alpha.iter |
a positive numeric scalar that, if supplied, is used for the ordinary Tikhonov solve after the outer bandwidth/operator refinement rather than selecting a refined regularization parameter numerically. |
alpha.max |
maximum of search range for |
alpha.min |
minimum of search range for |
alpha.tol |
the search tolerance for |
bw |
an object which, if provided, contains bandwidths and parameters
(obtained from a previous invocation of |
Further arguments are passed to lower-level kernel-sum and estimation routines.
... |
Only fixed bandwidths are currently supported. Supplying
|
Formula variables of class ts, including lagged variables, are
aligned on their common time support before fitting. Other variables
must already have the length of that intersection. Supply explicitly
aligned rows when using native data arguments instead of a formula.
Local-polynomial nuisance fits may use numerical diagonal ridging.
For its Seifert–Gasser motivation, see npreg.
This is distinct from regularization of the instrumental-variable
inverse problem and does not apply the ordinary-regression residual
uncertainty correction to IV inference.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
The formula interface uses explicit role order:
y ~ z | w and y ~ z | w | x. Additive transformations and
factors are retained through model.frame. Dot expansion and formula
interaction operators are rejected because they do not identify a unique
mixed-data kernel role; create an explicit transformed variable (for example
with I(a * b)) instead. Native vector/data-frame calls remain
supported unchanged.
For Landweber-Fridman regularization, state means the complete
state after exactly residual-correction updates. Column
of phi.mat, norm.stop[N], norm.index, the
returned structural curve, derivatives, and optional weights therefore all
refer to that same state. With penalize.iteration=TRUE, the stopping
value is times the normalized squared conditional-residual norm
evaluated at state .
Multivariate derivative components are pure coordinate partials in the
order of the continuous columns in the augmented structural block
data.frame(z, x). Thus the first-derivative matrix has one named
column per continuous endogenous or appended exogenous coordinate; it does
not contain a mixed derivative.
The Tikhonov route solves the Darolles et al. operator equation with
and right-hand side . Its default
data-driven selector is the fixed order-two criterion of
Feve and Florens (2010), Equation (3.10); the returned curve is the ordinary
Tikhonov solution. iterate.Tikhonov.num counts outer bandwidth and
operator refinements. The current implementation selects alpha.iter
during the first outer cycle and reuses it in later cycles; it does not
implement a per-cycle alpha policy or the alternative Darolles extended-
residual selector.
Tikhonov regularization requires computation of weight matrices of
dimension which can be computationally costly
in terms of memory requirements and may be unsuitable for large
datasets. Landweber-Fridman will be preferred in such settings as it
does not require construction and storage of these weight matrices
while it also avoids the need for numerical optimization methods to
determine .
method="Landweber-Fridman" uses an optimal stopping rule based
upon . However, if local rather than global
optima are encountered the resulting estimates can be overly noisy. To
best guard against this eventuality set nmulti to a larger
number than the default nmulti=min(2,p) for the first
iteration, where p is the dimension of the current smoothing
problem.
Note that for subsequent Landweber-Fridman iterations, a “warm
start” strategy is employed. The optimal bandwidths from the previous
iteration are used as starting values for the current iteration. The
user-supplied nmulti is respected for all iterations. For
iterations after the first successful one, these optimal bandwidths
serve as the first of the multiple initial points (a warm start),
while any remaining restarts are cold starts. If nmulti is not
explicitly supplied by the user, it defaults to min(2,p) for the first
iteration and to 1 for all subsequent iterations. This strategy
provides a balance between computational efficiency and robustness,
allowing the numerical optimizer to refine the structural bandwidths
as the residuals evolve incrementally while still guarding against
local optima.
When using method="Landweber-Fridman", iteration will terminate
when either the change in the value of
from iteration to iteration is
less than iterate.diff.tol or we hit iterate.max or
stops falling in value and
starts rising.
The option bw= would be useful, say, when bootstrapping is
necessary. Note that when passing bw, it must be obtained from
a previous invocation of npregiv. For instance, if
model.iv was obtained from an invocation of npregiv with
method="Landweber-Fridman", then the following needs to be fed
to the subsequent invocation of npregiv:
model.iv <- npregiv(\dots)
bw <- NULL
bw$bw.E.y.w <- model.iv$bw.E.y.w
bw$bw.E.y.z <- model.iv$bw.E.y.z
bw$bw.resid.w <- model.iv$bw.resid.w
bw$bw.resid.fitted.w.z <- model.iv$bw.resid.fitted.w.z
bw$norm.index <- model.iv$norm.index
foo <- npregiv(\dots,bw=bw)
If, on the other hand model.iv was obtained from an invocation
of npregiv with method="Tikhonov", then the following
needs to be fed to the subsequent invocation of npregiv:
model.iv <- npregiv(\dots)
bw <- NULL
bw$alpha <- model.iv$alpha
bw$alpha.iter <- model.iv$alpha.iter
bw$bw.E.y.w <- model.iv$bw.E.y.w
bw$bw.E.E.y.w.z <- model.iv$bw.E.E.y.w.z
bw$bw.E.phi.w <- model.iv$bw.E.phi.w
bw$bw.E.E.phi.w.z <- model.iv$bw.E.E.phi.w.z
foo <- npregiv(\dots,bw=bw)
Or, if model.iv was obtained from an invocation of
npregiv with either method="Landweber-Fridman" or
method="Tikhonov", then the following would also work:
model.iv <- npregiv(\dots)
foo <- npregiv(\dots,bw=model.iv)
When exogenous predictors x (xeval) are passed, they are
appended to both the endogenous predictors z and the
instruments w as additional columns. If this is not desired,
one can manually append the exogenous variables to z (or
w) prior to passing z (or w), and then they will
only appear among the z or w as desired.
npregiv returns a npregiv object. The generic
functions print, summary,
plot, fitted, residuals, and
gradients support objects of this type. fitted
returns the selected structural function and gradients returns its
stored first derivatives. Both are training-row accessors even when
fit-time evaluation data were supplied; evaluation results remain in the
phi.eval and phi.deriv.eval.* fields. Residuals use the
aligned training structural curve. For formula fits using an exclusion-style na.action,
these accessors restore omitted rows. summary returns a structured
summary.npregiv object with a dedicated print method. The printed
smoothing description reports the effective continuous-stage policy using
the same Kernel Regression Estimator: labels as npreg:
Local-Constant, Local-Linear, or, for
regtype="lp", the local-polynomial degree and basis details. The
retained legacy p field is not printed separately.
The plot method displays the structural level by default, uses a separate
fit-time evaluation grid when phi.eval is available, and overlays
the training response by default without replacing that evaluation curve.
Set gradients=TRUE for the first derivative and
data.rug=TRUE for the training-support rug.
npregiv returns a list with components phi,
phi.mat and either alpha when method="Tikhonov"
or norm.index, norm.stop and convergence when
method="Landweber-Fridman", among others. The compact
bws, smoothing.spec, and stage.specs components record
stage bandwidth payloads and requested/effective fixed-degree smoothing
state without replacing the legacy bandwidth fields.
In addition, if any of return.weights.* are invoked
(*=1,2), then phi.weights and phi.deriv.*.weights
return weight matrices for computing the instrumental regression and
its partial derivatives. Note that these weights, post multiplied by
the response vector , will deliver the estimates returned in
phi, phi.deriv.1, and phi.deriv.2 (the latter
only being produced when p is 2 or greater). When invoked with
evaluation data, similar matrices are returned but named
phi.eval.weights and phi.deriv.eval.*.weights. These
weights can be used for constrained estimation, among others.
When method="Landweber-Fridman" is invoked, bandwidth objects
are returned in bw.E.y.w (scalar/vector), bw.E.y.z
(scalar/vector), and bw.resid.w (matrix) and
bw.resid.fitted.w.z, the latter matrices containing bandwidths
for each iteration stored as rows. When method="Tikhonov" is
invoked, bandwidth objects are returned in bw.E.y.w,
bw.E.E.y.w.z, and bw.E.phi.w and bw.E.E.phi.w.z.
This function should be considered to be in ‘beta test’ status until further notice.
Jeffrey S. Racine [email protected], Samuele Centorrino [email protected]
Carrasco, M. and J.P. Florens and E. Renault (2007), “Linear Inverse Problems in Structural Econometrics Estimation Based on Spectral Decomposition and Regularization,” In: James J. Heckman and Edward E. Leamer, Editor(s), Handbook of Econometrics, Elsevier, 2007, Volume 6, Part 2, Chapter 77, Pages 5633-5751
Darolles, S. and Y. Fan and J.P. Florens and E. Renault (2011), “Nonparametric instrumental regression,” Econometrica, 79, 1541-1565.
Feve, F. and J.P. Florens (2010), “The practice of non-parametric estimation by solving inverse problems: the example of transformation models,” Econometrics Journal, 13, S1-S27.
Florens, J.P. and J.S. Racine and S. Centorrino (2018), “Nonparametric instrumental derivatives,” Journal of Nonparametric Statistics, 30 (2), 368-391.
Fridman, V. M. (1956), “A method of successive approximations for Fredholm integral equations of the first kind,” Uspeskhi, Math. Nauk., 11, 233-334, in Russian.
Horowitz, J.L. (2011), “Applied nonparametric instrumental variables estimation,” Econometrica, 79, 347-394.
Landweber, L. (1951), “An iterative formula for Fredholm integral equations of the first kind,” American Journal of Mathematics, 73, 615-24.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2004), “Cross-validated Local Linear Nonparametric Regression,” Statistica Sinica, 14, 485-512.
np.kernels, np.options, plot
npregivderiv,npreg
## Not run: ## This illustration was made possible by Samuele Centorrino ## <[email protected]> set.seed(42) n <- 500 trim <- 0.005 ## Endogenous-regressor DGP: ## ## y = phi(z) + u ## E(u | z) != 0 ## z = 0.2 w + v ## E(u | w) = 0 v <- rnorm(n, mean = 0, sd = 0.27) eps <- rnorm(n, mean = 0, sd = 0.05) u <- -0.5 * v + eps w <- rnorm(n) phi <- function(z) z^2 z <- 0.2 * w + v y <- phi(z) + u ivdata <- data.frame(y, z, w) ivdata <- ivdata[order(ivdata$z), ] model.iv <- npregiv(y ~ z | w, data = ivdata, regtype = "ll") phi.iv <- fitted(model.iv) ## Compare with the non-IV local-linear estimator of E(y | z). model.noniv <- npreg(y ~ z, data = ivdata, regtype = "ll") mean.noniv <- fitted(model.noniv) ## Restrict the display to the central 99 percent of the z observations. zlim <- quantile(ivdata$z, c(trim, 1 - trim)) keep <- ivdata$z >= zlim[1L] & ivdata$z <= zlim[2L] ylim <- range(ivdata$y[keep], phi.iv[keep], mean.noniv[keep]) plot(ivdata$z[keep], phi(ivdata$z[keep]), ylim = ylim, ylab = "Y", xlab = "Z", main = "Nonparametric Instrumental Kernel Regression", type = "l", lwd = 2) points(ivdata$z[keep], ivdata$y[keep], cex = 0.25, col = "grey") lines(ivdata$z[keep], phi.iv[keep], col = "blue", lwd = 2, lty = 2) lines(ivdata$z[keep], mean.noniv[keep], col = "red", lwd = 2, lty = 4) legend("topright", c(expression(varphi(z)), expression(paste("Nonparametric ", hat(varphi)(z))), "Nonparametric E(y | z)"), lty = c(1, 2, 4), col = c("black", "blue", "red"), lwd = c(2, 2, 2), bty = "n") ## End(Not run)## Not run: ## This illustration was made possible by Samuele Centorrino ## <[email protected]> set.seed(42) n <- 500 trim <- 0.005 ## Endogenous-regressor DGP: ## ## y = phi(z) + u ## E(u | z) != 0 ## z = 0.2 w + v ## E(u | w) = 0 v <- rnorm(n, mean = 0, sd = 0.27) eps <- rnorm(n, mean = 0, sd = 0.05) u <- -0.5 * v + eps w <- rnorm(n) phi <- function(z) z^2 z <- 0.2 * w + v y <- phi(z) + u ivdata <- data.frame(y, z, w) ivdata <- ivdata[order(ivdata$z), ] model.iv <- npregiv(y ~ z | w, data = ivdata, regtype = "ll") phi.iv <- fitted(model.iv) ## Compare with the non-IV local-linear estimator of E(y | z). model.noniv <- npreg(y ~ z, data = ivdata, regtype = "ll") mean.noniv <- fitted(model.noniv) ## Restrict the display to the central 99 percent of the z observations. zlim <- quantile(ivdata$z, c(trim, 1 - trim)) keep <- ivdata$z >= zlim[1L] & ivdata$z <= zlim[2L] ylim <- range(ivdata$y[keep], phi.iv[keep], mean.noniv[keep]) plot(ivdata$z[keep], phi(ivdata$z[keep]), ylim = ylim, ylab = "Y", xlab = "Z", main = "Nonparametric Instrumental Kernel Regression", type = "l", lwd = 2) points(ivdata$z[keep], ivdata$y[keep], cex = 0.25, col = "grey") lines(ivdata$z[keep], phi.iv[keep], col = "blue", lwd = 2, lty = 2) lines(ivdata$z[keep], mean.noniv[keep], col = "red", lwd = 2, lty = 4) legend("topright", c(expression(varphi(z)), expression(paste("Nonparametric ", hat(varphi)(z))), "Nonparametric E(y | z)"), lty = c(1, 2, 4), col = c("black", "blue", "red"), lwd = c(2, 2, 2), bty = "n") ## End(Not run)
npregivderiv uses the approach of Florens, Racine and Centorrino
(2018) to compute the partial derivative of a nonparametric
estimation of an instrumental regression function
defined by conditional moment restrictions stemming from a structural
econometric model: , and involving endogenous variables and and
exogenous variables and instruments . The derivative
function is the solution of an ill-posed inverse
problem, and is computed using Landweber-Fridman regularization.
npregivderiv(y, ...) ## Default S3 method: npregivderiv(y, z, w, x = NULL, zeval = NULL, weval = NULL, xeval = NULL, constant = 0.5, iterate.break = TRUE, iterate.max = 1000, nmulti = NULL, random.seed = 42, smooth.residuals = TRUE, start.from = c("Eyz","EEywz"), starting.values = NULL, stop.on.increase = TRUE, regtype = c("ll","lc","lp"), degree = NULL, nomad = FALSE, ...) ## S3 method for class 'formula' npregivderiv(y, data = NULL, subset, na.action, newdata = NULL, zeval = NULL, weval = NULL, xeval = NULL, ...) ## S3 method for class 'npregivderiv' plot(x, gradients = TRUE, data.overlay = TRUE, data.rug = FALSE, ...)npregivderiv(y, ...) ## Default S3 method: npregivderiv(y, z, w, x = NULL, zeval = NULL, weval = NULL, xeval = NULL, constant = 0.5, iterate.break = TRUE, iterate.max = 1000, nmulti = NULL, random.seed = 42, smooth.residuals = TRUE, start.from = c("Eyz","EEywz"), starting.values = NULL, stop.on.increase = TRUE, regtype = c("ll","lc","lp"), degree = NULL, nomad = FALSE, ...) ## S3 method for class 'formula' npregivderiv(y, data = NULL, subset, na.action, newdata = NULL, zeval = NULL, weval = NULL, xeval = NULL, ...) ## S3 method for class 'npregivderiv' plot(x, gradients = TRUE, data.overlay = TRUE, data.rug = FALSE, ...)
These arguments identify the response, endogenous variables, instruments, exogenous covariates, and evaluation data.
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame used with the formula interface. This estimator
accepts |
subset |
an optional expression selecting training rows in the formula interface. |
na.action |
a function specifying missing-value handling for the formula model frame. |
newdata |
an optional data frame supplying fit-time values of formula variable
|
w |
a |
weval |
retained for compatibility. The inverse problem is defined on the
training instruments, so a supplied value must equal |
x |
for |
xeval |
reserved with |
y |
a one (1) dimensional numeric or integer vector of dependent data, or a
formula using the explicit IV grammar described under |
z |
one finite continuous numeric endogenous regressor with at least two distinct support points. |
zeval |
finite values of the endogenous regressor at which to evaluate the
structural derivative. The training inverse problem, residuals, centering,
stopping rule, and selected state remain based on |
gradients |
logical; display the structural derivative when |
data.overlay |
logical; overlay the training response on a structural-function display.
The default is |
data.rug |
logical; add a rug showing the training |
These arguments control derivative iteration and reproducibility settings.
constant |
the constant to use for Landweber-Fridman iteration. |
iterate.break |
a logical value indicating whether to compute all objects up to
|
iterate.max |
an integer indicating the maximum number of complete positive Landweber-Fridman states to evaluate. The initialization state is numbered zero and does not consume this budget. |
nmulti |
integer number of times to restart the process of finding extrema of the cross-validation function from different (random) initial points. |
random.seed |
an integer used to seed R's random number generator. This ensures replicability of the numerical search. Defaults to 42. |
These arguments control residual smoothing and the initial derivative path.
smooth.residuals |
a logical value (defaults to |
start.from |
a character string indicating whether to start from
|
starting.values |
an optional vector supplying the derivative
immediately before the first reported Landweber-Fridman update. When
omitted, the initialization derivative is obtained from |
stop.on.increase |
a logical value (defaults to |
These arguments control all internal npreg stages consistently.
regtype |
a fixed regression type: |
degree |
one nonnegative integer required with |
nomad |
logical or |
Further arguments are passed to npreg and npksum.
... |
Only fixed bandwidths are currently supported. Supplying
|
Formula variables of class ts, including lagged variables, are
aligned on their common time support before fitting. Other variables
must already have the length of that intersection. Supply explicitly
aligned rows when using native data arguments instead of a formula.
Local-polynomial nuisance fits may use numerical diagonal ridging.
For its Seifert–Gasser motivation, see npreg.
This is distinct from regularization of the instrumental-variable
inverse problem and does not apply the ordinary-regression residual
uncertainty correction to IV inference.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
The formula interface uses explicit role order:
y ~ z | w and y ~ z | w | x. Additive transformations and
factors are retained through model.frame. Dot expansion and formula
interaction operators are rejected because they do not identify a unique
mixed-data kernel role; create an explicit transformed variable (for example
with I(a * b)) instead. Native vector/data-frame calls remain
supported unchanged.
The current derivative operator is univariate in z. Consequently,
although the shared parser recognizes the package-wide optional | x
partition, npregivderiv rejects it explicitly rather than silently
changing the derivative target. Post-fit predict() is not available;
use fit-time newdata or the native evaluation arguments.
Fit-time evaluation is output-only. Conditional regressions, the empirical
adjoint, fitted-residual centering, structural integration, stopping values,
and state selection are always computed on aligned training rows. A separate
zeval accumulates the derivative corrections from those same training
states into phi.prime.eval and phi.prime.eval.mat; it cannot
change phi, phi.prime, their training paths, or
norm.stop. Structural levels at arbitrary new points are not returned
because this derivative estimator's integration and centering normalization
is defined on the training support.
Let denote the initialization derivative,
obtained from start.from or supplied directly through
starting.values. Its integrated and centered curve is
. This state is retained in
starting.values.phi.prime and starting.values.phi; it is
not a column of the positive-iteration matrices. For ,
iteration means exactly completed residual-correction
updates after this initialization. Column of
phi.prime.mat and phi.mat therefore contains the coherent
pair , and
norm.stop[N] is evaluated at that same state using the multiplier
. Check the stopping vector for anomalies such as an immediate
increase.
Landweber-Fridman iteration uses an optimal stopping rule based upon
. However, if local rather than global optima are encountered the
resulting estimates can be overly noisy. To best guard against this
eventuality set nmulti to a larger number than the default
nmulti=min(2,p) for the first iteration, where p is
the dimension of the current smoothing problem.
Note that for subsequent Landweber-Fridman iterations, a “warm
start” strategy is employed. The optimal bandwidths from the previous
iteration are used as starting values for the current iteration. The
user-supplied nmulti is respected for all iterations. For
iterations after the first successful one, these optimal bandwidths
serve as the first of the multiple initial points (a warm start),
while any remaining restarts are cold starts. If nmulti is not
explicitly supplied by the user, it defaults to min(2,p) for the first
iteration and to 1 for all subsequent iterations. This strategy
provides a balance between computational efficiency and robustness,
allowing the numerical optimizer to refine the structural bandwidths
as the residuals evolve incrementally while still guarding against
local optima.
With iterate.break=TRUE, iteration can stop after the stopping rule
turns upward once the initial guard interval has passed; otherwise all
states through iterate.max are evaluated. The selected state is then
obtained from the computed stopping profile.
npregivderiv returns a npregivderiv object. The
generic functions print, summary,
plot, fitted, residuals, and
gradients support objects of this type. fitted
returns the reconstructed training structural function while gradients
returns the training derivative estimate. Residuals use the aligned
training structural curve even when a separate evaluation grid was
supplied. For formula fits using an exclusion-style
na.action, these accessors restore omitted rows. summary
returns a structured
summary.npregivderiv object with a dedicated print method. The
printed smoothing description reports the effective continuous-stage
policy using the same Kernel Regression Estimator: labels as
npreg: Local-Constant, Local-Linear, or, for
regtype="lp", the local-polynomial degree and basis details.
The plot method displays the derivative by default, preserving the
estimator family's primary target. Set gradients=FALSE to display
the reconstructed training structural function. The training response is
overlaid only on that level display; data.rug=TRUE adds the training
support without replacing an available derivative evaluation curve.
npregivderiv returns a list with components phi.prime,
phi, phi.prime.mat, phi.mat, and, when a separate
evaluation grid was supplied, phi.prime.eval and
phi.prime.eval.mat,
num.iterations, norm.stop, convergence, and the
initialization components starting.values.phi.prime and
starting.values.phi. num.iterations is the selected state
returned in phi.prime and phi; the number of states evaluated,
including any stopping-rule overshoot, is length(norm.stop). The
compact bws, smoothing.spec, and stage.specs
components record stage bandwidth payloads and requested/effective
fixed-degree smoothing state without replacing the legacy bandwidth fields.
This function currently supports univariate z only. This
function should be considered to be in ‘beta test’ status until
further notice.
Jeffrey S. Racine [email protected]
Carrasco, M. and J.P. Florens and E. Renault (2007), “Linear Inverse Problems in Structural Econometrics Estimation Based on Spectral Decomposition and Regularization,” In: James J. Heckman and Edward E. Leamer, Editor(s), Handbook of Econometrics, Elsevier, 2007, Volume 6, Part 2, Chapter 77, Pages 5633-5751
Darolles, S. and Y. Fan and J.P. Florens and E. Renault (2011), “Nonparametric instrumental regression,” Econometrica, 79, 1541-1565.
Feve, F. and J.P. Florens (2010), “The practice of non-parametric estimation by solving inverse problems: the example of transformation models,” Econometrics Journal, 13, S1-S27.
Florens, J.P. and J.S. Racine and S. Centorrino (2018), “Nonparametric instrumental derivatives,” Journal of Nonparametric Statistics, 30 (2), 368-391.
Fridman, V. M. (1956), “A method of successive approximations for Fredholm integral equations of the first kind,” Uspeskhi, Math. Nauk., 11, 233-334, in Russian.
Horowitz, J.L. (2011), “Applied nonparametric instrumental variables estimation,” Econometrica, 79, 347-394.
Landweber, L. (1951), “An iterative formula for Fredholm integral equations of the first kind,” American Journal of Mathematics, 73, 615-24.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2004), “Cross-validated Local Linear Nonparametric Regression,” Statistica Sinica, 14, 485-512.
np.kernels, np.options, plot
npregiv,npreg
## Not run: ## This illustration was made possible by Samuele Centorrino ## <[email protected]> set.seed(42) n <- 500 trim <- 0.005 ## Endogenous-regressor DGP: ## ## y = phi(z) + u ## E(u | z) != 0 ## z = 0.2 w + v ## E(u | w) = 0 v <- rnorm(n, mean = 0, sd = 0.27) eps <- rnorm(n, mean = 0, sd = 0.05) u <- -0.5 * v + eps w <- rnorm(n) phi <- function(z) z^2 phi.prime <- function(z) 2 * z z <- 0.2 * w + v y <- phi(z) + u ivdata <- data.frame(y, z, w) ivdata <- ivdata[order(ivdata$z), ] model.ivderiv <- npregivderiv(y ~ z | w, data = ivdata) deriv.iv <- gradients(model.ivderiv) ## Restrict the display to the central 99 percent of the z observations. zlim <- quantile(ivdata$z, c(trim, 1 - trim)) keep <- ivdata$z >= zlim[1L] & ivdata$z <= zlim[2L] plot(ivdata$z[keep], deriv.iv[keep], main = "", xlab = "Z", ylab = "Derivative", type = "l", lwd = 2) curve(phi.prime(x), add = TRUE, col = 2, lty = 2, lwd = 2) rug(ivdata$z[keep]) ## End(Not run)## Not run: ## This illustration was made possible by Samuele Centorrino ## <[email protected]> set.seed(42) n <- 500 trim <- 0.005 ## Endogenous-regressor DGP: ## ## y = phi(z) + u ## E(u | z) != 0 ## z = 0.2 w + v ## E(u | w) = 0 v <- rnorm(n, mean = 0, sd = 0.27) eps <- rnorm(n, mean = 0, sd = 0.05) u <- -0.5 * v + eps w <- rnorm(n) phi <- function(z) z^2 phi.prime <- function(z) 2 * z z <- 0.2 * w + v y <- phi(z) + u ivdata <- data.frame(y, z, w) ivdata <- ivdata[order(ivdata$z), ] model.ivderiv <- npregivderiv(y ~ z | w, data = ivdata) deriv.iv <- gradients(model.ivderiv) ## Restrict the display to the central 99 percent of the z observations. zlim <- quantile(ivdata$z, c(trim, 1 - trim)) keep <- ivdata$z >= zlim[1L] & ivdata$z <= zlim[2L] plot(ivdata$z[keep], deriv.iv[keep], main = "", xlab = "Z", ylab = "Derivative", type = "l", lwd = 2) curve(phi.prime(x), add = TRUE, col = 2, lty = 2, lwd = 2) rug(ivdata$z[keep]) ## End(Not run)
npscoef computes a kernel regression estimate of a one (1)
dimensional dependent variable on -variate explanatory data,
using the model where
, given a set of evaluation
points, training points (consisting of explanatory data and dependent
data), and a bandwidth specification. A bandwidth specification can be
a scbandwidth object, or a bandwidth vector, bandwidth type and
kernel type.
npscoef(bws, ...) ## S3 method for class 'formula' npscoef(bws, data = NULL, newdata = NULL, y.eval = FALSE, se = FALSE, ...) ## Default S3 method: npscoef(bws, txdat, tydat, tzdat, nomad = FALSE, se = FALSE, ...) ## S3 method for class 'scbandwidth' npscoef(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), tzdat = NULL, exdat, eydat, ezdat, betas = FALSE, se = FALSE, iterate = TRUE, leave.one.out = FALSE, maxiter = 100, residuals = FALSE, tol = .Machine$double.eps, ...)npscoef(bws, ...) ## S3 method for class 'formula' npscoef(bws, data = NULL, newdata = NULL, y.eval = FALSE, se = FALSE, ...) ## Default S3 method: npscoef(bws, txdat, tydat, tzdat, nomad = FALSE, se = FALSE, ...) ## S3 method for class 'scbandwidth' npscoef(bws, txdat = stop("training data 'txdat' missing"), tydat = stop("training data 'tydat' missing"), tzdat = NULL, exdat, eydat, ezdat, betas = FALSE, se = FALSE, iterate = TRUE, leave.one.out = FALSE, maxiter = 100, residuals = FALSE, tol = .Machine$double.eps, ...)
These arguments identify the bandwidth specification, formula/data interface, and smooth-coefficient training data.
bws |
a bandwidth specification. This can be set as a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
txdat |
a |
tydat |
a one (1) dimensional numeric or integer vector of dependent data, each
element |
tzdat |
an optionally specified |
This argument controls the recommended automatic local-polynomial NOMAD route, which jointly selects continuous polynomial degree and bandwidths when these are computed inside npscoef.
nomad |
logical shortcut passed through to |
These arguments control where the smooth-coefficient fit is evaluated and which evaluation quantities are returned.
exdat |
a |
eydat |
a one (1) dimensional numeric or integer vector of the true values of the dependent variable. Optional, and used only to calculate the true errors. |
ezdat |
an optionally specified |
newdata |
An optional data frame in which to look for evaluation data. If omitted, the training data are used. |
y.eval |
If |
These arguments control returned coefficient estimates, errors, residuals, and iterative backfitting.
betas |
a logical value indicating whether or not estimates of the
components of |
se |
a logical value indicating whether or not asymptotic standard errors
should be computed and returned in the resulting
|
iterate |
a logical value indicating whether or not backfitted estimates
should be iterated for self-consistency. Defaults to |
leave.one.out |
a logical value to specify whether or not to compute the leave one
out estimates. Will not work if |
maxiter |
integer specifying the maximum number of times to iterate the
backfitted estimates while attempting to make the backfitted estimates
converge to the desired tolerance. Defaults to |
residuals |
a logical value indicating that you want residuals computed and
returned in the resulting |
tol |
desired tolerance on the relative convergence of backfit
estimates. Defaults to |
Further arguments are passed to the bandwidth-selection counterpart when bandwidths are not supplied.
... |
additional arguments supplied to specify the regression type,
bandwidth type, kernel types, selection methods, and so on.
To do this, you may specify any of |
Prediction with se.fit = TRUE reports known training mean squared
error in residual.scale, retaining MSE units, or NA when
training provenance is unavailable. Evaluation outcomes do not replace this
training score. No additional fit is performed to recover it.
In native calls, three unnamed arguments follow the fitter's bandwidth-first
convention: npscoef(bws, txdat, tydat); replacing training data
does not reuse a separate smoothing sample from the bandwidth object.
Supply tzdat explicitly to replace that role; otherwise the smoothing data default
to the training predictors. Numeric argument types cannot distinguish this
from an intended data-first call. To select bandwidths with separate smoothing
data, write npscoef(xdat, ydat, zdat = zdat) or name all data roles.
The selector npscoefbw(xdat, ydat, zdat) retains its data-first
convention. No argument roles are inferred from vector lengths or values.
With a formula-derived bandwidth object, supplying only tydat
replaces the evaluated response in retained-training-sample order: one row
per observation retained after the original subset and missing-value selection.
Original excluded rows are not restored; row names or equal lengths do not
imply original-data order. The effective na.action is then applied
jointly to the retained predictors and replacement response; any new omission
indices refer to this retained sample. The selected bandwidths remain fixed,
and the returned object retains the replacement sample for subsequent refits.
Use data for full formula-data replacement, not together with a partial
response replacement. Explicit native training arguments retain their separate
positional contract.
For native (non-formula) objects, named newdata columns are matched
to the retained variable names and reordered as needed. Extra columns are
ignored; missing, duplicate or ambiguous names are errors. An unnamed
matrix or vector remains positional for a single evaluation role.
Explicit native evaluation arguments retain their positional contract and
take precedence over newdata.
For a native bandwidth object, newdata is split into
exdat and ezdat using the retained predictor and smoothing
variable names. Names must identify both roles unambiguously;
explicitly supplied native evaluation arguments take precedence. This
evaluates at the requested rows without repeating bandwidth selection.
When an external evaluation row has no usable kernel support or its
kernel-weighted system cannot be solved, the corresponding fitted value,
coefficients and requested standard errors are NA. One warning
identifies affected rows; valid rows are retained in their original order.
A larger bandwidth or another kernel may provide usable support.
Required training and bootstrap fits instead signal an error on this
failure; they do not silently discard rows. Being outside the training
range alone does not imply that a local fit is undefined.
npscoef returns a smoothcoefficient object. The generic
functions fitted, residuals, coef,
se, and predict,
extract (or generate) estimated values,
residuals, coefficients, bootstrapped standard
errors on estimates, and predictions, respectively, from
the returned object. Furthermore, the functions summary
and plot support objects of this type. The returned object
has the following components:
eval |
evaluation points |
mean |
estimation of the regression function (conditional mean) at the evaluation points |
merr |
if |
beta |
if |
grad |
estimated derivatives of the conditional mean with
respect to the regressors in |
gerr |
if |
resid |
if |
R2 |
coefficient of determination (Doksum and Samarov (1995)) |
MSE |
mean squared error |
training.MSE |
Known mean squared error against the training outcomes,
retained independently of any evaluation-outcome override; |
MAE |
mean absolute error |
MAPE |
mean absolute percentage error |
CORR |
absolute value of Pearson's correlation coefficient |
SIGN |
fraction of observations where fitted and observed values agree in sign |
Smooth-coefficient moment solves use their own bounded numerical ridging;
see npreg for its Seifert–Gasser motivation.
The smooth-coefficient covariance is a separate moment calculation, not
the ordinary-regression residual-normalized sandwich.
The smooth-coefficient model lets slopes vary with conditioning
variables, typically written
. The functions estimate the
coefficient functions using mixed-data kernel
smoothing over , with the reported fitted values obtained by
combining the estimated coefficient functions with the corresponding
columns of .
For book-length derivations, see Li and Racine (2007), Chapter 9 Additive and Smooth (Varying) Coefficient Semiparametric Models, especially Sections 9.3-9.3.4, and Racine (2019), Chapter 8 Semiparametric Conditional Mean Function Estimation, especially the varying-coefficient material.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available.
For practitioners who want the recommended automatic local-polynomial degree-and-bandwidth NOMAD route
without spelling out all LP tuning arguments,
npscoef(..., nomad=TRUE) and npscoefbw(..., nomad=TRUE)
expand missing settings to the same documented preset. Explicit
incompatible settings fail fast rather than being silently rewritten.
For plotting options for fitted smooth-coefficient objects and their
bandwidth objects, see plot.np.
Support for backfitted bandwidths is experimental and is limited in functionality. The code does not support asymptotic standard errors or out of sample estimates with backfitting.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Cai Z. (2007), “Trending time-varying coefficient time series models with serially correlated errors,” Journal of Econometrics, 136, 163-188.
Doksum, K. and A. Samarov (1995), “Nonparametric estimation of global functionals and a measure of the explanatory power of covariates in regression,” The Annals of Statistics, 23 1443-1473.
Hastie, T. and R. Tibshirani (1993), “Varying-coefficient models,” Journal of the Royal Statistical Society, B 55, 757-796.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2010), “Smooth varying-coefficient estimation and inference for qualitative and quantitative data,” Econometric Theory, 26, 1-31.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Li, Q. and D. Ouyang and J.S. Racine (2013), “Categorical semiparametric varying-coefficient models,” Journal of Applied Econometrics, 28, 551-589.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np,
bw.nrd, bw.SJ, hist,
npudens, npudist,
npudensbw, npscoefbw
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): n <- 250 x <- runif(n) z <- runif(n, min=-2, max=2) y <- x*exp(z)*(1.0+rnorm(n,sd = 0.2)) bw <- npscoefbw(y~x|z) model <- npscoef(bw) if (interactive()) plot(model) # EXAMPLE 1 (INTERFACE=DATA FRAME): n <- 250 x <- runif(n) z <- runif(n, min=-2, max=2) y <- x*exp(z)*(1.0+rnorm(n,sd = 0.2)) bw <- npscoefbw(xdat=x, ydat=y, zdat=z) model <- npscoef(bw) if (interactive()) plot(model) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): n <- 250 x <- runif(n) z <- runif(n, min=-2, max=2) y <- x*exp(z)*(1.0+rnorm(n,sd = 0.2)) bw <- npscoefbw(y~x|z) model <- npscoef(bw) if (interactive()) plot(model) # EXAMPLE 1 (INTERFACE=DATA FRAME): n <- 250 x <- runif(n) z <- runif(n, min=-2, max=2) y <- x*exp(z)*(1.0+rnorm(n,sd = 0.2)) bw <- npscoefbw(xdat=x, ydat=y, zdat=z) model <- npscoef(bw) if (interactive()) plot(model) ## End(Not run)
npscoefbw computes a bandwidth object for a smooth
coefficient kernel regression estimate of a one (1) dimensional
dependent variable on
-variate explanatory data, using the model
where
given training points (consisting of explanatory data and dependent
data), and a bandwidth specification, which can be a rbandwidth
object, or a bandwidth vector, bandwidth type and kernel type.
npscoefbw(...) ## S3 method for class 'formula' npscoefbw(formula, data, subset, na.action, call, ...) ## Default S3 method: npscoefbw(xdat = stop("invoked without data 'xdat'"), ydat = stop("invoked without data 'ydat'"), zdat = NULL, bws, backfit.iterate, backfit.maxiter, backfit.tol, bandwidth.compute = TRUE, basis, bernstein.basis, bwmethod, bwscaling, bwtype, ckerbound, ckerlb, ckerorder, ckertype, ckerub, cv.iterate, cv.num.iterations, degree, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, nmulti, nomad.remin = FALSE, powell.remin = TRUE, okertype, optim.abstol, optim.maxattempts, optim.maxit, optim.method, optim.reltol, random.seed, regtype, ukertype, scale.factor.init.lower = 0.1, scale.factor.init.upper = 2.0, scale.factor.init = 0.5, lbd.init = 0.5, hbd.init = 1.5, dfac.init = 1.0, scale.factor.search.lower = NULL, ..., nomad.opts = list()) ## S3 method for class 'scbandwidth' npscoefbw(xdat = stop("invoked without data 'xdat'"), ydat = stop("invoked without data 'ydat'"), zdat = NULL, bws, backfit.iterate = FALSE, backfit.maxiter = 100, backfit.tol = .Machine$double.eps, bandwidth.compute = TRUE, cv.iterate = FALSE, cv.num.iterations = 1, nmulti, optim.abstol = .Machine$double.eps, optim.maxattempts = 10, optim.maxit = 500, optim.method = c("Nelder-Mead", "BFGS", "CG"), optim.reltol = sqrt(.Machine$double.eps), random.seed = 42, scale.factor.init.lower = 0.1, scale.factor.init.upper = 2.0, scale.factor.init = 0.5, lbd.init = 0.5, hbd.init = 1.5, dfac.init = 1.0, scale.factor.search.lower = NULL, ..., nomad.opts = list())npscoefbw(...) ## S3 method for class 'formula' npscoefbw(formula, data, subset, na.action, call, ...) ## Default S3 method: npscoefbw(xdat = stop("invoked without data 'xdat'"), ydat = stop("invoked without data 'ydat'"), zdat = NULL, bws, backfit.iterate, backfit.maxiter, backfit.tol, bandwidth.compute = TRUE, basis, bernstein.basis, bwmethod, bwscaling, bwtype, ckerbound, ckerlb, ckerorder, ckertype, ckerub, cv.iterate, cv.num.iterations, degree, degree.select = c("manual", "coordinate", "exhaustive"), search.engine = c("nomad+powell", "cell", "nomad"), nomad = FALSE, nomad.nmulti = 0L, degree.min = NULL, degree.max = NULL, degree.start = NULL, degree.restarts = 0L, degree.max.cycles = 20L, degree.verify = FALSE, nmulti, nomad.remin = FALSE, powell.remin = TRUE, okertype, optim.abstol, optim.maxattempts, optim.maxit, optim.method, optim.reltol, random.seed, regtype, ukertype, scale.factor.init.lower = 0.1, scale.factor.init.upper = 2.0, scale.factor.init = 0.5, lbd.init = 0.5, hbd.init = 1.5, dfac.init = 1.0, scale.factor.search.lower = NULL, ..., nomad.opts = list()) ## S3 method for class 'scbandwidth' npscoefbw(xdat = stop("invoked without data 'xdat'"), ydat = stop("invoked without data 'ydat'"), zdat = NULL, bws, backfit.iterate = FALSE, backfit.maxiter = 100, backfit.tol = .Machine$double.eps, bandwidth.compute = TRUE, cv.iterate = FALSE, cv.num.iterations = 1, nmulti, optim.abstol = .Machine$double.eps, optim.maxattempts = 10, optim.maxit = 500, optim.method = c("Nelder-Mead", "BFGS", "CG"), optim.reltol = sqrt(.Machine$double.eps), random.seed = 42, scale.factor.init.lower = 0.1, scale.factor.init.upper = 2.0, scale.factor.init = 0.5, lbd.init = 0.5, hbd.init = 1.5, dfac.init = 1.0, scale.factor.search.lower = NULL, ..., nomad.opts = list())
These arguments identify the smooth-coefficient data, formula interface, and whether bandwidths are supplied or computed.
bandwidth.compute |
a logical value which specifies whether to do a numerical search for
bandwidths or not. If set to |
bws |
a bandwidth specification. This can be set as a |
call |
the original function call. This is passed internally by
|
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
formula |
a symbolic description of variables on which bandwidth selection is to be performed. The details of constructing a formula are described below. |
na.action |
a function which indicates what should happen when the data contain
|
subset |
an optional vector specifying a subset of observations to be used in the fitting process. |
xdat |
a |
ydat |
a one (1) dimensional numeric or integer vector of dependent data, each
element |
zdat |
an optionally specified |
These arguments control automatic local-polynomial degree search.
degree.max |
optional scalar or integer vector giving upper bounds for automatic
degree search when |
degree.max.cycles |
positive integer giving the maximum number of coordinate-search
sweeps over the degree vector. Ignored for |
degree.min |
optional scalar or integer vector giving lower bounds for automatic
degree search when |
degree.restarts |
non-negative integer giving the number of additional deterministic
coordinate-search restarts. Ignored for |
degree.select |
character string controlling local-polynomial degree handling when
|
degree.start |
optional starting degree vector for automatic coordinate search. If
omitted, the search starts from the degree-zero local-constant
baseline on the continuous |
degree.verify |
logical value indicating whether a coordinate-search solution should
be exhaustively verified over the admissible degree grid after the
heuristic phase completes. Available only for
|
These controls tune the optional smooth-coefficient backfitting iterations.
backfit.iterate |
boolean value specifying whether or not to iterate evaluations of
the smooth coefficient estimator, for extra accuracy, during the
cross-validated backfitting procedure. Defaults to |
backfit.maxiter |
integer specifying the maximum number of times to iterate the
evaluation of the smooth coefficient estimator in the attempt to
obtain the desired accuracy. Defaults to |
backfit.tol |
tolerance to determine convergence of iterated evaluations of the
smooth coefficient estimator. Defaults to |
These arguments choose the selection criterion and the way continuous bandwidths are represented.
bwmethod |
which method was used to select bandwidths. |
bwscaling |
a logical value that when set to |
bwtype |
character string used for the continuous variable bandwidth type,
specifying the type of bandwidth provided. Defaults to
|
These controls set categorical search starts.
dfac.init |
deterministic fixed-bandwidth start factor for ordered and
unordered categorical coordinates. Used only when
|
hbd.init |
upper bound for random fixed-bandwidth start factors for ordered
and unordered categorical coordinates. Used only when
|
lbd.init |
lower bound for random fixed-bandwidth start factors for ordered
and unordered categorical coordinates. Used only when
|
These controls choose and parameterize bounded support for continuous kernels.
ckerbound |
character string controlling continuous-kernel support handling.
Can be set as |
ckerlb |
numeric scalar/vector of lower bounds for continuous variables used
when |
ckerub |
numeric scalar/vector of upper bounds for continuous variables used
when |
These controls define deterministic and random continuous scale-factor starts and the lower admissibility floor for fixed-bandwidth search.
scale.factor.init |
deterministic initial scale factor for continuous fixed-bandwidth
search. Defaults to |
scale.factor.init.lower |
lower endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.init.upper |
upper endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.search.lower |
optional nonnegative scalar giving the hard lower admissibility
bound for continuous fixed-bandwidth search candidates. Defaults to
|
These controls tune iterative cross-validation behavior.
cv.iterate |
boolean value specifying whether or not to perform iterative,
cross-validated backfitting on the data. See details for limitations
of the backfitting procedure. Defaults to |
cv.num.iterations |
integer specifying the number of times to iterate the backfitting
process over all covariates. Defaults to |
These controls choose continuous, unordered, and ordered kernels.
ckerorder |
numeric value specifying kernel order (one of
|
ckertype |
character string used to specify the continuous kernel type.
Can be set as |
okertype |
character string used to specify the ordered categorical kernel type.
Can be set as |
ukertype |
character string used to specify the unordered categorical kernel type.
Can be set as |
These arguments control the local-polynomial estimator, basis, and fixed degree specification.
basis |
for |
bernstein.basis |
for |
degree |
for |
regtype |
a character string specifying local smoothing type for the |
These arguments control the optional NOMAD direct-search route for local-polynomial degree and bandwidth search.
nomad |
logical or character shortcut for the recommended automatic local-polynomial
NOMAD route. When |
nomad.nmulti |
non-negative integer controlling the inner
the native crs NOMAD C API multistart count used within each outer
NOMAD restart when |
nomad.opts |
optional named list of native NOMAD parameters forwarded to the
crs NOMAD C API for NOMAD-backed bandwidth searches.
|
nomad.remin |
logical flag controlling the optional second NOMAD hot start. When
|
search.engine |
character string controlling the automatic local-polynomial search
backend when |
These controls set search restart behavior.
nmulti |
integer number of times to restart the process of finding extrema of
the cross-validation function from different (random) initial
points. Defaults to |
powell.remin |
compatibility argument shared with bandwidth families that use the Powell
direction-set solver. Smooth-coefficient fixed-degree and post-NOMAD
refinement use R |
These arguments control outer optimization behavior for the semiparametric search.
optim.abstol |
the absolute convergence tolerance used by |
optim.maxattempts |
maximum number of attempts taken trying to achieve successful
convergence in |
optim.maxit |
maximum number of iterations used by |
optim.method |
method used by the default method is an implementation of that of Nelder and Mead (1965), that uses only function values and is robust but relatively slow. It will work reasonably well for non-differentiable functions. method method |
optim.reltol |
relative convergence tolerance used by |
random.seed |
an integer used to seed R's random number generator. This ensures replicability of the numerical search. Defaults to 42. |
These arguments collect remaining controls passed through S3 methods.
... |
additional arguments supplied to specify the regression type, bandwidth type, kernel types, selection methods, and so on, detailed below. |
Formula bandwidth objects retain the prepared training sample (after alignment,
subsetting and missing-value handling) and the resolved missing-value policy.
Later refits use that sample even if constructor variables are rebound.
Supplying explicit training data to the estimator replaces the training data;
evaluation via newdata does not. Retention requires storage proportional
to the sample size times the number of variables, not a pairwise weight matrix.
Older saved objects without this retained state still rely on their original
data bindings; rebuild their bandwidth object from the intended data before
changing those bindings. User-defined transformation and missing-value
functions should not rely on subsequently modified closure state.
The scale.factor.* controls are dimensionless search
controls. The package converts scale factors to bandwidths using the
estimator-specific scaling encoded in the bandwidth object, including
kernel order and the number of continuous variables relevant for the
estimator. Users should not pre-multiply these controls by sample-size
or standard-deviation factors.
scale.factor.init controls the deterministic first search
start when that control is exposed. scale.factor.init.lower
and scale.factor.init.upper define the random multistart
interval when exposed. scale.factor.search.lower is the lower
admissibility bound for continuous fixed-bandwidth search candidates.
The effective first start is max(scale.factor.init,
scale.factor.search.lower) when both controls are present, and the
effective random-start lower endpoint is
max(scale.factor.init.lower, scale.factor.search.lower).
scale.factor.init.upper must be at least that effective lower
endpoint; the package errors rather than silently expanding the user's
interval.
When scale.factor.search.lower is NULL, an existing
bandwidth object's stored floor is inherited when available;
otherwise the package default 0.1 is used. Explicit bandwidths
supplied for storage with bandwidth.compute = FALSE are not
rewritten by the search floor.
Categorical search-start controls such as dfac.init,
lbd.init, and hbd.init have separate semantics and are
not affected by scale.factor.search.lower.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot, plot.np for plotting options.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
npscoefbw implements a variety of methods for semiparametric
regression on multivariate (-variate) explanatory data defined
over a set of possibly continuous data. The approach is based on Li and
Racine (2003) who employ ‘generalized product kernels’ that
admit a mix of continuous and discrete data types.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating the
density at the point . Generalized nearest-neighbor bandwidths change
with the point at which the density is estimated, . Fixed bandwidths
are constant over the support of .
npscoefbw may be invoked either with a formula-like
symbolic description of variables on which bandwidth selection is to be
performed or through a simpler interface whereby data is passed
directly to the function via the xdat, ydat, and
zdat parameters. Use of these two interfaces is mutually
exclusive.
Data contained in the data frame xdat may be continuous and in
zdat may be of mixed type. Data can be entered in an arbitrary
order and data types will be detected automatically by the routine (see
np for details).
Data for which bandwidths are to be estimated may be specified
symbolically. A typical description has the form dependent
data ~ parametric explanatory data
| nonparametric explanatory data, where
dependent data is a univariate response, and
parametric explanatory data and
nonparametric explanatory data are both series of
variables specified by name, separated by the separation character
'+'. For example, y1 ~ x1 + x2 | z1 specifies that the
bandwidth object for the smooth coefficient model with response
y1, linear parametric regressors x1 and x2, and
nonparametric regressor (that is, the slope-changing variable)
z1 is to be estimated. See below for further examples. In the
case where the nonparametric (slope-changing) variable is not
specified, it is assumed to be the same as the parametric variable.
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth order Gaussian and Epanechnikov kernels, and the uniform kernel. Unordered discrete data types use a variation on Aitchison and Aitken's (1976) kernel, while ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
Setting nomad=TRUE is a convenience preset for this automatic
LP route, not a generic optimizer alias. For smooth coefficient
regression it expands any missing values to the equivalent long-form
call
npscoefbw(...,
regtype = "lp",
search.engine = "nomad+powell",
degree.select = "coordinate",
bernstein.basis = TRUE,
degree.min = 0L,
degree.max = 10L,
degree.verify = FALSE,
bwtype = "fixed")
Compatible explicit tuning arguments are respected. Incompatible
explicit settings fail fast so the shortcut never silently changes
user-selected semantics.
The character value nomad="auto" applies the same LP shortcut
but leaves search.engine and degree.select eligible for
data-driven resolution when both were not supplied explicitly: scalar
continuous degree searches use the exhaustive degree-grid route, while
higher-dimensional degree searches keep the compatibility
"nomad+powell" route.
Explicit search.engine or degree.select choices are
honored.
When regtype="lp" and degree.select != "manual",
npscoefbw can jointly determine the zdat-side local
polynomial degree vector together with the associated bandwidth
coordinates. With search.engine="cell", the criterion is
profiled over the admissible degree grid using cached
coordinate-wise or exhaustive search together with repeated
fixed-degree bandwidth solves. With search.engine="nomad" or
"nomad+powell", the criterion is optimized directly over the
joint degree/bandwidth space using the native crs NOMAD C API.
For this family, the compatibility value "nomad+powell" then
performs one family-native R optim hot start using
optim.method and keeps the better of the direct NOMAD and refined
answers. This polynomial-adaptive joint-search route is motivated by
Hall and Racine (2015). When bernstein.basis is not explicitly
supplied, the automatic search route defaults to
bernstein.basis=TRUE for numerical stability.
if bwtype is set to fixed, an object containing
bandwidths (or scale factors if bwscaling = TRUE) is
returned. If it is set to generalized_nn or adaptive_nn,
then instead the th nearest neighbors are returned for the
continuous variables while the discrete kernel bandwidths are returned
for the discrete variables. Bandwidths are stored in a vector under the
component name bw. Backfitted bandwidths are stored under the
component name bw.fitted.
The functions predict, summary, and
plot support
objects of this class.
The smooth-coefficient moment solves use their own bounded additive
numerical-ridge policy. For the Seifert–Gasser motivation for ridging,
see npreg; this does not impose its ordinary-regression
uncertainty formula on smooth-coefficient estimation.
npscoefbw selects bandwidths for the smooth-coefficient model
. The selected bandwidths control
the mixed-data smoothing over used to estimate the coefficient
functions .
For book-length derivations, see Li and Racine (2007), Chapter 9 Additive and Smooth (Varying) Coefficient Semiparametric Models, especially Sections 9.3-9.3.4, and Racine (2019), Chapter 8 Semiparametric Conditional Mean Function Estimation.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Caution: multivariate data-driven bandwidth selection methods are, by
their nature, computationally intensive. Virtually all methods
require dropping the th observation from the data set,
computing an object, repeating this for all observations in the
sample, then averaging each of these leave-one-out estimates for a
given value of the bandwidth vector, and only then repeating
this a large number of times in order to conduct multivariate
numerical minimization/maximization. Furthermore, due to the potential
for local minima/maxima, restarting this procedure a large
number of times may often be necessary. This can be frustrating for
users possessing large datasets. For exploratory purposes, you may
wish to override the default search tolerances, say, setting
optim.reltol=.1 and conduct multistarting (the default is to restart
min(2,ncol(zdat)) times). Once the procedure terminates, you can restart
search with default tolerances using those bandwidths obtained from
the less rigorous search (i.e., set bws=bw on subsequent calls
to this routine where bw is the initial bandwidth object). A
version of this package using the Rmpi wrapper is under
development that allows one to deploy this software in a clustered
computing environment to facilitate computation involving large
datasets.
Support for backfitted bandwidths is experimental and is limited in functionality. The code does not support asymptotic standard errors or out of sample estimates with backfitting.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Cai Z. (2007), “Trending time-varying coefficient time series models with serially correlated errors,” Journal of Econometrics, 136, 163-188.
Hastie, T. and R. Tibshirani (1993), “Varying-coefficient models,” Journal of the Royal Statistical Society, B 55, 757-796.
Hall, P. and J.S. Racine (2015), “Infinite Order Cross-Validated Local Polynomial Regression,” Journal of Econometrics, 185, 510-525.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2010), “Smooth varying-coefficient estimation and inference for qualitative and quantitative data,” Econometric Theory, 26, 1-31.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Li, Q. and D. Ouyang and J.S. Racine (2013), “Categorical semiparametric varying-coefficient models,” Journal of Applied Econometrics, 28, 551-589.
Li, A. and Q. Li and J.S. Racine (under revision), “Boundary Adjusted, Polynomial Adaptive, Nonparametric Kernel Conditional Density Estimation,” Econometric Reviews.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np
npregbw, npreg
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): set.seed(42) n <- 100 x <- runif(n) z <- runif(n, min=-2, max=2) y <- x*exp(z)*(1.0+rnorm(n,sd = 0.2)) bw <- npscoefbw(formula=y~x|z) summary(bw) # EXAMPLE 1 (INTERFACE=DATA FRAME): n <- 100 x <- runif(n) z <- runif(n, min=-2, max=2) y <- x*exp(z)*(1.0+rnorm(n,sd = 0.2)) bw <- npscoefbw(xdat=x, ydat=y, zdat=z) summary(bw) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): set.seed(42) n <- 100 x <- runif(n) z <- runif(n, min=-2, max=2) y <- x*exp(z)*(1.0+rnorm(n,sd = 0.2)) bw <- npscoefbw(formula=y~x|z) summary(bw) # EXAMPLE 1 (INTERFACE=DATA FRAME): n <- 100 x <- runif(n) z <- runif(n, min=-2, max=2) y <- x*exp(z)*(1.0+rnorm(n,sd = 0.2)) bw <- npscoefbw(xdat=x, ydat=y, zdat=z) summary(bw) ## End(Not run)
npsdeptest implements the consistent metric entropy test of
nonlinear serial dependence as described in Granger, Maasoumi and
Racine (2004).
npsdeptest(data = NULL, lag.num = 1, method = c("integration","summation"), bootstrap = TRUE, B = 399, random.seed = 42)npsdeptest(data = NULL, lag.num = 1, method = c("integration","summation"), bootstrap = TRUE, B = 399, random.seed = 42)
These arguments identify the data series, lag count, and statistic variant.
data |
a vector containing the variable that can be of type
|
lag.num |
an integer value specifying the maximum number of lags to
use. Defaults to |
method |
a character string used to specify whether to compute the integral
version or the summation version of the statistic. Can be set as
|
These arguments control bootstrap execution and reproducibility settings.
B |
an integer value specifying the number of bootstrap
replications to use. Defaults to |
bootstrap |
a logical value which specifies whether to conduct
the bootstrap test or not. If set to |
random.seed |
an integer used to seed R's random number generator. This is to ensure replicability. Defaults to 42. |
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
npsdeptest computes the nonparametric metric entropy
(normalized Hellinger of Granger, Maasoumi and Racine (2004)) for
testing for nonlinear serial dependence, . Default bandwidths are of the Kullback-Leibler
variety obtained via likelihood cross-validation.
The test may be applied to a raw data series or to residuals of user estimated models.
The summation version of this statistic may be numerically unstable
when data is sparse (the summation version involves division of
densities while the integration version involves differences). Warning
messages are produced should this occur (‘integration recommended’)
and should be heeded.
npsdeptest returns an object of type deptest with the
following components
Srho |
the statistic vector |
Srho.cumulant |
the cumulant statistic vector |
Srho.bootstrap.mat |
contains the bootstrap replications of
|
Srho.cumulant.bootstrap.mat |
contains the bootstrap
replications of |
P |
the P-value vector of the Srho statistic vector |
P.cumulant |
the P-value vector of the cumulant Srho statistic vector |
bootstrap |
a logical value indicating whether bootstrapping was performed |
boot.num |
number of bootstrap replications |
lag.num |
the number of lags |
bw.y |
the numeric vector of bandwidths for |
bw.y.lag |
the numeric vector of bandwidths for lagged
|
bw.joint |
the numeric matrix of bandwidths for |
summary supports object of type deptest.
The bootstrap upper-tail p-value is the proportion of bootstrap statistics greater than or equal to the observed statistic. Ties count as at least as extreme, giving the conservative tie convention for discrete statistics. This is the ordinary bootstrap proportion, without an add-one correction; a reported zero is possible with a finite number of replications.
npsdeptest applies the dependence-test idea to a time series by
comparing the joint law of current and lagged values with the product
of their marginal laws. The lag and bootstrap choices determine the
serial-dependence alternatives being probed and the null calibration.
For book-length background, see Li and Racine (2007), Chapter 13 Nonsmoothing Tests, especially Sections 13.4 and 13.5, and Chapter 12 Model Specification Tests for related distributional tests. For entropy and density context, see Racine (2019), Chapter 2.
The integration version uses deterministic tensor-product,
corrected composite trapezoidal quadrature. Along each axis the domain
extends eight relevant bandwidths beyond the observed support and uses
two evaluation points per smallest relevant bandwidth. A registered
native callback evaluates the Gaussian marginal and joint densities in
bounded tiles, so package-owned working memory does not grow as a dense
sample-by-quadrature array. The integration version is generally more
computationally demanding than summation, but avoids the density
division that can make the summation statistic unstable.
The summation version fuses both marginal density sums and the
joint density sum in one registered native pass with constant auxiliary
storage. Bootstrap samples remain ordered index resamples: marginal
counts alone cannot represent the lag pairs used by the statistic.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Granger, C.W. and E. Maasoumi and J.S. Racine (2004), “A dependence metric for possibly nonlinear processes”, Journal of Time Series Analysis, 25, 649-669.
np.kernels, np.options, plot
npdeptest,npdeneqtest,npsymtest,npunitest
## Not run: set.seed(1234) ## A function to create a time series ar.series <- function(phi,epsilon) { n <- length(epsilon) series <- numeric(n) series[1] <- epsilon[1]/(1-phi) for(i in 2:n) { series[i] <- phi*series[i-1] + epsilon[i] } return(series) } n <- 100 ## Stationary persistent time-series yt <- ar.series(0.95,rnorm(n)) npsdeptest(yt,lag.num=2,B=99,method="summation") if (interactive()) Sys.sleep(5) ## Stationary independent time-series yt <- ar.series(0.0,rnorm(n)) npsdeptest(yt,lag.num=2,B=99,method="summation") ## Stationary persistent time-series yt <- ar.series(0.95,rnorm(n)) npsdeptest(yt,lag.num=2,B=99,method="integration") if (interactive()) Sys.sleep(5) ## Stationary independent time-series yt <- ar.series(0.0,rnorm(n)) npsdeptest(yt,lag.num=2,B=99,method="integration") ## End(Not run)## Not run: set.seed(1234) ## A function to create a time series ar.series <- function(phi,epsilon) { n <- length(epsilon) series <- numeric(n) series[1] <- epsilon[1]/(1-phi) for(i in 2:n) { series[i] <- phi*series[i-1] + epsilon[i] } return(series) } n <- 100 ## Stationary persistent time-series yt <- ar.series(0.95,rnorm(n)) npsdeptest(yt,lag.num=2,B=99,method="summation") if (interactive()) Sys.sleep(5) ## Stationary independent time-series yt <- ar.series(0.0,rnorm(n)) npsdeptest(yt,lag.num=2,B=99,method="summation") ## Stationary persistent time-series yt <- ar.series(0.95,rnorm(n)) npsdeptest(yt,lag.num=2,B=99,method="integration") if (interactive()) Sys.sleep(5) ## Stationary independent time-series yt <- ar.series(0.0,rnorm(n)) npsdeptest(yt,lag.num=2,B=99,method="integration") ## End(Not run)
npseed is a function which sets the random seed in the
np C backend, resetting the random number generator.
npseed(seed)npseed(seed)
Seed value used to reset the package C backend random number generator.
seed |
a single finite numeric value that is representable as a non-negative integer after applying |
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
npseed provides an interface for setting the random seed (and
resetting the random number generator) used
by np. The random number generator is used during the
bandwidth search procedure to set the search starting point, and in
subsequent searches when using multistarting, to avoid being trapped
in local minima if the objective function is not globally concave.
Calling npseed will only affect the numerical search if it is
performed by the C backend. The affected functions include:
npudensbw, npcdensbw,
npregbw, npplregbw, npqreg,
npcmstest (via npregbw),
npqcmstest (via npregbw),
npsigtest (via npregbw).
Invalid inputs such as missing values, non-finite values, non-scalars, and values that cannot be represented as integers are rejected with an explicit error.
None.
This method currently only supports objects from the np library.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
np.kernels, np.options, plot
set.seed
npseed(712) x <- runif(10) y <- x + rnorm(10, sd = 0.1) bw <- npregbw(y~x)npseed(712) x <- runif(10) y <- x + rnorm(10, sd = 0.1) bw <- npregbw(y~x)
Constructs hat operators for semiparametric estimators so that fitted values or bootstrap draws can be computed by matrix application in one step. These interfaces are currently experimental.
npindexhat(bws, txdat = stop("training data 'txdat' missing"), exdat = txdat, y = NULL, output = c("matrix", "apply", "constraint"), s = 0L, fd.step = NULL, ...) npplreghat(bws, txdat = stop("training data 'txdat' missing"), tzdat = stop("training data 'tzdat' missing"), exdat = txdat, ezdat = tzdat, y = NULL, output = c("apply", "matrix", "constraint"), ...) npscoefhat(bws, txdat = stop("training data 'txdat' missing"), tzdat = NULL, exdat = txdat, ezdat = tzdat, y = NULL, output = c("matrix", "apply", "constraint"), ridge = 0, iterate = FALSE, leave.one.out = FALSE, ...)npindexhat(bws, txdat = stop("training data 'txdat' missing"), exdat = txdat, y = NULL, output = c("matrix", "apply", "constraint"), s = 0L, fd.step = NULL, ...) npplreghat(bws, txdat = stop("training data 'txdat' missing"), tzdat = stop("training data 'tzdat' missing"), exdat = txdat, ezdat = tzdat, y = NULL, output = c("apply", "matrix", "constraint"), ...) npscoefhat(bws, txdat = stop("training data 'txdat' missing"), tzdat = NULL, exdat = txdat, ezdat = tzdat, y = NULL, output = c("matrix", "apply", "constraint"), ridge = 0, iterate = FALSE, leave.one.out = FALSE, ...)
These arguments identify the fitted bandwidth object, training data, and evaluation data.
bws |
A fitted bandwidth object. |
exdat |
Evaluation |
txdat |
Training |
These arguments control operator output, derivative selection, finite-difference compatibility, and apply-mode right-hand sides.
fd.step |
Compatibility argument for |
output |
Either |
s |
For |
y |
Optional response vector or matrix for apply mode. For |
These arguments supply the additional z data used by partially linear and smooth-coefficient models.
ezdat |
Evaluation |
tzdat |
Training |
These arguments control smooth-coefficient iteration, leave-one-out behavior, and ridge stabilization.
iterate |
Logical; |
leave.one.out |
Logical; leave-one-out kernel weights for |
ridge |
Base ridge term for local linear solves in |
Reserved for future extensions.
... |
Reserved for future extensions. |
For local-constant and degree-zero local-polynomial npindexhat means,
every finite nonzero kernel-weight sum is used without an epsilon floor.
An explicitly supplied external evaluation row with all computed weights zero
returns NA with a warning, preserving its position in matrix and applied
outputs. This does not distinguish geometric absence from weights that have
underflowed. Signed cancellation and nonfinite normalizing sums are errors.
Required internal and bootstrap computations do not omit undefined rows or
replications.
These operators are intended for fixed- workflows such as one-shot wild
bootstrap calculations where many response draws are projected through the same
operator. The implementation is intentionally conservative: class and scalar
argument contracts are validated explicitly, and unsupported iterative
npscoefhat() paths fail fast. npscoefhat() inherits
regtype/LP-basis controls from the supplied scbandwidth
object. For non-fixed npscoef bootstrap plotting, these operators can
support a frozen approximation, but they do not remove the need to recompute
the local smooth-coefficient vector itself for each resample: the local
weighted systems depend on the resample weights/counts at each evaluation
point, so unlike npplreg there is no single global coefficient vector
to update once per draw.
Method-specific argument map:
npindexhat() uses s; fd.step is accepted for compatibility but the current s=1 route uses the canonical exact derivative operator;
npplreghat() and npscoefhat() use tzdat/ezdat;
npscoefhat() additionally uses ridge, iterate, and
leave.one.out.
For output = "constraint", the selected operator is first defined exactly
as in output = "matrix" and the return value is t(H) * y. This is
a convenience route for constrained quadratic-programming workflows; it does
not solve a constrained estimation problem and it does not change the meaning
of output = "apply".
If output = "matrix", returns a hat matrix . If
output = "apply", returns (or for matrix
right-hand-side input). If output = "constraint", returns the
constraint design matrix as represented in R by
t(H) * y.
## Not run: set.seed(42) n <- 100 x <- runif(n) z <- runif(n) y <- sin(2*pi*x) + 0.5 * z + rnorm(n, sd = 0.1) tx <- data.frame(x = x) tz <- data.frame(z = z) ibw <- npindexbw(xdat = data.frame(x, x2 = x^2), ydat = y, bws = c(0.5, 1.0, 1.0), bandwidth.compute = FALSE) iH <- npindexhat(bws = ibw, txdat = data.frame(x, x2 = x^2), output = "matrix") iH.fitted <- iH iA <- npindexhat(bws = ibw, txdat = data.frame(x, x2 = x^2), y = y, output = "constraint") all.equal(iA, t(iH) * y) ifit <- npindex(bws = ibw, txdat = data.frame(x, x2 = x^2), tydat = y) head(cbind(fitted(ifit), iH.fitted), n = 2L) pbw <- npplregbw(xdat = tx, zdat = tz, ydat = y, bws = matrix(c(0.2, 0.2), nrow = 2L, ncol = 1L), bandwidth.compute = FALSE) pH <- npplreghat(bws = pbw, txdat = tx, tzdat = tz, output = "matrix") pH.fitted <- pH pfit <- npplreg(bws = pbw, txdat = tx, tydat = y, tzdat = tz) head(cbind(fitted(pfit), pH.fitted), n = 2L) sbw <- npscoefbw(xdat = tx, zdat = tz, ydat = y, bws = 0.2, bandwidth.compute = FALSE) sH <- npscoefhat(bws = sbw, txdat = tx, tzdat = tz, output = "matrix", iterate = FALSE) sH.fitted <- sH sfit <- npscoef(bws = sbw, txdat = tx, tydat = y, tzdat = tz, iterate = FALSE) head(cbind(fitted(sfit), sH.fitted), n = 2L) ## End(Not run)## Not run: set.seed(42) n <- 100 x <- runif(n) z <- runif(n) y <- sin(2*pi*x) + 0.5 * z + rnorm(n, sd = 0.1) tx <- data.frame(x = x) tz <- data.frame(z = z) ibw <- npindexbw(xdat = data.frame(x, x2 = x^2), ydat = y, bws = c(0.5, 1.0, 1.0), bandwidth.compute = FALSE) iH <- npindexhat(bws = ibw, txdat = data.frame(x, x2 = x^2), output = "matrix") iH.fitted <- iH iA <- npindexhat(bws = ibw, txdat = data.frame(x, x2 = x^2), y = y, output = "constraint") all.equal(iA, t(iH) * y) ifit <- npindex(bws = ibw, txdat = data.frame(x, x2 = x^2), tydat = y) head(cbind(fitted(ifit), iH.fitted), n = 2L) pbw <- npplregbw(xdat = tx, zdat = tz, ydat = y, bws = matrix(c(0.2, 0.2), nrow = 2L, ncol = 1L), bandwidth.compute = FALSE) pH <- npplreghat(bws = pbw, txdat = tx, tzdat = tz, output = "matrix") pH.fitted <- pH pfit <- npplreg(bws = pbw, txdat = tx, tydat = y, tzdat = tz) head(cbind(fitted(pfit), pH.fitted), n = 2L) sbw <- npscoefbw(xdat = tx, zdat = tz, ydat = y, bws = 0.2, bandwidth.compute = FALSE) sH <- npscoefhat(bws = sbw, txdat = tx, tzdat = tz, output = "matrix", iterate = FALSE) sH.fitted <- sH sfit <- npscoef(bws = sbw, txdat = tx, tydat = y, tzdat = tz, iterate = FALSE) head(cbind(fitted(sfit), sH.fitted), n = 2L) ## End(Not run)
npsigtest implements a consistent test of significance of an
explanatory variable(s) in a nonparametric regression setting that is
analogous to a simple -test (-test) in a parametric
regression setting. The test is based on Racine, Hart, and Li (2006)
and Racine (1997).
npsigtest(bws, ..., B = 399) ## S3 method for class 'formula' npsigtest(bws, data = NULL, ...) ## S3 method for class 'npregression' npsigtest(bws, ...) ## Default S3 method: npsigtest(bws, xdat, ydat, ...) ## S3 method for class 'rbandwidth' npsigtest(bws, xdat = stop("data xdat missing"), ydat = stop("data ydat missing"), B = 399, boot.method = c("iid","wild","wild-rademacher","pairwise"), boot.type = c("I","II"), pivot=TRUE, joint=FALSE, index = seq_len(ncol(xdat)), random.seed = 42, ...)npsigtest(bws, ..., B = 399) ## S3 method for class 'formula' npsigtest(bws, data = NULL, ...) ## S3 method for class 'npregression' npsigtest(bws, ...) ## Default S3 method: npsigtest(bws, xdat, ydat, ...) ## S3 method for class 'rbandwidth' npsigtest(bws, xdat = stop("data xdat missing"), ydat = stop("data ydat missing"), B = 399, boot.method = c("iid","wild","wild-rademacher","pairwise"), boot.type = c("I","II"), pivot=TRUE, joint=FALSE, index = seq_len(ncol(xdat)), random.seed = 42, ...)
These arguments identify the bandwidth object, formula/data interface, and explicit data inputs.
bws |
a bandwidth specification. This can be set as a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object coercible to
a data frame by |
xdat |
a |
ydat |
a one (1) dimensional numeric or integer vector of dependent data,
each element |
These arguments control bootstrap execution, tested effects, and reproducibility settings.
boot.method |
a character string used to specify the bootstrap method for
determining the null distribution. |
B |
an integer value specifying the number of bootstrap replications to
use. Defaults to |
boot.type |
a character string specifying whether to use a ‘Bootstrap I’ or
‘Bootstrap II’ method (see Racine, Hart, and Li (2006) for
details). The ‘Bootstrap II’ method re-runs cross-validation for
each bootstrap replication and uses the new cross-validated
bandwidth for variable |
index |
a vector of indices for the columns of |
joint |
a logical value which specifies whether to conduct a joint test or
individual test. This is to be used in conjunction with |
pivot |
a logical value specifying whether to studentize the statistic.
The default, |
random.seed |
an integer used to seed R's random number generator. This is to ensure replicability. Defaults to 42. |
Further arguments are passed to the bandwidth-selection routines used by the test.
... |
additional arguments supplied to specify the bandwidth type, kernel types, selection methods, and so on, detailed below. |
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
npsigtest implements a variety of methods for computing the
null distribution of the test statistic and allows the user to
investigate the impact of a variety of settings including whether or
not to pivot the statistic (pivot), whether pairwise
or residual resampling is to be used (boot.method), and whether
or not to recompute the bandwidths for the variables being tested
(boot.type), among others.
Eligible individual tests with fixed bandwidths, IID residual resampling, and a supported local-polynomial or categorical-only local-constant engine evaluate bootstrap statistics in bounded native tiles. This is an internal computational optimization: it preserves bootstrap draws, random-number state, statistics, and P-values. Joint tests and configurations outside the qualified set continue through the incumbent bootstrap loop.
The categorical statistic of Racine, Hart, and Li (2006) is the
unstandardized mean of squared finite-difference estimates, available
with pivot=FALSE. The default extends this construction by
studentizing categorical effects as well as continuous derivatives.
For a joint test, the statistic is the mean of squared componentwise
studentized effects over observations and tested predictors; it is not
an inverse-covariance Wald statistic.
Studentized statistics use the residual-normalized gradient sandwich
described in npreg, including its Ruppert et al. (1997)
residual correction. Each bootstrap response supplies its own normalized
training residuals; original-response errors are not held fixed across
replications. Categorical errors use paired endpoint influence
differences and retain endpoint covariance. Observed and bootstrap
calculations use the same producer and information-availability rules.
Eligible streamed calculations use the equivalent shared influence
calculation without retaining a full influence matrix. This does not
account for bandwidth or degree-selection uncertainty, or guarantee size
calibration for every sample and configuration.
Studentization can reduce size distortion, but does not uniformly improve finite-sample calibration or power. In sparse designs it can be conservative and have lower power than the unstandardized statistic; rejection frequencies from an oversized unstandardized test are not size-adjusted power comparisons. The choice of pivot does not replace assessment of the fitted model and available local information.
Identical categorical endpoints contribute zero without changing the
number of observations in the statistic's denominator. A native
certificate of identically zero paired influence has the same
interpretation; unavailable donor variance alone is not such a
certificate. Unordered
first-level reference rows have this property; ordered first-level rows
instead use a forward difference. An entire finite observed effect vector
that is exactly zero has statistic zero under the degenerate-zero
convention. Because bootstrap statistics are nonnegative, the inclusive
upper-tail P-value is one, without bootstrap fitting or bandwidth
reselection. The bootstrap statistics need not also be zero. This applies
to an individual test, or a joint test only when every tested observed
effect vanishes. A zero component of a mixed joint test stays in the
original denominator; it does not suppress the other components.
The test has no separate bandwidth-based full-smoothing detector. However,
the regression estimator's existing large-categorical-bandwidth
approximation can make a categorical contrast exactly zero near the
kernel's upper bandwidth bound, thereby triggering this convention.
This can produce a discontinuity in the P-value at that approximation's
cutoff; it is not evidence that the unapproximated contrast has vanished.
The test respects the estimator option np.largelambda, including
when the caller explicitly disables the approximation. Random draws are
advanced to preserve later tests' random-number streams.
Otherwise a required zero, negative, non-finite or unavailable standard error does not define studentization. An isolated zero effect with zero standard error within a nonzero effect vector is not covered by the degenerate-zero convention unless its influence is separately certified as identically zero. The test stops with an informative diagnostic; it does not insert a variance floor, discard rows or failed replications, or substitute an unstandardized statistic. This rule applies equally to continuous and categorical effects and to observed and bootstrap responses.
When the supplied bandwidth object has regtype="lp", every
tested continuous coordinate must have polynomial degree at least one.
A degree-zero local polynomial does not identify the derivative used by
this significance test, so the function stops before fitting or
bootstrap work and names the affected coordinate(s). If the degree was
selected by NOMAD, refit the bandwidth object with
degree.min=1. This restriction does not apply to an ordinary
regtype="lc" bandwidth object.
With nearest-neighbor bandwidths, repeated continuous values can give a
required radius of zero. In this case the test stops with the shared
nearest-neighbor diagnostic, identifying the affected variable and the
failing stage. This can occur during the unrestricted gradient or
null-model evaluation, before bootstrap replications. It is not a blanket
restriction on repeated values. Refit using bwtype="fixed" (the
default) to avoid this nearest-neighbor radius limitation; see
np.kernels.
The empirical upper-tail P-value counts bootstrap statistics equal to
the observed statistic, that is,
. Thus equality with the
bootstrap critical value is non-rejection. In particular, when
smoothing makes both the observed statistic and every bootstrap
statistic exactly zero, the returned P-value is one rather than zero.
Defaults are chosen so as to provide reasonable behaviour in a broad
range of settings and this involves a trade-off between computational
expense and finite-sample performance. However, the default
boot.type="I", though computationally expedient, can deliver a
test that can be slightly over-sized in small sample settings (e.g.
at the 5% level the test might reject 8% of the time for samples of
size for some data generating processes). If the default
setting (boot.type="I") delivers a P-value that is in the
neighborhood (i.e. slightly smaller) of any classical level
(e.g. 0.05) and you only have a modest amount of data, it might be
prudent to re-run the test using the more computationally intensive
boot.type="II" setting to confirm the original result. Note
also that boot.method="pairwise" is not recommended for the
multivariate local linear estimator due to substantial size
distortions that may arise in certain cases.
npsigtest returns an object of type
sigtest. summary supports sigtest objects. It
has the
following components:
In |
the vector of statistics |
P |
the vector of empirical upper-tail P-values for each statistic
in |
In.bootstrap |
contains a matrix of the bootstrap
replications of the vector |
pivot |
the requested logical pivot mode, |
pivot.effective |
a named logical vector recording the statistic actually used for each tested predictor. For a joint test all entries are identical. |
bootstrap.executed |
the number of bootstrap statistics actually computed for each test (zero for analytic non-rejection). |
bootstrap.reason |
the structural reason for skipping bootstrap
computation, or |
The bootstrap upper-tail p-value is the proportion of bootstrap statistics greater than or equal to the observed statistic. Ties count as at least as extreme, giving the conservative tie convention for discrete statistics. This is the ordinary bootstrap proportion, without an add-one correction; a reported zero is possible with a finite number of replications.
npsigtest assesses predictor relevance in nonparametric
regression by comparing the fitted unrestricted regression with
restrictions implied by excluding or smoothing over selected
regressors. Bootstrap choices trade computational cost against
finite-sample behavior.
For book-length background, see Li and Racine (2007), Chapter 12 Model Specification Tests, especially Sections 12.3 and 12.3.5, and Chapter 13 Nonsmoothing Tests, especially Section 13.3 where relevant. For the underlying conditional-mean setting, see Racine (2019), Chapter 6 Conditional Mean Function Estimation.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work
as intended on mixed data types and will coerce the data to the same
type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available.
Resampling can repeat continuous observations. With nearest-neighbor
bandwidths, an inherited count can then give a zero literal radius, even
when it was feasible in the preceding sample. Such a candidate is refused;
the resulting error is propagated, not converted to a successful replicate
or a different bootstrap method. Inspect ties and nearest-neighbor counts, or
explicitly select fixed bandwidths (bwtype="fixed") when this occurs.
Caution: bootstrap methods are, by their nature, computationally
intensive. This can be frustrating for users possessing large
datasets. For exploratory purposes, you may wish to override the
default number of bootstrap replications, say, setting them to
B=99. A version of this package using the Rmpi
wrapper is under development that allows one to deploy this software
in a clustered computing environment to facilitate computation
involving large datasets.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Racine, J.S., J. Hart, and Q. Li (2006), “Testing the significance of categorical predictor variables in nonparametric regression models,” Econometric Reviews, 25, 523-544.
Racine, J.S. (1997), “Consistent significance testing for nonparametric regression,” Journal of Business and Economic Statistics 15, 369-379.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we simulate 100 draws # from a DGP in which z, the first column of X, is an irrelevant # discrete variable set.seed(12345) n <- 100 z <- rbinom(n,1,.5) x1 <- rnorm(n) x2 <- runif(n,-2,2) y <- x1 + x2 + rnorm(n) # Next, we must compute bandwidths for our regression model. In this # case we conduct local linear regression. Note - this may take a few # minutes depending on the speed of your computer... bw <- npregbw(formula=y~factor(z)+x1+x2,regtype="ll",bwmethod="cv.aic") # We then compute a vector of tests corresponding to the columns of # X. Note - this may take a few minutes depending on the speed of your # computer... we have to generate the null distribution of the statistic # for each variable whose significance is being tested using 399 # bootstrap replications for each... npsigtest(bws=bw) # If you wished, you could conduct the test for, say, variables 1 and 3 # only, as in npsigtest(bws=bw,index=c(1,3)) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we simulate 100 # draws from a DGP in which z, the first column of X, is an irrelevant # discrete variable set.seed(12345) n <- 100 z <- rbinom(n,1,.5) x1 <- rnorm(n) x2 <- runif(n,-2,2) X <- data.frame(factor(z),x1,x2) y <- x1 + x2 + rnorm(n) # Next, we must compute bandwidths for our regression model. In this # case we conduct local linear regression. Note - this may take a few # minutes depending on the speed of your computer... bw <- npregbw(xdat=X,ydat=y,regtype="ll",bwmethod="cv.aic") # We then compute a vector of tests corresponding to the columns of # X. Note - this may take a few minutes depending on the speed of your # computer... we have to generate the null distribution of the statistic # for each variable whose significance is being tested using 399 # bootstrap replications for each... npsigtest(bws=bw) # If you wished, you could conduct the test for, say, variables 1 and 3 # only, as in npsigtest(bws=bw,index=c(1,3)) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we simulate 100 draws # from a DGP in which z, the first column of X, is an irrelevant # discrete variable set.seed(12345) n <- 100 z <- rbinom(n,1,.5) x1 <- rnorm(n) x2 <- runif(n,-2,2) y <- x1 + x2 + rnorm(n) # Next, we must compute bandwidths for our regression model. In this # case we conduct local linear regression. Note - this may take a few # minutes depending on the speed of your computer... bw <- npregbw(formula=y~factor(z)+x1+x2,regtype="ll",bwmethod="cv.aic") # We then compute a vector of tests corresponding to the columns of # X. Note - this may take a few minutes depending on the speed of your # computer... we have to generate the null distribution of the statistic # for each variable whose significance is being tested using 399 # bootstrap replications for each... npsigtest(bws=bw) # If you wished, you could conduct the test for, say, variables 1 and 3 # only, as in npsigtest(bws=bw,index=c(1,3)) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we simulate 100 # draws from a DGP in which z, the first column of X, is an irrelevant # discrete variable set.seed(12345) n <- 100 z <- rbinom(n,1,.5) x1 <- rnorm(n) x2 <- runif(n,-2,2) X <- data.frame(factor(z),x1,x2) y <- x1 + x2 + rnorm(n) # Next, we must compute bandwidths for our regression model. In this # case we conduct local linear regression. Note - this may take a few # minutes depending on the speed of your computer... bw <- npregbw(xdat=X,ydat=y,regtype="ll",bwmethod="cv.aic") # We then compute a vector of tests corresponding to the columns of # X. Note - this may take a few minutes depending on the speed of your # computer... we have to generate the null distribution of the statistic # for each variable whose significance is being tested using 399 # bootstrap replications for each... npsigtest(bws=bw) # If you wished, you could conduct the test for, say, variables 1 and 3 # only, as in npsigtest(bws=bw,index=c(1,3)) ## End(Not run)
npsymtest implements the consistent metric entropy test of
asymmetry as described in Maasoumi and Racine (2009).
npsymtest(data = NULL, method = c("integration","summation"), B = 399, bw = NULL, boot.method = c("iid", "geom"), random.seed = 42, ...)npsymtest(data = NULL, method = c("integration","summation"), B = 399, bw = NULL, boot.method = c("iid", "geom"), random.seed = 42, ...)
These arguments identify the data, statistic variant, and any supplied bandwidth.
bw |
a numeric (scalar) bandwidth. Defaults to plug-in (see details below). |
data |
a vector containing the variable. |
method |
a character string used to specify whether to compute the integral
version or the summation version of the statistic. Can be set as
|
These arguments control bootstrap execution and reproducibility settings.
boot.method |
a character string used to specify the
bootstrap method. Can be set as |
B |
an integer value specifying the number of bootstrap
replications to use. Defaults to |
random.seed |
an integer used to seed R's random number generator. This is to ensure replicability. Defaults to 42. |
Further arguments are passed to the bandwidth-selection routines used by the test.
... |
additional arguments supplied to specify the bandwidth
type, kernel types, and so on. This is used since we specify bw as
a numeric scalar and not a |
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
npsymtest computes the nonparametric metric entropy (normalized
Hellinger of Granger, Maasoumi and Racine (2004)) for testing
symmetry using the densities/probabilities of the data and the
rotated data, . See
Maasoumi and Racine (2009) for details. Default bandwidths are of the
plug-in variety (bw.SJ for continuous variables and
direct plug-in for discrete variables).
Missing observations are omitted before computing the statistic. For categorical data, declared levels, including unused levels, are retained in the pooled null sample and every bootstrap draw. The discrete entropy sum uses the full declared domain and the plug-in selector uses its category count. Kernel normalization and the existing reflection rule are unchanged; this does not define a new reflection for arbitrary nominal labels. If an observed or bootstrap reflection produces a category outside the declared domain, the call stops rather than discarding that observation. Numeric factor levels must therefore accommodate the existing reflection rule. No p-value is returned from incomplete bootstrap statistics.
For bootstrapping the null distribution of the statistic, iid
conducts simple random resampling, while geom conducts Politis
and Romano's (1994) stationary bootstrap using automatic block length
selection via the b.star function in the
np package. See the boot package for
details.
The summation version of this statistic may be numerically unstable
when y is sparse (the summation version involves division of
densities while the integration version involves differences). Warning
messages are produced should this occur (‘integration recommended’)
and should be heeded.
For numeric data using the fixed second-order Gaussian density estimator, the integration statistic uses deterministic corrected composite trapezoidal quadrature with four evaluation points per bandwidth and a domain extending eight bandwidths beyond the observed support. The density of each reflected bootstrap sample is obtained by reversing the density values on a grid symmetric about that sample's mean; the same reflection identity also avoids fitting a second density on the summation route. For summation, the selected iid or stationary bootstrap plan is generated once with the boot sampling law, converted to bounded chunks of multiplicities, and evaluated by a registered native routine without a sample-by-sample kernel matrix.
The accelerated route is also used when ... contains only
bwtype="fixed", ckertype="gaussian", and
ckerorder=2. Other density options retain the general
kernel-specific route. Generalized and adaptive nearest-neighbour
bandwidths therefore continue to use the ordered, duplicate-preserving
bootstrap sample and recompute realized neighbour radii rather than
treating multiplicities as fixed-bandwidth weights.
npsymtest returns an object of type symtest with the
following components
Srho |
the statistic |
Srho.bootstrap |
contains the bootstrap replications of |
P |
the P-value of the statistic |
boot.num |
number of bootstrap replications |
data.rotate |
the rotated data series |
bw |
the numeric (scalar) bandwidth |
summary supports object of type symtest.
The bootstrap upper-tail p-value is the proportion of bootstrap statistics greater than or equal to the observed statistic. Ties count as at least as extreme, giving the conservative tie convention for discrete statistics. This is the ordinary bootstrap proportion, without an add-one correction; a reported zero is possible with a finite number of replications.
npsymtest tests symmetry by comparing the density or
probability function of the observed data with that of the data
reflected around the relevant center. The same entropy-distance logic
used by the univariate density tests underlies the statistic.
For book-length background, see Racine (2019), Chapter 2 Continuous Density and Cumulative Distribution Functions and Li and Racine (2007), Chapter 13 Nonsmoothing Tests and Chapter 12 Model Specification Tests where related density-feature tests are treated.
When using data of type factor it is crucial that the
variable not be an alphabetic character string (i.e. the factor must
be integer-valued). The rotation is conducted about the median after
conversion to type numeric which is then converted back
to type factor. Failure to do so will have unpredictable
results. See the example below for proper usage.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Granger, C.W. and E. Maasoumi and J.S. Racine (2004), “A dependence metric for possibly nonlinear processes”, Journal of Time Series Analysis, 25, 649-669.
Maasoumi, E. and J.S. Racine (2009), “A robust entropy-based test of asymmetry for discrete and continuous processes,” Econometric Reviews, 28, 246-261.
Politis, D.N. and J.P. Romano (1994), “The stationary bootstrap,” Journal of the American Statistical Association, 89, 1303-1313.
np.kernels, np.options, plot
npdeneqtest,npdeptest,npsdeptest,npunitest
## Not run: set.seed(1234) n <- 100 ## Asymmetric discrete probability distribution function x <- factor(rbinom(n,2,.8)) npsymtest(x,B=99) if (interactive()) Sys.sleep(5) ## Symmetric discrete probability distribution function x <- factor(rbinom(n,2,.5)) npsymtest(x,B=99) if (interactive()) Sys.sleep(5) ## Asymmetric continuous distribution function y <- rchisq(n,df=2) npsymtest(y,B=99) if (interactive()) Sys.sleep(5) ## Symmetric continuous distribution function y <- rnorm(n) npsymtest(y,B=99) ## Time-series bootstrap ar.series <- function(phi,epsilon) { n <- length(epsilon) series <- numeric(n) series[1] <- epsilon[1]/(1-phi) for(i in 2:n) { series[i] <- phi*series[i-1] + epsilon[i] } return(series) } ## Asymmetric time-series yt <- ar.series(0.5,rchisq(n,df=3)) npsymtest(yt,B=99,boot.method="geom") ## Symmetric time-series yt <- ar.series(0.5,rnorm(n)) npsymtest(yt,B=99,boot.method="geom") ## End(Not run)## Not run: set.seed(1234) n <- 100 ## Asymmetric discrete probability distribution function x <- factor(rbinom(n,2,.8)) npsymtest(x,B=99) if (interactive()) Sys.sleep(5) ## Symmetric discrete probability distribution function x <- factor(rbinom(n,2,.5)) npsymtest(x,B=99) if (interactive()) Sys.sleep(5) ## Asymmetric continuous distribution function y <- rchisq(n,df=2) npsymtest(y,B=99) if (interactive()) Sys.sleep(5) ## Symmetric continuous distribution function y <- rnorm(n) npsymtest(y,B=99) ## Time-series bootstrap ar.series <- function(phi,epsilon) { n <- length(epsilon) series <- numeric(n) series[1] <- epsilon[1]/(1-phi) for(i in 2:n) { series[i] <- phi*series[i-1] + epsilon[i] } return(series) } ## Asymmetric time-series yt <- ar.series(0.5,rchisq(n,df=3)) npsymtest(yt,B=99,boot.method="geom") ## Symmetric time-series yt <- ar.series(0.5,rnorm(n)) npsymtest(yt,B=99,boot.method="geom") ## End(Not run)
npudens computes kernel unconditional density estimates on
evaluation data, given a set of training data and a bandwidth
specification (a bandwidth object or a bandwidth vector,
bandwidth type, and kernel type) using the method of Li and Racine
(2003).
npudens(bws, ...) ## S3 method for class 'formula' npudens(bws, data = NULL, newdata = NULL, ...) ## S3 method for class 'bandwidth' npudens(bws, tdat = stop("invoked without training data 'tdat'"), edat, ..., se = FALSE) ## Default S3 method: npudens(bws, tdat, ..., se = FALSE)npudens(bws, ...) ## S3 method for class 'formula' npudens(bws, data = NULL, newdata = NULL, ...) ## S3 method for class 'bandwidth' npudens(bws, tdat = stop("invoked without training data 'tdat'"), edat, ..., se = FALSE) ## Default S3 method: npudens(bws, tdat, ..., se = FALSE)
se |
Logical; compute and retain asymptotic standard errors when
|
These arguments identify the bandwidth specification, formula/data interface, and training data.
bws |
a bandwidth specification. This can be set as a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
tdat |
a |
These arguments control where the fitted density is evaluated.
edat |
a |
newdata |
An optional data frame in which to look for evaluation data. If omitted, the training data are used. |
Further arguments are passed to npudensbw when bandwidths are computed internally, or used to interpret a numeric bws vector.
... |
additional arguments supplied to |
With generalized nearest-neighbor bandwidths, query identity matters when
selecting a radius: a training observation excludes its own occurrence,
whereas explicit evaluation data remain external queries even if their
values equal training observations. Consequently,
predict(fit, newdata = training.data) can differ from
fitted(fit). This does not omit the training contribution from the
fitted estimator. See np.kernels for the radius convention.
For native (non-formula) objects, named newdata columns are matched
to the retained variable names and reordered as needed. Extra columns are
ignored; missing, duplicate or ambiguous names are errors. An unnamed
matrix or vector remains positional for a single evaluation role.
Explicit native evaluation arguments retain their positional contract and
take precedence over newdata.
For a native bandwidth object, newdata supplies edat;
explicitly supplied native evaluation arguments take precedence. This
evaluates at the requested rows without repeating bandwidth selection.
With bwtype="adaptive_nn" and se=TRUE, standard errors
include the same-sample influence of each donor-centred nearest-neighbour
radius. A two-sided rank-spacing pilot estimates the marginal density sum
at the radius endpoints. Cross-coordinate and categorical-kernel covariance
are retained in the joint observation influence. The selected NN ranks
are treated as fixed; bandwidth-selection uncertainty is not included.
This calculation supports Gaussian and Epanechnikov kernels of orders
2, 4, 6 and 8, and uniform kernels, without finite kernel bounds.
Uniform density errors additionally include moving-support boundary
influences with joint other-coordinate and categorical kernel marks.
These use type-7 sample-quantile endpoints and deterministic two-sided
rank-spacing pilots whose interior window grows as the two-thirds power
of sample size. A strictly absent support face contributes zero; an exact
probability endpoint or undefined finite-face pilot is unavailable.
Finite kernel bounds (including beta kernels), extended or saturated NN
ranks, and degenerate pilot spacings are not
currently qualified: point estimates are retained and standard errors
are NA, with one availability notice. No additional uncertainty
computation is performed for se=FALSE. Requested adaptive-NN
standard errors can take several times as long as the point fit because
they include the donor-radius influence calculation; this cost is incurred
only when standard errors are requested.
Documentation guide: see npudensbw for bandwidth
selection and search controls, np.kernels for kernels,
np.options for global options, and plot,
plot.np for plotting options.
When bws is omitted, the formula and default methods call
npudensbw first and pass bandwidth-selection arguments
from ... to that call. When bws is already a
bandwidth object, npudens estimates with the stored
bandwidth metadata in that object.
The beta associated density described in np.kernels is
available for continuous coordinates at orders 2, 4, 6, and 8 with manual
or cross-validated metric bandwidths. Such coordinates may be combined with
unordered and ordered categorical coordinates. Fixed, generalized-NN, and
adaptive-NN bandwidths are supported. Use ckertype="beta" and either
ckerbound="fixed" with finite lower and upper bounds or
ckerbound="range" for beta outer half-spacing sample bounds as
defined in np.kernels. Every
continuous training and evaluation value must lie within the resulting
support. For
example:
fhat <- npudens(tdat=data.frame(x), edat=data.frame(x=x.eval),
bws=0.12, ckertype="beta", ckerorder=2,
ckerbound="fixed", ckerlb=0, ckerub=1)
The beta contribution already includes its complete original-scale density
normalization. No additional division by the bandwidth is performed.
Beta density routes require at least one continuous coordinate and reject
normal-reference selection. Cross-validated cv.ml and bounded
target-coordinate cv.ls are available; the latter integrates the
actual estimator and does not substitute the public beta-overlap operator.
Orders 4, 6, and 8 are signed and can produce negative density estimates;
no positivity repair is applied.
Because an associated beta kernel has target-dependent shape and roughness,
its reported standard error does not substitute a translation-invariant
constant. If denotes the full multivariate beta
contribution, the implementation reports the ordinary standard error of
their sample mean,
with zero reported when . This contribution-based expression
automatically respects the changing boundary shape.
When all variables are categorical, uncertainty uses the complete
joint-category contributions produced by the selected kernel
computation. With , the empirical-population
convention is
Thus zero smoothing retains ,
while exactly constant contributions have zero standard error.
Category-profile compression includes the original observation counts;
it does not treat distinct profiles as equally frequent observations.
For ordinary kernels with mixed continuous and categorical data, fixed and generalized-nearest-neighbour standard errors retain the leading continuous- bandwidth approximation while using the squared joint categorical kernel product. Thus a categorical factor that multiplies the density by a constant also multiplies its standard error by that constant. This is not the sample variance of finite-bandwidth continuous kernel contributions. Generalized-NN errors use the existing frozen-query-radius approximation. The separate adaptive-NN influence calculation is described above.
Argument groups for bandwidth selection are documented on
npudensbw. The most common workflow is to choose data
and bandwidth inputs first, then bandwidth criterion and
representation, then kernel/support controls and numerical search
controls if defaults need to be changed.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
Typical usages are (see below for a complete list of options and also the examples at the end of this help file)
Usage 1: first compute the bandwidth object via npudensbw and then
compute the density:
bw <- npudensbw(~y)
fhat <- npudens(bw)
Usage 2: alternatively, compute the bandwidth object indirectly:
fhat <- npudens(~y)
Usage 3: modify the default kernel and order:
fhat <- npudens(~y, ckertype="epanechnikov", ckerorder=4)
Usage 4: use the data frame interface rather than the formula
interface:
fhat <- npudens(tdat = y, ckertype="epanechnikov", ckerorder=4)
npudens implements a variety of methods for estimating
multivariate density functions (-variate) defined over a set of
possibly continuous and/or discrete (unordered, ordered) data. The
approach is based on Li and Racine (2003) who employ
‘generalized product kernels’ that admit a mix of continuous
and discrete data types.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating
the density at the point . Generalized nearest-neighbor
bandwidths change with the point at which the density is estimated,
. Fixed bandwidths are constant over the support of .
Data contained in the data frame tdat (and also edat)
may be a mix of continuous (default), unordered discrete (to be
specified in the data frame tdat using the factor
command), and ordered discrete (to be specified in the data frame
tdat using the ordered command). Data can be
entered in an arbitrary order and data types will be detected
automatically by the routine (see np for details).
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth order Gaussian and Epanechnikov kernels, and the uniform kernel. Unordered discrete data types use a variation on Aitchison and Aitken's (1976) kernel, while ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
Standard errors are opt-in. To add them to an existing fit without
repeating bandwidth selection, use
fit <- npudens(bws=fit$bws, se=TRUE), supplying the original
training data and desired evaluation data again when these cannot be
recovered from the bandwidth object's call. The se() extractor
reads retained errors only and gives a helpful refit message when they
were not requested. Use predict(fit, se.fit=TRUE, ...) for
prediction with standard errors.
npudens returns a npdensity object. The generic accessor
functions fitted, and se, extract
estimated values and asymptotic standard errors on estimates,
respectively, from the returned object. Furthermore, the functions
predict, summary and plot
support objects of both classes. The returned objects have the
following components:
eval |
the evaluation points. |
dens |
estimation of the density at the evaluation points |
derr |
Standard errors of the density estimates when
|
se |
Whether standard-error computation was requested. |
log_likelihood |
aggregate fitted-density log likelihood. Every
represented strictly positive density estimate, including a positive
subnormal value, contributes its literal logarithm. An exact zero or
negative density estimate has no mathematical logarithm and is represented
in this aggregate by the established computational placeholder
|
The unconditional density target is . In the continuous
fixed-bandwidth case the estimator has the usual kernel form
; with mixed data,
npudens uses generalized product kernels so that the continuous,
unordered, and ordered components each contribute their appropriate
kernel factor. Nearest-neighbor bandwidth types change how the
continuous bandwidth is indexed, not the statistical target.
For book-length derivations, see Li and Racine (2007), Chapter 1 Density Estimation, especially Sections 1.1, 1.3, 1.6, 1.8, and 1.9, and Chapter 4 Kernel Estimation with Mixed Data. The later workflow treatment is Racine (2019), Chapter 2 Continuous Density and Cumulative Distribution Functions and Chapter 3 Mixed-Data Probability Density and Cumulative Distribution Functions.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “ Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2003), “Nonparametric estimation of distributions with categorical and continuous data,” Journal of Multivariate Analysis, 86, 266-292.
Ouyang, D. and Q. Li and J.S. Racine (2006), “Cross-validation and the estimation of probability distributions with categorical data,” Journal of Nonparametric Statistics, 18, 69-100.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Scott, D.W. (1992), Multivariate Density Estimation: Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
Chen, S.X. (1999), “Beta kernel estimators for density functions,” Computational Statistics & Data Analysis, 31(2), 131–145. doi:10.1016/S0167-9473(99)00010-9.
Igarashi, G. and Kakizawa, Y. (2020), “Higher-order bias corrections for asymmetric kernel density estimators,” Journal of Nonparametric Statistics, 32(3), 716–752. doi:10.1080/10485252.2020.1770754.
np.kernels, np.options, plot, plot.np npudensbw , density
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous, # compute bandwidths using likelihood cross-validation, then create a # grid of data on which the density will be evaluated for plotting # purposes. data("Italy") with(Italy, { # Compute bandwidths using likelihood cross-validation (default). bw <- npudensbw(formula=~ordered(year)+gdp) # At this stage you could use npudens() to do a variety of # things. Here we compute the npudens() object and place it in fhat. fhat <- npudens(bws=bw) # Note that simply typing the name of the object returns some useful # information. For more info, one can call summary: summary(fhat) # Next, we illustrate how to create a grid of `evaluation data' and feed # it to the perspective plotting routines in R, among others. # Create an evaluation data matrix year.seq <- sort(unique(year)) gdp.seq <- seq(1,36,length=50) data.eval <- expand.grid(year=year.seq,gdp=gdp.seq) # Generate the estimated density computed for the evaluation data fhat <- fitted(npudens(bws=bw, newdata=data.eval)) # Coerce the data into a matrix for plotting with persp() f <- matrix(fhat, length(unique(year)), 50) # Next, create a 3D perspective plot of the PDF f, and a 2D # contour plot. persp(as.integer(levels(year.seq)), gdp.seq, f, col="lightblue", ticktype="detailed", ylab="GDP", xlab="Year", zlab="Density", theta=300, phi=50) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) contour(as.integer(levels(year.seq)), gdp.seq, f, xlab="Year", ylab="GDP", main = "Density Contour Plot", col=topo.colors(100)) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Alternatively, you could use the plot() command (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous, # compute bandwidths using likelihood cross-validation, then create a # grid of data on which the density will be evaluated for plotting # purposes. data("Italy") with(Italy, { data <- data.frame(year=ordered(year), gdp) # Compute bandwidths using likelihood cross-validation (default). bw <- npudensbw(dat=data) # At this stage you could use npudens() to do a variety of # things. Here we compute the npudens() object and place it in fhat. fhat <- npudens(bws=bw) # Note that simply typing the name of the object returns some useful # information. For more info, one can call summary: summary(fhat) # Next, we illustrate how to create a grid of `evaluation data' and feed # it to the perspective plotting routines in R, among others. # Create an evaluation data matrix year.seq <- sort(unique(year)) gdp.seq <- seq(1,36,length=50) data.eval <- expand.grid(year=year.seq,gdp=gdp.seq) # Generate the estimated density computed for the evaluation data fhat <- fitted(npudens(edat = data.eval, bws=bw)) # Coerce the data into a matrix for plotting with persp() f <- matrix(fhat, length(unique(year)), 50) # Next, create a 3D perspective plot of the PDF f, and a 2D # contour plot. persp(as.integer(levels(year.seq)), gdp.seq, f, col="lightblue", ticktype="detailed", ylab="GDP", xlab="Year", zlab="Density", theta=300, phi=50) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) contour(as.integer(levels(year.seq)), gdp.seq, f, xlab="Year", ylab="GDP", main = "Density Contour Plot", col=topo.colors(100)) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Alternatively, you could use the plot() command (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=FORMULA): For this example, we load the old # faithful geyser data and compute the density and distribution # functions. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npudensbw(formula=~eruptions+waiting) summary(bw) # Plot the density function (<ctrl>-C will interrupt on *NIX systems, # <esc> will interrupt on MS Windows systems). Note that we use xtrim = # -0.2 to extend the plot outside the support of the data (i.e., extend # the tails of the estimate to meet the horizontal axis). if (interactive()) plot(bw, xtrim=-0.2) }) # EXAMPLE 2 (INTERFACE=DATA FRAME): For this example, we load the old # faithful geyser data and compute the density and distribution # functions. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npudensbw(dat=faithful) summary(bw) # Plot the density function (<ctrl>-C will interrupt on *NIX systems, # <esc> will interrupt on MS Windows systems). Note that we use xtrim = # -0.2 to extend the plot outside the support of the data (i.e., extend # the tails of the estimate to meet the horizontal axis). if (interactive()) plot(bw, xtrim=-0.2) }) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous, # compute bandwidths using likelihood cross-validation, then create a # grid of data on which the density will be evaluated for plotting # purposes. data("Italy") with(Italy, { # Compute bandwidths using likelihood cross-validation (default). bw <- npudensbw(formula=~ordered(year)+gdp) # At this stage you could use npudens() to do a variety of # things. Here we compute the npudens() object and place it in fhat. fhat <- npudens(bws=bw) # Note that simply typing the name of the object returns some useful # information. For more info, one can call summary: summary(fhat) # Next, we illustrate how to create a grid of `evaluation data' and feed # it to the perspective plotting routines in R, among others. # Create an evaluation data matrix year.seq <- sort(unique(year)) gdp.seq <- seq(1,36,length=50) data.eval <- expand.grid(year=year.seq,gdp=gdp.seq) # Generate the estimated density computed for the evaluation data fhat <- fitted(npudens(bws=bw, newdata=data.eval)) # Coerce the data into a matrix for plotting with persp() f <- matrix(fhat, length(unique(year)), 50) # Next, create a 3D perspective plot of the PDF f, and a 2D # contour plot. persp(as.integer(levels(year.seq)), gdp.seq, f, col="lightblue", ticktype="detailed", ylab="GDP", xlab="Year", zlab="Density", theta=300, phi=50) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) contour(as.integer(levels(year.seq)), gdp.seq, f, xlab="Year", ylab="GDP", main = "Density Contour Plot", col=topo.colors(100)) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Alternatively, you could use the plot() command (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous, # compute bandwidths using likelihood cross-validation, then create a # grid of data on which the density will be evaluated for plotting # purposes. data("Italy") with(Italy, { data <- data.frame(year=ordered(year), gdp) # Compute bandwidths using likelihood cross-validation (default). bw <- npudensbw(dat=data) # At this stage you could use npudens() to do a variety of # things. Here we compute the npudens() object and place it in fhat. fhat <- npudens(bws=bw) # Note that simply typing the name of the object returns some useful # information. For more info, one can call summary: summary(fhat) # Next, we illustrate how to create a grid of `evaluation data' and feed # it to the perspective plotting routines in R, among others. # Create an evaluation data matrix year.seq <- sort(unique(year)) gdp.seq <- seq(1,36,length=50) data.eval <- expand.grid(year=year.seq,gdp=gdp.seq) # Generate the estimated density computed for the evaluation data fhat <- fitted(npudens(edat = data.eval, bws=bw)) # Coerce the data into a matrix for plotting with persp() f <- matrix(fhat, length(unique(year)), 50) # Next, create a 3D perspective plot of the PDF f, and a 2D # contour plot. persp(as.integer(levels(year.seq)), gdp.seq, f, col="lightblue", ticktype="detailed", ylab="GDP", xlab="Year", zlab="Density", theta=300, phi=50) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) contour(as.integer(levels(year.seq)), gdp.seq, f, xlab="Year", ylab="GDP", main = "Density Contour Plot", col=topo.colors(100)) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Alternatively, you could use the plot() command (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=FORMULA): For this example, we load the old # faithful geyser data and compute the density and distribution # functions. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npudensbw(formula=~eruptions+waiting) summary(bw) # Plot the density function (<ctrl>-C will interrupt on *NIX systems, # <esc> will interrupt on MS Windows systems). Note that we use xtrim = # -0.2 to extend the plot outside the support of the data (i.e., extend # the tails of the estimate to meet the horizontal axis). if (interactive()) plot(bw, xtrim=-0.2) }) # EXAMPLE 2 (INTERFACE=DATA FRAME): For this example, we load the old # faithful geyser data and compute the density and distribution # functions. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npudensbw(dat=faithful) summary(bw) # Plot the density function (<ctrl>-C will interrupt on *NIX systems, # <esc> will interrupt on MS Windows systems). Note that we use xtrim = # -0.2 to extend the plot outside the support of the data (i.e., extend # the tails of the estimate to meet the horizontal axis). if (interactive()) plot(bw, xtrim=-0.2) }) ## End(Not run)
npudensbw computes a bandwidth object for a -variate
kernel unconditional density estimator defined over mixed continuous
and discrete (unordered, ordered) data using either the normal
reference rule-of-thumb, likelihood cross-validation, or least-squares
cross validation using the method of Li and Racine (2003).
npudensbw(...) ## S3 method for class 'formula' npudensbw(formula, data, subset, na.action, call, ...) ## S3 method for class 'bandwidth' npudensbw(dat = stop("invoked without input data 'dat'"), bws, bandwidth.compute = TRUE, cfac.dir = 2.5*(3.0-sqrt(5)), scale.factor.init = 0.5, dfac.dir = 0.25*(3.0-sqrt(5)), dfac.init = 0.375, dfc.dir = 3, ftol = 1.490116e-07, scale.factor.init.upper = 2.0, hbd.dir = 1, hbd.init = 0.9, initc.dir = 1.0, initd.dir = 1.0, invalid.penalty = c("baseline","dbmax"), itmax = 10000, lbc.dir = 0.5, scale.factor.init.lower = 0.1, lbd.dir = 0.1, lbd.init = 0.1, nmulti, penalty.multiplier = 10, powell.remin = TRUE, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample = FALSE, scale.factor.search.lower = NULL, small = 1.490116e-05, tol = 1.490116e-04, transform.bounds = FALSE, eval.only = FALSE, ..., nomad.opts = list()) ## Default S3 method: npudensbw(dat = stop("invoked without input data 'dat'"), bws, bandwidth.compute = TRUE, bwmethod, bwscaling, bwtype, cfac.dir, scale.factor.init, ckerbound, ckerlb, ckerorder, ckertype, ckerub, dfac.dir, dfac.init, dfc.dir, ftol, scale.factor.init.upper, hbd.dir, hbd.init, initc.dir, initd.dir, invalid.penalty, itmax, lbc.dir, scale.factor.init.lower, lbd.dir, lbd.init, nmulti, okertype, penalty.multiplier, powell.remin, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample, scale.factor.search.lower = NULL, small, tol, transform.bounds, ukertype, ..., nomad.opts = list())npudensbw(...) ## S3 method for class 'formula' npudensbw(formula, data, subset, na.action, call, ...) ## S3 method for class 'bandwidth' npudensbw(dat = stop("invoked without input data 'dat'"), bws, bandwidth.compute = TRUE, cfac.dir = 2.5*(3.0-sqrt(5)), scale.factor.init = 0.5, dfac.dir = 0.25*(3.0-sqrt(5)), dfac.init = 0.375, dfc.dir = 3, ftol = 1.490116e-07, scale.factor.init.upper = 2.0, hbd.dir = 1, hbd.init = 0.9, initc.dir = 1.0, initd.dir = 1.0, invalid.penalty = c("baseline","dbmax"), itmax = 10000, lbc.dir = 0.5, scale.factor.init.lower = 0.1, lbd.dir = 0.1, lbd.init = 0.1, nmulti, penalty.multiplier = 10, powell.remin = TRUE, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample = FALSE, scale.factor.search.lower = NULL, small = 1.490116e-05, tol = 1.490116e-04, transform.bounds = FALSE, eval.only = FALSE, ..., nomad.opts = list()) ## Default S3 method: npudensbw(dat = stop("invoked without input data 'dat'"), bws, bandwidth.compute = TRUE, bwmethod, bwscaling, bwtype, cfac.dir, scale.factor.init, ckerbound, ckerlb, ckerorder, ckertype, ckerub, dfac.dir, dfac.init, dfc.dir, ftol, scale.factor.init.upper, hbd.dir, hbd.init, initc.dir, initd.dir, invalid.penalty, itmax, lbc.dir, scale.factor.init.lower, lbd.dir, lbd.init, nmulti, okertype, penalty.multiplier, powell.remin, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample, scale.factor.search.lower = NULL, small, tol, transform.bounds, ukertype, ..., nomad.opts = list())
These arguments identify the data, formula interface, and whether bandwidths are supplied or computed.
bandwidth.compute |
a logical value which specifies whether to do a numerical search for
bandwidths or not. If set to |
bws |
a bandwidth specification. This can be set as a bandwidth object
returned from a previous invocation, or as a vector of bandwidths,
with each element |
call |
the original function call. This is passed internally by
|
dat |
a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
formula |
a symbolic description of variables on which bandwidth selection is to be performed. The details of constructing a formula are described below. |
na.action |
a function which indicates what should happen when the data contain
|
subset |
an optional vector specifying a subset of observations to be used in the fitting process. |
These arguments choose the selection criterion and the way continuous bandwidths are represented.
bwmethod |
a character string specifying the bandwidth selection
method. |
bwscaling |
a logical value that when set to |
bwtype |
character string used for the continuous variable bandwidth type,
specifying the type of bandwidth to compute and return in the
|
These controls set categorical search starts and categorical direction-set initialization.
dfac.dir |
stretch factor for direction set search for Powell's algorithm for categorical variables. See Details |
dfac.init |
non-random initial values for scale factors for categorical variables for Powell's algorithm. See Details |
hbd.dir |
upper bound for direction set search for Powell's algorithm for categorical variables. See Details |
hbd.init |
upper bound for scale factors for categorical variables for Powell's algorithm. See Details |
initd.dir |
initial non-random values for direction set search for Powell's algorithm for categorical variables. See Details |
lbd.dir |
lower bound for direction set search for Powell's algorithm for categorical variables. See Details |
lbd.init |
lower bound for scale factors for categorical variables for Powell's algorithm. See Details |
scale.init.categorical.sample |
a logical value that when set
to |
These controls set Powell direction-set initialization for continuous variables.
cfac.dir |
stretch factor for direction set search for Powell's algorithm for |
dfc.dir |
chi-square degrees of freedom for direction set search for Powell's algorithm for |
initc.dir |
initial non-random values for direction set search for Powell's algorithm for |
lbc.dir |
lower bound for direction set search for Powell's algorithm for |
These controls choose and parameterize bounded support for continuous kernels.
ckerbound |
character string controlling continuous-kernel support handling.
Can be set as |
ckerlb |
numeric scalar/vector of lower bounds for continuous variables used
when |
ckerub |
numeric scalar/vector of upper bounds for continuous variables used
when |
These controls define deterministic and random continuous scale-factor starts and the lower admissibility floor for fixed-bandwidth search.
scale.factor.init |
deterministic initial scale factor for continuous fixed-bandwidth
search. Defaults to |
scale.factor.init.lower |
lower endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.init.upper |
upper endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.search.lower |
optional nonnegative scalar giving the hard lower admissibility
bound for continuous fixed-bandwidth search candidates. Defaults to
|
These controls choose continuous, unordered, and ordered kernels.
ckerorder |
numeric value specifying kernel order (one of
|
ckertype |
character string used to specify the continuous kernel type.
Can be set as |
okertype |
character string used to specify the ordered categorical kernel type.
Can be set as |
ukertype |
character string used to specify the unordered categorical kernel type.
Can be set as |
These controls set optimizer tolerances, restart behavior, invalid-candidate penalties, and bounded search transformations.
ftol |
fractional tolerance on the value of the cross-validation function
evaluated at located minima (of order the machine precision or
perhaps slightly larger so as not to be diddled by
roundoff). Defaults to |
invalid.penalty |
a character string specifying the penalty
used when the optimizer encounters invalid bandwidths.
|
itmax |
integer number of iterations before failure in the numerical
optimization routine. Defaults to |
nmulti |
integer number of times to restart the process of finding extrema of the cross-validation function from different (random) initial points. |
penalty.multiplier |
a numeric multiplier applied to the
baseline penalty when |
powell.remin |
logical flag controlling Powell restart-from-minimum behavior. When
|
bwsolver |
bandwidth optimizer for fixed-degree searches. The default
|
nomad.opts |
optional named list of native NOMAD parameters forwarded to the
crs NOMAD C API for MADS/NOMAD-backed bandwidth searches.
|
small |
a small number used to bracket a minimum (it is hopeless to ask for
a bracketing interval of width less than sqrt(epsilon) times its
central value, a fractional width of only about 10-04 (single
precision) or 3x10-8 (double precision)). Defaults to |
tol |
tolerance on the position of located minima of the cross-validation
function (tol should generally be no smaller than the square root of
your machine's floating point precision). Defaults to |
transform.bounds |
a logical value that when set to |
eval.only |
internal logical flag used by solver wrappers to evaluate an
existing bandwidth candidate without running a bandwidth search.
Ordinary users should leave this at its default |
These arguments collect remaining controls passed through S3 methods.
... |
additional arguments supplied to specify the bandwidth type, kernel types, selection methods, and so on, detailed below. |
Formula bandwidth objects retain the prepared training sample (after alignment,
subsetting and missing-value handling) and the resolved missing-value policy.
Later refits use that sample even if constructor variables are rebound.
Supplying explicit training data to the estimator replaces the training data;
evaluation via newdata does not. Retention requires storage proportional
to the sample size times the number of variables, not a pairwise weight matrix.
Older saved objects without this retained state still rely on their original
data bindings; rebuild their bandwidth object from the intended data before
changing those bindings. User-defined transformation and missing-value
functions should not rely on subsequently modified closure state.
The scale.factor.* controls are dimensionless search
controls. The package converts scale factors to bandwidths using the
estimator-specific scaling encoded in the bandwidth object, including
kernel order and the number of continuous variables relevant for the
estimator. Users should not pre-multiply these controls by sample-size
or standard-deviation factors.
scale.factor.init controls the deterministic first search
start. scale.factor.init.lower and
scale.factor.init.upper define the random multistart interval.
scale.factor.search.lower is the lower admissibility bound for
continuous fixed-bandwidth search candidates. The effective first
start is max(scale.factor.init, scale.factor.search.lower),
and the effective random-start lower endpoint is
max(scale.factor.init.lower, scale.factor.search.lower).
scale.factor.init.upper must be at least that effective lower
endpoint; the package errors rather than silently expanding the user's
interval.
When scale.factor.search.lower is NULL, an existing
bandwidth object's stored floor is inherited when available;
otherwise the package default 0.1 is used. Explicit bandwidths
supplied for storage with bandwidth.compute = FALSE are not
rewritten by the search floor.
For automatic fixed-bandwidth CVLS with a beta kernel,
repeated complete observations at a declared endpoint require an
explicitly positive resolved scale.factor.search.lower. The default
0.1 already satisfies this requirement. Endpoint repetitions can
cause the criterion to prefer vanishing bandwidths; this is a conservative
search-admissibility policy, not a claim that every such sample has a
divergent criterion. Manual bandwidth evaluation and nearest-neighbor
searches remain available. No positive floor is silently substituted for
an explicitly requested zero.
A selected scale factor at this floor is a boundary solution of the
constrained search, not evidence of an interior optimum. In particular,
endpoint observations can make beta CVLS sensitive to the chosen floor.
For a returned fixed-bandwidth object bw, inspect
bw$sfactor$x[bw$icon] alongside
bw$scale.factor.search.lower; the physical bandwidth is on a
different scale and should not be compared directly with this dimensionless
bound. Near-bound solutions merit the same sensitivity consideration, but
proximity alone does not prove that the unconstrained criterion diverges.
Changing the floor changes the admissible search problem.
Categorical search-start controls such as dfac.init,
lbd.init, and hbd.init have separate semantics and are
not affected by scale.factor.search.lower.
For bwmethod="cv.ml", the ordinary contribution is based on
. Compact-support kernels can yield
zero leave-one-out density estimates, and higher-order kernels can
yield negative estimates. In those cases the package optimizes a
guarded CVML criterion rather than the literal log likelihood. Every
represented strictly positive fitted value, including a positive
subnormal value, uses the ordinary branch
. Let
denote the positive machine floor used only to
encode an invalid nonpositive contribution. Exact zero and negative values
with magnitude no greater than use
; negative values of larger magnitude
use the smooth penalty
.
The guarded count reported in bandwidth summaries records
objective evaluations containing an invalid nonpositive contribution; a
positive value is not guarded merely because it is small. The
bwmethod="cv.ls" criterion remains well defined for negative
kernel density estimates and is not modified by this CVML guard.
Documentation guide: see np.kernels for kernels,
np.options for global options, and
plot, plot.np for plotting options.
The bandwidth-selection argument surface is easiest to read by
decision group: data and existing bandwidth inputs; bandwidth
criterion and representation; continuous kernel and support controls
beginning with cker*; categorical kernel controls
ukertype and okertype; and numerical search
initialization, tolerances, and feasibility controls. Users who call
npudens without a bandwidth object can pass these same
bandwidth-selection controls through that function's ....
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
Typical usages are (see below for a complete list of options and also the examples at the end of this help file)
Usage 1: compute a bandwidth object using the formula interface:
bw <- npudensbw(~y)
Usage 2: compute a bandwidth object using the data frame interface
and change the default kernel and order:
fhat <- npudensbw(tdat = y, ckertype="epanechnikov", ckerorder=4)
npudensbw implements a variety of methods for choosing
bandwidths for multivariate (-variate) distributions defined over
a set of possibly continuous and/or discrete (unordered, ordered)
data. The approach is based on Li and Racine (2003) who employ
‘generalized product kernels’ that admit a mix of continuous
and discrete data types.
The cross-validation methods employ multivariate numerical search algorithms (direction set (Powell's) methods in multidimensions).
Bandwidths can (and will) differ for each variable which is, of course, desirable.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating the
density at the point . Generalized nearest-neighbor bandwidths change
with the point at which the density is estimated, . Fixed bandwidths
are constant over the support of .
Exact ties can make the literal th continuous nearest-neighbor
radius zero. Such a bandwidth is undefined and is rejected; see
np.kernels for the precise contract and remedies.
The Chen/Igarashi–Kakizawa beta family is available at orders 2, 4, 6,
and 8 for fixed, generalized-NN, and adaptive-NN estimation of continuous
variables on finite supports. Beta continuous coordinates may be combined
with unordered and ordered categorical coordinates, which retain their
selected categorical kernels. Set ckertype = "beta" and use either
ckerbound = "fixed" with finite ckerlb/ckerub or
ckerbound = "range". Explicit bandwidth objects and automatic
cv.ml/cv.ls selection are supported for continuous and mixed
data; normal-reference selection is not. The bandwidth is in
the units of coordinate ; internally the beta precision is
.
Higher orders use the signed multiscale coefficients documented in
np.kernels. Bounded density cv.ls uses numerical
target-coordinate quadrature of the estimator rather than the public
observation-coordinate overlap. For univariate order-2 fixed-bandwidth beta
ckerbound="range" CVLS searches with Powell, the ordinary result is
also checked against the deterministic uniform-limit certificate documented
in np.kernels. This does not replace or reduce the user's
nmulti search, and the same check applies when automatic selection is
restarted from an eligible beta range bandwidth object.
npudensbw may be invoked either with a formula-like
symbolic description of variables on which bandwidth selection is to
be performed or through a simpler interface whereby data is
passed directly to the function via the dat parameter. Use of
these two interfaces is mutually exclusive.
Data contained in the data frame dat may be a mix of continuous
(default), unordered discrete (to be specified in the data frame
dat using factor), and ordered discrete (to be
specified in the data frame dat using
ordered). Data can be entered in an arbitrary order and
data types will be detected automatically by the routine (see
np for details).
Data for which bandwidths are to be estimated may be specified
symbolically. A typical description has the form ~ data, where
data is a series of variables specified by name, separated by
the separation character '+'. For example, ~ x + y specifies
that the bandwidths for the joint distribution of variables x
and y are to be estimated. See below for further examples.
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth order Gaussian and Epanechnikov kernels, and the uniform kernel. Unordered discrete data types use a variation on Aitchison and Aitken's (1976) kernel, while ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
The optimizer invoked for search is Powell's conjugate direction
method which requires the setting of (non-random) initial values and
search directions for bandwidths, and, when restarting, random values
for successive invocations. Bandwidths for numeric variables
are scaled by robust measures of spread, the sample size, and the
number of numeric variables where appropriate. Two sets of
parameters for bandwidths for numeric can be modified, those
for initial values for the parameters themselves, and those for the
directions taken (Powell's algorithm does not involve explicit
computation of the function's gradient). The default values are set by
considering search performance for a variety of difficult test cases
and simulated cases. We highly recommend restarting search a large
number of times to avoid the presence of local minima (achieved by
modifying nmulti). Further refinement for difficult cases can
be achieved by modifying these sets of parameters. However, these
parameters are intended more for the authors of the package to enable
‘tuning’ for various methods rather than for the user themselves.
npudensbw returns a bandwidth object, with the
following components:
bw |
bandwidth(s), scale factor(s) or nearest neighbours for the
data, |
fval |
objective function value at minimum |
beta.range.certification |
for an eligible automatic beta range CVLS search, a list recording the uniform-limit probe, trigger decision, optional support-width refinement, and selected source; absent otherwise |
num.feval.certified |
number of function evaluations attributable to that certification and optional refinement; absent otherwise |
if bwtype is set to fixed, an object containing
bandwidths, of class bandwidth
(or scale factors if bwscaling = TRUE) is returned. If it is set to
generalized_nn or adaptive_nn, then instead the
th nearest
neighbors are returned for the continuous variables while the discrete
kernel bandwidths are returned for the discrete variables. Bandwidths
are stored under the component name bw, with each
element corresponding to column of input data
dat.
Prediction follows a two-stage contract. Calling predict(bw)
on the returned bandwidth object is a convenience forwarder for
npudens(bws = bw) and returns a fitted npdensity
object; it does not return a numeric vector of density estimates.
Call fitted(fit) or predict(fit, newdata = ...) on that
fitted object to obtain numeric results. The canonical workflow is
bw <- npudensbw(~ x, data = mydata)
fit <- predict(bw) # equivalent to npudens(bws = bw)
fitted(fit)
predict(fit, newdata = newdata)
The functions summary and plot also
support bandwidth objects.
npudensbw selects bandwidths for the unconditional density
target estimated by npudens. The continuous
scale factors and discrete smoothing parameters are those used in the
generalized product-kernel density estimator.
For book-length derivations, see Li and Racine (2007), Chapter 1 Density Estimation, especially Sections 1.3, 1.6, 1.8, and 1.9, and Chapter 4 Kernel Estimation with Mixed Data. The later workflow treatment is Racine (2019), Chapters 2 and 3.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Caution: multivariate data-driven bandwidth selection methods are, by
their nature, computationally intensive. Virtually all methods
require dropping the th observation from the data set, computing an
object, repeating this for all observations in the sample, then
averaging each of these leave-one-out estimates for a given
value of the bandwidth vector, and only then repeating this a large
number of times in order to conduct multivariate numerical
minimization/maximization. Furthermore, due to the potential for local
minima/maxima, restarting this procedure a large number of times may
often be necessary. This can be frustrating for users possessing
large datasets. For exploratory purposes, you may wish to override the
default search tolerances, say, setting ftol=.01 and tol=.01 and
conduct multistarting (the default is to restart min(2, ncol(dat))
times) as is done for a number of examples. Once the procedure
terminates, you can restart search with default tolerances using those
bandwidths obtained from the less rigorous search (i.e., set
bws=bw on subsequent calls to this routine where bw is
the initial bandwidth object). A version of this package using the
Rmpi wrapper is under development that allows one to deploy
this software in a clustered computing environment to facilitate
computation involving large datasets.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and , C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2003), “Nonparametric estimation of distributions with categorical and continuous data,” Journal of Multivariate Analysis, 86, 266-292.
Ouyang, D. and Q. Li and J.S. Racine (2006), “Cross-validation and the estimation of probability distributions with categorical data,” Journal of Nonparametric Statistics, 18, 69-100.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Scott, D.W. (1992), Multivariate Density Estimation. Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np
bw.nrd, bw.SJ, hist,
npudens, npudist
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous. data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # We compute bandwidths for the kernel density estimator using the # normal-reference rule-of-thumb. Otherwise, we use the defaults (second # order Gaussian kernel, fixed bandwidths). Note that the bandwidth # object you compute inherits all properties of the estimator (kernel # type, kernel order, estimation method) and can be fed directly into # the plotting utility plot() or into the npudens() function. bw <- npudensbw(formula=~ordered(year)+gdp, bwmethod="normal-reference") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, specify a value for the bandwidths manually (0.5 for the first # variable, 1.0 for the second)... bw <- npudensbw(formula=~ordered(year)+gdp, bws=c(0.5, 1.0), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, if you wanted to use the 1.06 sigma n^{-1/(2p+q)} rule-of-thumb # for the bandwidth for the continuous variable and, say, no smoothing # for the discrete variable, you would use the bwscaling=TRUE argument # and feed in the values 0 for the first variable (year) and 1.06 for # the second (gdp). Note that in the printout it reports the `scale # factors' rather than the `bandwidth' as reported in some of the # previous examples. bw <- npudensbw(formula=~ordered(year)+gdp, bws=c(0, 1.06), bwscaling=TRUE, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you wished to use, say, an eighth order Epanechnikov kernel for the # continuous variables and specify your own bandwidths, you could do # that as follows. bw <- npudensbw(formula=~ordered(year)+gdp, bws=c(0.5, 1.0), bandwidth.compute=FALSE, ckertype="epanechnikov", ckerorder=8) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you preferred, say, nearest-neighbor bandwidths and a generalized # kernel estimator for the continuous variable, you would use the # bwtype="generalized_nn" argument. bw <- npudensbw(formula=~ordered(year)+gdp, bwtype = "generalized_nn") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, compute bandwidths using likelihood cross-validation, fixed # bandwidths, and a second order Gaussian kernel for the continuous # variable (default). Note - this may take a few minutes depending on # the speed of your computer. bw <- npudensbw(formula=~ordered(year)+gdp) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Finally, if you wish to use initial values for numerical search, you # can either provide a vector of bandwidths as in bws=c(...) or a # bandwidth object from a previous run, as in bw <- npudensbw(formula=~ordered(year)+gdp, bws=c(1, 1)) summary(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous. data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # We compute bandwidths for the kernel density estimator using the # normal-reference rule-of-thumb. Otherwise, we use the defaults (second # order Gaussian kernel, fixed bandwidths). Note that the bandwidth # object you compute inherits all properties of the estimator (kernel # type, kernel order, estimation method) and can be fed directly into # the plotting utility plot() or into the npudens() function. bw <- npudensbw(dat=data, bwmethod="normal-reference") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, specify a value for the bandwidths manually (0.5 for the first # variable, 1.0 for the second)... bw <- npudensbw(dat=data, bws=c(0.5, 1.0), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, if you wanted to use the 1.06 sigma n^{-1/(2p+q)} rule-of-thumb # for the bandwidth for the continuous variable and, say, no smoothing # for the discrete variable, you would use the bwscaling=TRUE argument # and feed in the values 0 for the first variable (year) and 1.06 for # the second (gdp). Note that in the printout it reports the `scale # factors' rather than the `bandwidth' as reported in some of the # previous examples. bw <- npudensbw(dat=data, bws=c(0, 1.06), bwscaling=TRUE, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you wished to use, say, an eighth order Epanechnikov kernel for the # continuous variables and specify your own bandwidths, you could do # that as follows: bw <- npudensbw(dat=data, bws=c(0.5, 1.0), bandwidth.compute=FALSE, ckertype="epanechnikov", ckerorder=8) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you preferred, say, nearest-neighbor bandwidths and a generalized # kernel estimator for the continuous variable, you would use the # bwtype="generalized_nn" argument. bw <- npudensbw(dat=data, bwtype = "generalized_nn") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, compute bandwidths using likelihood cross-validation, fixed # bandwidths, and a second order Gaussian kernel for the continuous # variable (default). Note - this may take a few minutes depending on # the speed of your computer. bw <- npudensbw(dat=data) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Finally, if you wish to use initial values for numerical search, you # can either provide a vector of bandwidths as in bws=c(...) or a # bandwidth object from a previous run, as in bw <- npudensbw(dat=data, bws=c(1, 1)) summary(bw) }) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous. data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # We compute bandwidths for the kernel density estimator using the # normal-reference rule-of-thumb. Otherwise, we use the defaults (second # order Gaussian kernel, fixed bandwidths). Note that the bandwidth # object you compute inherits all properties of the estimator (kernel # type, kernel order, estimation method) and can be fed directly into # the plotting utility plot() or into the npudens() function. bw <- npudensbw(formula=~ordered(year)+gdp, bwmethod="normal-reference") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, specify a value for the bandwidths manually (0.5 for the first # variable, 1.0 for the second)... bw <- npudensbw(formula=~ordered(year)+gdp, bws=c(0.5, 1.0), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, if you wanted to use the 1.06 sigma n^{-1/(2p+q)} rule-of-thumb # for the bandwidth for the continuous variable and, say, no smoothing # for the discrete variable, you would use the bwscaling=TRUE argument # and feed in the values 0 for the first variable (year) and 1.06 for # the second (gdp). Note that in the printout it reports the `scale # factors' rather than the `bandwidth' as reported in some of the # previous examples. bw <- npudensbw(formula=~ordered(year)+gdp, bws=c(0, 1.06), bwscaling=TRUE, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you wished to use, say, an eighth order Epanechnikov kernel for the # continuous variables and specify your own bandwidths, you could do # that as follows. bw <- npudensbw(formula=~ordered(year)+gdp, bws=c(0.5, 1.0), bandwidth.compute=FALSE, ckertype="epanechnikov", ckerorder=8) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you preferred, say, nearest-neighbor bandwidths and a generalized # kernel estimator for the continuous variable, you would use the # bwtype="generalized_nn" argument. bw <- npudensbw(formula=~ordered(year)+gdp, bwtype = "generalized_nn") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, compute bandwidths using likelihood cross-validation, fixed # bandwidths, and a second order Gaussian kernel for the continuous # variable (default). Note - this may take a few minutes depending on # the speed of your computer. bw <- npudensbw(formula=~ordered(year)+gdp) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Finally, if you wish to use initial values for numerical search, you # can either provide a vector of bandwidths as in bws=c(...) or a # bandwidth object from a previous run, as in bw <- npudensbw(formula=~ordered(year)+gdp, bws=c(1, 1)) summary(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous. data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # We compute bandwidths for the kernel density estimator using the # normal-reference rule-of-thumb. Otherwise, we use the defaults (second # order Gaussian kernel, fixed bandwidths). Note that the bandwidth # object you compute inherits all properties of the estimator (kernel # type, kernel order, estimation method) and can be fed directly into # the plotting utility plot() or into the npudens() function. bw <- npudensbw(dat=data, bwmethod="normal-reference") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, specify a value for the bandwidths manually (0.5 for the first # variable, 1.0 for the second)... bw <- npudensbw(dat=data, bws=c(0.5, 1.0), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, if you wanted to use the 1.06 sigma n^{-1/(2p+q)} rule-of-thumb # for the bandwidth for the continuous variable and, say, no smoothing # for the discrete variable, you would use the bwscaling=TRUE argument # and feed in the values 0 for the first variable (year) and 1.06 for # the second (gdp). Note that in the printout it reports the `scale # factors' rather than the `bandwidth' as reported in some of the # previous examples. bw <- npudensbw(dat=data, bws=c(0, 1.06), bwscaling=TRUE, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you wished to use, say, an eighth order Epanechnikov kernel for the # continuous variables and specify your own bandwidths, you could do # that as follows: bw <- npudensbw(dat=data, bws=c(0.5, 1.0), bandwidth.compute=FALSE, ckertype="epanechnikov", ckerorder=8) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you preferred, say, nearest-neighbor bandwidths and a generalized # kernel estimator for the continuous variable, you would use the # bwtype="generalized_nn" argument. bw <- npudensbw(dat=data, bwtype = "generalized_nn") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, compute bandwidths using likelihood cross-validation, fixed # bandwidths, and a second order Gaussian kernel for the continuous # variable (default). Note - this may take a few minutes depending on # the speed of your computer. bw <- npudensbw(dat=data) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Finally, if you wish to use initial values for numerical search, you # can either provide a vector of bandwidths as in bws=c(...) or a # bandwidth object from a previous run, as in bw <- npudensbw(dat=data, bws=c(1, 1)) summary(bw) }) ## End(Not run)
Constructs the unconditional density hat operator associated with
npudens bandwidth objects. The returned operator maps a
right-hand side y to ; with y = 1 this reproduces the
fitted unconditional density.
npudenshat(bws, tdat = stop("training data 'tdat' missing"), edat, y = NULL, output = c("matrix", "apply"))npudenshat(bws, tdat = stop("training data 'tdat' missing"), edat, y = NULL, output = c("matrix", "apply"))
These arguments identify the fitted bandwidth object, training data, and evaluation data.
bws |
A fitted unconditional density bandwidth object of class |
edat |
Optional evaluation data. If omitted, the operator is built on the training data. |
tdat |
Training data used to construct the operator. |
These arguments control whether the operator is returned as a matrix or applied directly.
output |
Either |
y |
Optional right-hand side vector or matrix with one row per training observation. |
For output = "matrix", the return value is a matrix with class
c("npudenshat", "matrix") and attributes storing the bandwidth object,
training data, evaluation data, and call metadata.
For output = "apply", the function returns H y directly. Matrix
right-hand sides are applied column-wise.
This helper is intended for object-fed repeated evaluation once a bandwidth object has already been constructed. It does not perform bandwidth selection.
Either a hat matrix of class "npudenshat" or the applied result
H y, depending on output.
## Not run: data(cps71) tx <- data.frame(age = cps71$age) bw <- npudensbw(dat = tx, bwtype = "fixed", bandwidth.compute = FALSE, bws = 1.0) H <- npudenshat(bws = bw, tdat = tx) dens.hat <- npudenshat(bws = bw, tdat = tx, y = rep(1, nrow(tx)), output = "apply") dens.core <- fitted(npudens(bws = bw, tdat = tx)) head(cbind(dens.core, dens.hat), n = 2L) ## End(Not run)## Not run: data(cps71) tx <- data.frame(age = cps71$age) bw <- npudensbw(dat = tx, bwtype = "fixed", bandwidth.compute = FALSE, bws = 1.0) H <- npudenshat(bws = bw, tdat = tx) dens.hat <- npudenshat(bws = bw, tdat = tx, y = rep(1, nrow(tx)), output = "apply") dens.core <- fitted(npudens(bws = bw, tdat = tx)) head(cbind(dens.core, dens.hat), n = 2L) ## End(Not run)
npudist computes kernel unconditional cumulative distribution
estimates on evaluation data, given a set of training data and a
bandwidth specification (a dbandwidth object or a bandwidth
vector, bandwidth type, and kernel type) using the method of Li, Li
and Racine (2017).
npudist(bws, ...) ## S3 method for class 'formula' npudist(bws, data = NULL, newdata = NULL, ...) ## S3 method for class 'dbandwidth' npudist(bws, tdat = stop("invoked without training data 'tdat'"), edat, ..., se = FALSE) ## Default S3 method: npudist(bws, tdat, ..., se = FALSE)npudist(bws, ...) ## S3 method for class 'formula' npudist(bws, data = NULL, newdata = NULL, ...) ## S3 method for class 'dbandwidth' npudist(bws, tdat = stop("invoked without training data 'tdat'"), edat, ..., se = FALSE) ## Default S3 method: npudist(bws, tdat, ..., se = FALSE)
se |
Logical; compute and retain asymptotic standard errors when
|
These arguments identify the bandwidth specification, formula/data interface, and training data.
bws |
a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object
coercible to a data frame by |
tdat |
a |
These arguments control where the fitted cumulative distribution is evaluated.
edat |
a |
newdata |
An optional data frame in which to look for evaluation data. If omitted, the training data are used. |
Further arguments are passed to npudistbw when bandwidths are computed internally, or used to interpret a numeric bws vector.
... |
additional arguments supplied to |
With generalized nearest-neighbor bandwidths, query identity matters when
selecting a radius: a training observation excludes its own occurrence,
whereas explicit evaluation data remain external queries even if their
values equal training observations. Consequently,
predict(fit, newdata = training.data) can differ from
fitted(fit). This does not omit the training contribution from the
fitted estimator. See np.kernels for the radius convention.
For native (non-formula) objects, named newdata columns are matched
to the retained variable names and reordered as needed. Extra columns are
ignored; missing, duplicate or ambiguous names are errors. An unnamed
matrix or vector remains positional for a single evaluation role.
Explicit native evaluation arguments retain their positional contract and
take precedence over newdata.
For a native bandwidth object, newdata supplies edat;
explicitly supplied native evaluation arguments take precedence. This
evaluates at the requested rows without repeating bandwidth selection.
With bwtype="adaptive_nn" and se=TRUE, standard errors
include the same-sample influence of each donor-centred nearest-neighbour
radius. A two-sided rank-spacing pilot estimates the marginal density sum
at the radius endpoints. Cross-coordinate and categorical-kernel covariance
are retained in the joint observation influence. The selected NN ranks
are treated as fixed; bandwidth-selection uncertainty is not included.
This calculation supports Gaussian and Epanechnikov kernels of orders
2, 4, 6 and 8, and uniform kernels, without finite kernel bounds.
Uniform density errors additionally include moving-support boundary
influences with joint other-coordinate and categorical kernel marks.
These use type-7 sample-quantile endpoints and deterministic two-sided
rank-spacing pilots whose interior window grows as the two-thirds power
of sample size. A strictly absent support face contributes zero; an exact
probability endpoint or undefined finite-face pilot is unavailable.
Finite kernel bounds (including beta kernels), extended or saturated NN
ranks, and degenerate pilot spacings are not
currently qualified: point estimates are retained and standard errors
are NA, with one availability notice. No additional uncertainty
computation is performed for se=FALSE. Requested adaptive-NN
standard errors can take several times as long as the point fit because
they include the donor-radius influence calculation; this cost is incurred
only when standard errors are requested.
For ordinary kernels with mixed continuous and ordered categorical data, fixed and generalized-nearest-neighbour standard errors retain the leading continuous-indicator approximation and the squared integrated categorical kernel product. The continuous integrated kernel remains to power one in that second moment; this is not a finite-smoothing sample-contribution variance. Purely continuous and purely categorical conventions are unchanged. Generalized-NN errors condition on the current query radii. The separate adaptive-NN influence calculation is described above.
Documentation guide: see npudistbw for bandwidth
selection and search controls, np.kernels for kernels,
np.options for global options, and plot,
plot.np for plotting options.
When bws is omitted, the formula and default methods call
npudistbw first and pass bandwidth-selection arguments
from ... to that call. When bws is already a
dbandwidth object, npudist estimates with the stored
bandwidth metadata in that object.
With finite continuous bounds, npudist uses the
observation-centered truncated-kernel CDF documented in
np.kernels. It is exactly zero and one at the declared
lower and upper endpoints and has the linear uniform-CDF limit as the
bandwidth diverges.
The beta associated CDF is available at orders 2, 4, 6, and 8 with manual
or cross-validated metric bandwidths. Fixed, generalized-NN, and adaptive-NN
modes are supported. Set ckertype="beta" and use either
ckerbound="fixed" with finite ckerlb/ckerub, or
ckerbound="range" for beta outer half-spacing sample bounds. The data must
be continuous and all training and evaluation values must lie within the
resulting supports. Categorical products and normal-reference selection are
not supported.
For observation , target , support ,
, , , and
, the contribution is
The returned estimate is the sample mean of these contributions; its
reported standard error is the sample standard deviation of the
multivariate contribution divided by . The implementation
accumulates this variance in centered form to avoid cancellation near zero
or one. This beta CDF is observation-centered and is not the target-variable
integral of Chen's evaluation-centered beta density kernel. See
np.kernels for the design rationale and references.
Fixed and adaptive order-2 beta CDF estimates are proper CDFs on the
declared support. A generalized-NN order-2 curve retains exact endpoints
and contribution-wise range but may be locally nonmonotone because its
bandwidth changes with the target. Orders 4, 6, and 8 are signed and may
overshoot or be locally nonmonotone in any bandwidth mode.
Returned values are not silently clipped or monotonized.
For purely ordered data, let be the complete multivariate CDF
contribution and . Standard errors use
the empirical-population variance of these contributions divided by
sample size,
At zero smoothing this retains the usual
. At finite smoothing a contribution
need not be an indicator, so the Bernoulli expression does not generally
apply. Profile compression retains original observation multiplicities.
Argument groups for bandwidth selection are documented on
npudistbw. The most common workflow is to choose data
and bandwidth inputs first, then bandwidth criterion and
representation, then kernel/support controls, distribution-specific
integral/grid controls, and numerical search controls if defaults
need to be changed.
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
Typical usages are (see below for a complete list of options and also the examples at the end of this help file)
Usage 1: first compute the bandwidth object via npudistbw and then
compute the cumulative distribution:
bw <- npudistbw(~y)
Fhat <- npudist(bw)
Usage 2: alternatively, compute the bandwidth object indirectly:
Fhat <- npudist(~y)
Usage 3: modify the default kernel and order:
Fhat <- npudist(~y, ckertype="epanechnikov", ckerorder=4)
Usage 4: use the data frame interface rather than the formula
interface:
Fhat <- npudist(tdat = y, ckertype="epanechnikov", ckerorder=4)
npudist implements a variety of methods for estimating
multivariate cumulative distributions (-variate) defined over a
set of possibly continuous and/or discrete (ordered) data. The
approach is based on Li and Racine (2003) who employ
‘generalized product kernels’ that admit a mix of continuous
and discrete data types.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating
the cumulative distribution at the point . Generalized nearest-neighbor
bandwidths change with the point at which the cumulative distribution is estimated,
. Fixed bandwidths are constant over the support of .
Data contained in the data frame tdat (and also edat)
may be a mix of continuous (default) and ordered discrete (to be
specified in the data frame tdat using the
ordered command). Data can be entered in an arbitrary
order and data types will be detected automatically by the routine
(see np for details).
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth-order Gaussian and Epanechnikov kernels, and the uniform kernel. Ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
Standard errors are opt-in. To add them to an existing fit without
repeating bandwidth selection, use
fit <- npudist(bws=fit$bws, se=TRUE), supplying the original
training data and desired evaluation data again when these cannot be
recovered from the bandwidth object's call. The se() extractor
reads retained errors only and gives a helpful refit message when they
were not requested. Use predict(fit, se.fit=TRUE, ...) for
prediction with standard errors.
npudist returns a npdistribution object. The
generic accessor functions fitted and se
extract estimated values and asymptotic standard errors on estimates,
respectively, from the returned object. Furthermore, the functions
predict, summary and plot
support objects of both classes. The returned objects have the
following components:
eval |
the evaluation points. |
dist |
estimate of the cumulative distribution at the evaluation points |
derr |
Standard errors of the cumulative distribution estimates when
|
se |
Whether standard-error computation was requested. |
The unconditional distribution target is .
The estimator replaces the density kernel factors by integrated
distribution-kernel factors where appropriate, while retaining the
same mixed-data product-kernel logic for continuous and ordered
components. The returned standard errors are asymptotic standard
errors for the estimated cumulative distribution values.
For book-length derivations, see Li and Racine (2007), Chapter 1 Density Estimation, especially Sections 1.4 and 1.5 for CDF estimation and bandwidth selection, together with Chapter 4 Kernel Estimation with Mixed Data. The later workflow treatment is Racine (2019), Chapter 2 Continuous Density and Cumulative Distribution Functions and Chapter 3 Mixed-Data Probability Density and Cumulative Distribution Functions.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
For formula fits, character-valued missing-data policies are resolved
through the stats model-frame owner; pass a caller-local policy as
a function object rather than its name. With replacement training data,
an explicit na.action, including NULL, takes precedence
over the saved policy. Native fitting still requires complete rows, so
a permissive policy does not guarantee the same retained sample as
stats::model.frame.
When reusing a bandwidth object without explicit training or evaluation
data, newly constructed bandwidth objects use retained training values.
A fit with explicit replacement training data retains that sample in its
returned bandwidth object; evaluation grids do not replace training data.
Older objects without retained samples use their stored call environment
when available and may require explicit training inputs after
saveRDS() and readRDS(). Custom formula transformations used
on new evaluation data must still be available.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “ Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2003), “Nonparametric estimation of distributions with categorical and continuous data,” Journal of Multivariate Analysis, 86, 266-292.
Li, C. and H. Li and J.S. Racine (2017), “Cross-Validated Mixed Datatype Bandwidth Selection for Nonparametric Cumulative Distribution/Survivor Functions,” Econometric Reviews, 36, 970-987.
Chen, S.X. (1999), “Beta kernel estimators for density functions,” Computational Statistics & Data Analysis, 31(2), 131–145. doi:10.1016/S0167-9473(99)00010-9.
Igarashi, G. and Kakizawa, Y. (2020), “Higher-order bias corrections for asymmetric kernel density estimators,” Journal of Nonparametric Statistics, 32(3), 716–752. doi:10.1080/10485252.2020.1770754.
Mansouri, B., Rastin, A., and Allah Mombeni, H. (2024), “Beta Kernel Estimator for a Cumulative Distribution Function with Bounded Support,” Journal of Sciences, Islamic Republic of Iran, 34(4), 349–361 (volume dated 2023; accepted and DOI registered in 2024). doi:10.22059/jsciences.2024.367933.1007836.
Ouyang, D. and Q. Li and J.S. Racine (2006), “Cross-validation and the estimation of probability distributions with categorical data,” Journal of Nonparametric Statistics, 18, 69-100.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Scott, D.W. (1992), Multivariate Density Estimation. Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np npudistbw , density
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous, # compute bandwidths using cross-validation, then create a grid of data # on which the cumulative distribution will be evaluated for plotting # purposes. data("Italy") with(Italy, { # Compute bandwidths using cross-validation (default). bw <- npudistbw(formula=~ordered(year)+gdp) # At this stage you could use npudist() to do a variety of things. Here # we compute the npudist() object and place it in Fhat. Fhat <- npudist(bws=bw) # Note that simply typing the name of the object returns some useful # information. For more info, one can call summary: summary(Fhat) # Next, we illustrate how to create a grid of `evaluation data' and feed # it to the perspective plotting routines in R, among others. # Create an evaluation data matrix year.seq <- sort(unique(year)) gdp.seq <- seq(1,36,length=50) data.eval <- expand.grid(year=year.seq,gdp=gdp.seq) # Generate the estimated cumulative distribution computed for the # evaluation data Fhat <- fitted(npudist(bws=bw, newdata=data.eval)) # Coerce the data into a matrix for plotting with persp() Fhat <- matrix(Fhat, length(unique(year)), 50) # Next, create a 3D perspective plot of the CDF F, and a 2D # contour plot. persp(as.integer(levels(year.seq)), gdp.seq, Fhat, col="lightblue", ticktype="detailed", ylab="GDP", xlab="Year", zlab="Density", theta=300, phi=50) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) contour(as.integer(levels(year.seq)), gdp.seq, Fhat, xlab="Year", ylab="GDP", main = "Cumulative Distribution Contour Plot", col=topo.colors(100)) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Alternatively, you could use the plot() command (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous, # compute bandwidths using cross-validation, then create a grid of data # on which the cumulative distribution will be evaluated for plotting # purposes. data("Italy") with(Italy, { data <- data.frame(year=ordered(year), gdp) # Compute bandwidths using cross-validation (default). bw <- npudistbw(dat=data) # At this stage you could use npudist() to do a variety of # things. Here we compute the npudist() object and place it in Fhat. Fhat <- npudist(bws=bw) # Note that simply typing the name of the object returns some useful # information. For more info, one can call summary: summary(Fhat) # Next, we illustrate how to create a grid of `evaluation data' and feed # it to the perspective plotting routines in R, among others. # Create an evaluation data matrix year.seq <- sort(unique(year)) gdp.seq <- seq(1,36,length=50) data.eval <- expand.grid(year=year.seq,gdp=gdp.seq) # Generate the estimated cumulative distribution computed for the # evaluation data Fhat <- fitted(npudist(edat = data.eval, bws=bw)) # Coerce the data into a matrix for plotting with persp() Fhat <- matrix(Fhat, length(unique(year)), 50) # Next, create a 3D perspective plot of the CDF F, and a 2D # contour plot. persp(as.integer(levels(year.seq)), gdp.seq, Fhat, col="lightblue", ticktype="detailed", ylab="GDP", xlab="Year", zlab="Cumulative Distribution", theta=300, phi=50) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) contour(as.integer(levels(year.seq)), gdp.seq, Fhat, xlab="Year", ylab="GDP", main = "Cumulative Distribution Contour Plot", col=topo.colors(100)) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Alternatively, you could use the plot() command (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=FORMULA): For this example, we load the old # faithful geyser data and compute the cumulative distribution function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npudistbw(formula=~eruptions+waiting) summary(bw) # Plot the cumulative distribution function (<ctrl>-C will interrupt on # *NIX systems, <esc> will interrupt on MS Windows systems). Note that # we use xtrim = -0.2 to extend the plot outside the support of the data # (i.e., extend the tails of the estimate to meet the horizontal axis). if (interactive()) plot(bw, xtrim=-0.2) }) # EXAMPLE 2 (INTERFACE=DATA FRAME): For this example, we load the old # faithful geyser data and compute the cumulative distribution function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npudistbw(dat=faithful) summary(bw) # Plot the cumulative distribution function (<ctrl>-C will interrupt on # *NIX systems, <esc> will interrupt on MS Windows systems). Note that # we use xtrim = -0.2 to extend the plot outside the support of the data # (i.e., extend the tails of the estimate to meet the horizontal axis). if (interactive()) plot(bw, xtrim=-0.2) }) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous, # compute bandwidths using cross-validation, then create a grid of data # on which the cumulative distribution will be evaluated for plotting # purposes. data("Italy") with(Italy, { # Compute bandwidths using cross-validation (default). bw <- npudistbw(formula=~ordered(year)+gdp) # At this stage you could use npudist() to do a variety of things. Here # we compute the npudist() object and place it in Fhat. Fhat <- npudist(bws=bw) # Note that simply typing the name of the object returns some useful # information. For more info, one can call summary: summary(Fhat) # Next, we illustrate how to create a grid of `evaluation data' and feed # it to the perspective plotting routines in R, among others. # Create an evaluation data matrix year.seq <- sort(unique(year)) gdp.seq <- seq(1,36,length=50) data.eval <- expand.grid(year=year.seq,gdp=gdp.seq) # Generate the estimated cumulative distribution computed for the # evaluation data Fhat <- fitted(npudist(bws=bw, newdata=data.eval)) # Coerce the data into a matrix for plotting with persp() Fhat <- matrix(Fhat, length(unique(year)), 50) # Next, create a 3D perspective plot of the CDF F, and a 2D # contour plot. persp(as.integer(levels(year.seq)), gdp.seq, Fhat, col="lightblue", ticktype="detailed", ylab="GDP", xlab="Year", zlab="Density", theta=300, phi=50) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) contour(as.integer(levels(year.seq)), gdp.seq, Fhat, xlab="Year", ylab="GDP", main = "Cumulative Distribution Contour Plot", col=topo.colors(100)) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Alternatively, you could use the plot() command (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous, # compute bandwidths using cross-validation, then create a grid of data # on which the cumulative distribution will be evaluated for plotting # purposes. data("Italy") with(Italy, { data <- data.frame(year=ordered(year), gdp) # Compute bandwidths using cross-validation (default). bw <- npudistbw(dat=data) # At this stage you could use npudist() to do a variety of # things. Here we compute the npudist() object and place it in Fhat. Fhat <- npudist(bws=bw) # Note that simply typing the name of the object returns some useful # information. For more info, one can call summary: summary(Fhat) # Next, we illustrate how to create a grid of `evaluation data' and feed # it to the perspective plotting routines in R, among others. # Create an evaluation data matrix year.seq <- sort(unique(year)) gdp.seq <- seq(1,36,length=50) data.eval <- expand.grid(year=year.seq,gdp=gdp.seq) # Generate the estimated cumulative distribution computed for the # evaluation data Fhat <- fitted(npudist(edat = data.eval, bws=bw)) # Coerce the data into a matrix for plotting with persp() Fhat <- matrix(Fhat, length(unique(year)), 50) # Next, create a 3D perspective plot of the CDF F, and a 2D # contour plot. persp(as.integer(levels(year.seq)), gdp.seq, Fhat, col="lightblue", ticktype="detailed", ylab="GDP", xlab="Year", zlab="Cumulative Distribution", theta=300, phi=50) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) contour(as.integer(levels(year.seq)), gdp.seq, Fhat, xlab="Year", ylab="GDP", main = "Cumulative Distribution Contour Plot", col=topo.colors(100)) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Alternatively, you could use the plot() command (<ctrl>-C will # interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems). if (interactive()) plot(bw) }) # EXAMPLE 2 (INTERFACE=FORMULA): For this example, we load the old # faithful geyser data and compute the cumulative distribution function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npudistbw(formula=~eruptions+waiting) summary(bw) # Plot the cumulative distribution function (<ctrl>-C will interrupt on # *NIX systems, <esc> will interrupt on MS Windows systems). Note that # we use xtrim = -0.2 to extend the plot outside the support of the data # (i.e., extend the tails of the estimate to meet the horizontal axis). if (interactive()) plot(bw, xtrim=-0.2) }) # EXAMPLE 2 (INTERFACE=DATA FRAME): For this example, we load the old # faithful geyser data and compute the cumulative distribution function. library("datasets") data("faithful") with(faithful, { # Note - this may take a few minutes depending on the speed of your # computer... bw <- npudistbw(dat=faithful) summary(bw) # Plot the cumulative distribution function (<ctrl>-C will interrupt on # *NIX systems, <esc> will interrupt on MS Windows systems). Note that # we use xtrim = -0.2 to extend the plot outside the support of the data # (i.e., extend the tails of the estimate to meet the horizontal axis). if (interactive()) plot(bw, xtrim=-0.2) }) ## End(Not run)
npudistbw computes a bandwidth object for a -variate
kernel cumulative distribution estimator defined over mixed continuous
and discrete (ordered) data using either the normal reference
rule-of-thumb or least-squares cross validation using the method of
Li, Li and Racine (2017).
npudistbw(...) ## S3 method for class 'formula' npudistbw(formula, data, subset, na.action, call, gdata = NULL, ...) ## S3 method for class 'dbandwidth' npudistbw(dat = stop("invoked without input data 'dat'"), bws, gdat = NULL, bandwidth.compute = TRUE, cfac.dir = 2.5*(3.0-sqrt(5)), scale.factor.init = 0.5, dfac.dir = 0.25*(3.0-sqrt(5)), dfac.init = 0.375, dfc.dir = 3, do.full.integral = FALSE, ftol = 1.490116e-07, scale.factor.init.upper = 2.0, hbd.dir = 1, hbd.init = 0.9, initc.dir = 1.0, initd.dir = 1.0, invalid.penalty = c("baseline","dbmax"), itmax = 10000, lbc.dir = 0.5, scale.factor.init.lower = 0.1, lbd.dir = 0.1, lbd.init = 0.1, memfac = 500.0, ngrid = 100, nmulti, penalty.multiplier = 10, powell.remin = TRUE, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample = FALSE, scale.factor.search.lower = NULL, small = 1.490116e-05, tol = 1.490116e-04, transform.bounds = FALSE, eval.only = FALSE, ..., nomad.opts = list()) ## Default S3 method: npudistbw(dat = stop("invoked without input data 'dat'"), bws, gdat, bandwidth.compute = TRUE, bwmethod, bwscaling, bwtype, cfac.dir, scale.factor.init, ckerbound, ckerlb, ckerorder, ckertype, ckerub, dfac.dir, dfac.init, dfc.dir, do.full.integral, ftol, scale.factor.init.upper, hbd.dir, hbd.init, initc.dir, initd.dir, invalid.penalty, itmax, lbc.dir, scale.factor.init.lower, lbd.dir, lbd.init, memfac, ngrid, nmulti, okertype, penalty.multiplier, powell.remin, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample, scale.factor.search.lower = NULL, small, tol, transform.bounds, ..., nomad.opts = list())npudistbw(...) ## S3 method for class 'formula' npudistbw(formula, data, subset, na.action, call, gdata = NULL, ...) ## S3 method for class 'dbandwidth' npudistbw(dat = stop("invoked without input data 'dat'"), bws, gdat = NULL, bandwidth.compute = TRUE, cfac.dir = 2.5*(3.0-sqrt(5)), scale.factor.init = 0.5, dfac.dir = 0.25*(3.0-sqrt(5)), dfac.init = 0.375, dfc.dir = 3, do.full.integral = FALSE, ftol = 1.490116e-07, scale.factor.init.upper = 2.0, hbd.dir = 1, hbd.init = 0.9, initc.dir = 1.0, initd.dir = 1.0, invalid.penalty = c("baseline","dbmax"), itmax = 10000, lbc.dir = 0.5, scale.factor.init.lower = 0.1, lbd.dir = 0.1, lbd.init = 0.1, memfac = 500.0, ngrid = 100, nmulti, penalty.multiplier = 10, powell.remin = TRUE, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample = FALSE, scale.factor.search.lower = NULL, small = 1.490116e-05, tol = 1.490116e-04, transform.bounds = FALSE, eval.only = FALSE, ..., nomad.opts = list()) ## Default S3 method: npudistbw(dat = stop("invoked without input data 'dat'"), bws, gdat, bandwidth.compute = TRUE, bwmethod, bwscaling, bwtype, cfac.dir, scale.factor.init, ckerbound, ckerlb, ckerorder, ckertype, ckerub, dfac.dir, dfac.init, dfc.dir, do.full.integral, ftol, scale.factor.init.upper, hbd.dir, hbd.init, initc.dir, initd.dir, invalid.penalty, itmax, lbc.dir, scale.factor.init.lower, lbd.dir, lbd.init, memfac, ngrid, nmulti, okertype, penalty.multiplier, powell.remin, bwsolver = c("powell", "mads", "mads+powell"), scale.init.categorical.sample, scale.factor.search.lower = NULL, small, tol, transform.bounds, ..., nomad.opts = list())
These arguments identify the data, formula interface, optional integration grid, and whether bandwidths are supplied or computed.
bandwidth.compute |
a logical value which specifies whether to do a numerical search for
bandwidths or not. If set to |
bws |
a bandwidth specification. This can be set as a bandwidth object
returned from a previous invocation, or as a vector of bandwidths,
with each element |
call |
the original function call. This is passed internally by
|
dat |
a |
data |
This argument belongs to the formula interface (including supported
formula-bearing bandwidth-object refits). Native calls must supply their
vectors, matrices or data frames directly, or use an optional data frame, list or environment (or object coercible to
a data frame by |
formula |
a symbolic description of variables on which bandwidth selection is to be performed. The details of constructing a formula are described below. |
gdat |
a grid of data on which the indicator function for least-squares cross-validation is to be computed (can be the sample or a grid of quantiles). |
gdata |
a grid of data on which the indicator function for least-squares cross-validation is to be computed (can be the sample or a grid of quantiles). |
na.action |
a function which indicates what should happen when the data contain
|
subset |
an optional vector specifying a subset of observations to be used in the fitting process. |
These arguments choose the selection criterion and the way continuous bandwidths are represented.
bwmethod |
a character string specifying the bandwidth selection
method. |
bwscaling |
a logical value that when set to |
bwtype |
character string used for the continuous variable bandwidth type,
specifying the type of bandwidth to compute and return in the
|
These controls set categorical search starts and categorical direction-set initialization.
dfac.dir |
stretch factor for direction set search for Powell's algorithm for categorical variables. See Details |
dfac.init |
non-random initial values for scale factors for categorical variables for Powell's algorithm. See Details |
hbd.dir |
upper bound for direction set search for Powell's algorithm for categorical variables. See Details |
hbd.init |
upper bound for scale factors for categorical variables for Powell's algorithm. See Details |
initd.dir |
initial non-random values for direction set search for Powell's algorithm for categorical variables. See Details |
lbd.dir |
lower bound for direction set search for Powell's algorithm for categorical variables. See Details |
lbd.init |
lower bound for scale factors for categorical variables for Powell's algorithm. See Details |
scale.init.categorical.sample |
a logical value that when set
to |
These controls set Powell direction-set initialization for continuous variables.
cfac.dir |
stretch factor for direction set search for Powell's algorithm for |
dfc.dir |
chi-square degrees of freedom for direction set search for Powell's algorithm for |
initc.dir |
initial non-random values for direction set search for Powell's algorithm for |
lbc.dir |
lower bound for direction set search for Powell's algorithm for |
These controls choose and parameterize bounded support for continuous kernels.
ckerbound |
character string controlling continuous-kernel support handling.
Can be set as |
ckerlb |
numeric scalar/vector of lower bounds for continuous variables used
when |
ckerub |
numeric scalar/vector of upper bounds for continuous variables used
when |
These controls define deterministic and random continuous scale-factor starts and the lower admissibility floor for fixed-bandwidth search.
scale.factor.init |
deterministic initial scale factor for continuous fixed-bandwidth
search. Defaults to |
scale.factor.init.lower |
lower endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.init.upper |
upper endpoint for random continuous scale-factor starts. Defaults
to |
scale.factor.search.lower |
optional nonnegative scalar giving the hard lower admissibility
bound for continuous fixed-bandwidth search candidates. Defaults to
|
These controls tune the distribution-function integral and grid calculations.
do.full.integral |
a logical value which when set as |
memfac |
The algorithm to compute the least-squares objective function uses a block-based algorithm to eliminate or minimize redundant kernel evaluations. Due to memory, hardware and software constraints, a maximum block size must be imposed by the algorithm. This block size is roughly equal to memfac*10^5 elements. Empirical tests on modern hardware find that a memfac of 500 performs well. If you experience out of memory errors, or strange behaviour for large data sets (>100k elements) setting memfac to a lower value may fix the problem. |
ngrid |
integer number of row-aligned marginal-quantile grid points to use
when |
These controls choose continuous, unordered, and ordered kernels.
ckerorder |
numeric value specifying kernel order (one of
|
ckertype |
character string used to specify the continuous kernel type.
Can be set as |
okertype |
character string used to specify the ordered categorical kernel type.
Can be set as |
These controls set optimizer tolerances, restart behavior, invalid-candidate penalties, and bounded search transformations.
ftol |
fractional tolerance on the value of the cross-validation function
evaluated at located minima (of order the machine precision or
perhaps slightly larger so as not to be diddled by
roundoff). Defaults to |
invalid.penalty |
a character string specifying the penalty
used when the optimizer encounters invalid bandwidths.
|
itmax |
integer number of iterations before failure in the numerical
optimization routine. Defaults to |
nmulti |
integer number of times to restart the process of finding extrema of the cross-validation function from different (random) initial points. |
penalty.multiplier |
a numeric multiplier applied to the
baseline penalty when |
powell.remin |
logical flag controlling Powell restart-from-minimum behavior. When
|
bwsolver |
bandwidth optimizer for fixed-degree searches. The default
|
nomad.opts |
optional named list of native NOMAD parameters forwarded to the
crs NOMAD C API for MADS/NOMAD-backed bandwidth searches.
|
small |
a small number used to bracket a minimum (it is hopeless to ask for
a bracketing interval of width less than sqrt(epsilon) times its
central value, a fractional width of only about 10-04 (single
precision) or 3x10-8 (double precision)). Defaults to |
tol |
tolerance on the position of located minima of the cross-validation
function (tol should generally be no smaller than the square root of
your machine's floating point precision). Defaults to |
transform.bounds |
a logical value that when set to |
eval.only |
internal logical flag used by solver wrappers to evaluate an
existing bandwidth candidate without running a bandwidth search.
Ordinary users should leave this at its default |
These arguments collect remaining controls passed through S3 methods.
... |
additional arguments supplied to specify the bandwidth type, kernel types, selection methods, and so on, detailed below. |
Formula bandwidth objects retain the prepared training sample (after alignment,
subsetting and missing-value handling) and the resolved missing-value policy.
Later refits use that sample even if constructor variables are rebound.
Supplying explicit training data to the estimator replaces the training data;
evaluation via newdata does not. Retention requires storage proportional
to the sample size times the number of variables, not a pairwise weight matrix.
Older saved objects without this retained state still rely on their original
data bindings; rebuild their bandwidth object from the intended data before
changing those bindings. User-defined transformation and missing-value
functions should not rely on subsequently modified closure state.
The scale.factor.* controls are dimensionless search
controls. The package converts scale factors to bandwidths using the
estimator-specific scaling encoded in the bandwidth object, including
kernel order and the number of continuous variables relevant for the
estimator. Users should not pre-multiply these controls by sample-size
or standard-deviation factors.
scale.factor.init controls the deterministic first search
start. scale.factor.init.lower and
scale.factor.init.upper define the random multistart interval.
scale.factor.search.lower is the lower admissibility bound for
continuous fixed-bandwidth search candidates. The effective first
start is max(scale.factor.init, scale.factor.search.lower),
and the effective random-start lower endpoint is
max(scale.factor.init.lower, scale.factor.search.lower).
scale.factor.init.upper must be at least that effective lower
endpoint; the package errors rather than silently expanding the user's
interval.
When scale.factor.search.lower is NULL, an existing
bandwidth object's stored floor is inherited when available;
otherwise the package default 0.1 is used. Explicit bandwidths
supplied for storage with bandwidth.compute = FALSE are not
rewritten by the search floor.
Categorical search-start controls such as dfac.init,
lbd.init, and hbd.init have separate semantics and are
not affected by scale.factor.search.lower.
Documentation guide: see np.kernels for kernels,
np.options for global options, and
plot, plot.np for plotting options.
The bandwidth-selection argument surface is easiest to read by
decision group: data, grid, and existing bandwidth inputs; bandwidth
criterion and representation; continuous kernel and support controls
beginning with cker*; ordered categorical kernel controls
such as okertype; distribution-specific integral/grid controls
such as gdat, gdata, do.full.integral, and
ngrid; and numerical search initialization, tolerances, and
feasibility controls. Users who call npudist without a
bandwidth object can pass these same bandwidth-selection controls
through that function's ....
For S3 plotting help, see plot.np. You can list
available plot methods with methods("plot").
Typical usages are (see below for a complete list of options and also the examples at the end of this help file)
Usage 1: compute a bandwidth object using the formula interface:
bw <- npudistbw(~y)
Usage 2: compute a bandwidth object using the data frame interface
and change the default kernel and order:
Fhat <- npudistbw(tdat = y, ckertype="epanechnikov", ckerorder=4)
npudistbw implements a variety of methods for choosing
bandwidths for multivariate (-variate) distributions defined
over a set of possibly continuous and/or discrete (ordered) data. The
approach is based on Li and Racine (2003) who employ
‘generalized product kernels’ that admit a mix of continuous
and discrete data types.
The cross-validation methods employ multivariate numerical search algorithms (direction set (Powell's) methods in multidimensions).
Bandwidths can (and will) differ for each variable which is, of course, desirable.
Three classes of kernel estimators for the continuous data types are
available: fixed, adaptive nearest-neighbor, and generalized
nearest-neighbor. Adaptive nearest-neighbor bandwidths change with
each sample realization in the set, , when estimating the
cumulative distribution at the point . Generalized nearest-neighbor bandwidths change
with the point at which the cumulative distribution is estimated, . Fixed bandwidths
are constant over the support of .
Nearest-neighbor cross-validation excludes the held-out observation from both the kernel sum and the sample defining the neighborhood. An empirical evaluation-grid row retains its training-query identity in that deleted sample. An explicitly supplied grid is an external evaluation grid, even when its coordinates equal observed values.
Exact ties can make the literal th continuous nearest-neighbor
radius zero. Such a bandwidth is undefined and is rejected; see
np.kernels for the precise contract and remedies.
npudistbw may be invoked either with a formula-like
symbolic description of variables on which bandwidth selection is to
be performed or through a simpler interface whereby data is
passed directly to the function via the dat parameter. Use of
these two interfaces is mutually exclusive.
Data contained in the data frame dat may be a mix of continuous
(default) and ordered discrete (to be specified in the data frame
dat using ordered). Data can be entered in an
arbitrary order and data types will be detected automatically by the
routine (see np for details).
Data for which bandwidths are to be estimated may be specified
symbolically. A typical description has the form ~ data, where
data is a series of variables specified by name, separated by
the separation character '+'. For example, ~ x + y specifies
that the bandwidths for the joint distribution of variables x
and y are to be estimated. See below for further examples.
A variety of kernels may be specified by the user. Kernels implemented for continuous data types include the second, fourth, sixth, and eighth-order Gaussian and Epanechnikov kernels, and the uniform kernel. Ordered data types use a variation of the Wang and van Ryzin (1981) kernel.
The beta associated CDF supports orders 2, 4, 6, and 8, explicit bandwidth
objects and automatic cv.cdf selection, and fixed, generalized-NN,
and adaptive-NN bandwidths. Set ckertype="beta" and use
ckerbound="fixed" with finite ckerlb/ckerub, or
ckerbound="range". Data must be continuous and lie within those
supports. Normal-reference selection and categorical products are not
supported. Unsupported specifications fail explicitly. The bandwidth
remains in the coordinate's original units and maps to beta
precision . See np.kernels and
npudist for the exact observation-centered CDF contribution.
For univariate order-2 fixed-bandwidth beta ckerbound="range" CDF
searches with Powell, the ordinary result is also checked against the
deterministic uniform-limit certificate documented in
np.kernels. This does not replace or reduce the user's
nmulti search, and the same check applies when automatic selection is
restarted from an eligible beta range bandwidth object.
The optimizer invoked for search is Powell's conjugate direction
method which requires the setting of (non-random) initial values and
search directions for bandwidths, and when restarting, random values
for successive invocations. Bandwidths for numeric variables
are scaled by robust measures of spread, the sample size, and the
number of numeric variables where appropriate. Two sets of
parameters for bandwidths for numeric can be modified, those
for initial values for the parameters themselves, and those for the
directions taken (Powell's algorithm does not involve explicit
computation of the function's gradient). The default values are set by
considering search performance for a variety of difficult test cases
and simulated cases. We highly recommend restarting search a large
number of times to avoid the presence of local minima (achieved by
modifying nmulti). Further refinement for difficult cases can
be achieved by modifying these sets of parameters. However, these
parameters are intended more for the authors of the package to enable
‘tuning’ for various methods rather than for the user them
self.
npudistbw returns a bandwidth object with the
following components:
bw |
bandwidth(s), scale factor(s) or nearest neighbours for the
data, |
fval |
objective function value at minimum |
beta.range.certification |
for an eligible automatic beta range CDF search, a list recording the uniform-limit probe, trigger decision, optional support-width refinement, and selected source; absent otherwise |
num.feval.certified |
number of function evaluations attributable to that certification and optional refinement; absent otherwise |
if bwtype is set to fixed, an object containing
bandwidths, of class bandwidth
(or scale factors if bwscaling = TRUE) is returned. If it is set to
generalized_nn or adaptive_nn, then instead the
th nearest
neighbors are returned for the continuous variables while the discrete
kernel bandwidths are returned for the discrete variables. Bandwidths
are stored under the component name bw, with each
element corresponding to column of input data
dat.
Prediction follows a two-stage contract. Calling predict(bw)
on the returned bandwidth object is a convenience forwarder for
npudist(bws = bw) and returns a fitted npdistribution
object; it does not return a numeric vector of distribution estimates.
Call fitted(fit) or predict(fit, newdata = ...) on that
fitted object to obtain numeric results. The canonical workflow is
bw <- npudistbw(~ x, data = mydata)
fit <- predict(bw) # equivalent to npudist(bws = bw)
fitted(fit)
predict(fit, newdata = newdata)
The functions summary and plot also
support dbandwidth objects.
npudistbw selects bandwidths for the unconditional distribution
target estimated by npudist.
The selected bandwidths control the integrated kernel factors used in
the mixed-data CDF estimator.
By default, data-driven bandwidth selection evaluates the CDF criterion
on a row-aligned marginal-quantile path of length ngrid. This
default is fast and useful for routine selection. To evaluate the
criterion on the empirical joint support, set
do.full.integral = TRUE; to use a user-chosen evaluation cloud or
grid, supply gdat. For multivariate data, a Cartesian product of
marginal quantiles can be supplied explicitly through gdat when
appropriate, but it is not the default because its size grows
exponentially with dimension.
Higher-order continuous CDF kernels can yield estimates that are not
globally monotone and may fall outside at some evaluation
points. Returned values are not silently clamped. Fixed and adaptive
order-2 beta CDFs remain monotone and in ; generalized-NN
order-2 curves can be locally nonmonotone because the bandwidth changes with
the target. Signed beta orders 4, 6, and 8 may additionally leave
or be locally nonmonotone in any bandwidth mode.
For book-length derivations, see Li and Racine (2007), Chapter 1 Density Estimation, especially Sections 1.4 and 1.5, and Chapter 4 Kernel Estimation with Mixed Data. The later workflow treatment is Racine (2019), Chapters 2 and 3.
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Caution: multivariate data-driven bandwidth selection methods are, by
their nature, computationally intensive. Virtually all methods
require dropping the th observation from the data set, computing an
object, repeating this for all observations in the sample, then
averaging each of these leave-one-out estimates for a given
value of the bandwidth vector, and only then repeating this a large
number of times in order to conduct multivariate numerical
minimization/maximization. Furthermore, due to the potential for local
minima/maxima, restarting this procedure a large number of times may
often be necessary. This can be frustrating for users possessing
large datasets. For exploratory purposes, you may wish to override the
default search tolerances, say, setting ftol=.01 and tol=.01 and
conduct multistarting (the default is to restart min(2, ncol(dat))
times) as is done for a number of examples. Once the procedure
terminates, you can restart search with default tolerances using those
bandwidths obtained from the less rigorous search (i.e., set
bws=bw on subsequent calls to this routine where bw is
the initial bandwidth object). A version of this package using the
Rmpi wrapper is under development that allows one to deploy
this software in a clustered computing environment to facilitate
computation involving large datasets.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Bowman, A. and P. Hall and T. Prvan (1998), “Bandwidth selection for the smoothing of distribution functions,” Biometrika, 85, 799-808.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Li, Q. and J.S. Racine (2003), “Nonparametric estimation of distributions with categorical and continuous data,” Journal of Multivariate Analysis, 86, 266-292.
Li, C. and H. Li and J.S. Racine (2017), “Cross-Validated Mixed Datatype Bandwidth Selection for Nonparametric Cumulative Distribution/Survivor Functions,” Econometric Reviews, 36, 970-987.
Ouyang, D. and Q. Li and J.S. Racine (2006), “Cross-validation and the estimation of probability distributions with categorical data,” Journal of Nonparametric Statistics, 18, 69-100.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Scott, D.W. (1992), Multivariate Cumulative Distribution Estimation: Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options, plot, plot.np
bw.nrd, bw.SJ, hist,
npudist, npudist
## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous. data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # We compute bandwidths for the kernel cumulative distribution estimator # using the normal-reference rule-of-thumb. Otherwise, we use the # defaults (second order Gaussian kernel, fixed bandwidths). Note that # the bandwidth object you compute inherits all properties of the # estimator (kernel type, kernel order, estimation method) and can be # fed directly into the plotting utility plot() or into the npudist() # function. bw <- npudistbw(formula=~ordered(year)+gdp, bwmethod="normal-reference") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, specify a value for the bandwidths manually (0.5 for the first # variable, 1.0 for the second)... bw <- npudistbw(formula=~ordered(year)+gdp, bws=c(0.5, 1.0), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, if you wanted to use the 1.587 sigma n^{-1/(2p+q)} rule-of-thumb # for the bandwidth for the continuous variable and, say, no smoothing # for the discrete variable, you would use the bwscaling=TRUE argument # and feed in the values 0 for the first variable (year) and 1.587 for # the second (gdp). Note that in the printout it reports the `scale # factors' rather than the `bandwidth' as reported in some of the # previous examples. bw <- npudistbw(formula=~ordered(year)+gdp, bws=c(0, 1.587), bwscaling=TRUE, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you wished to use, say, an eighth-order Epanechnikov kernel for the # continuous variables and specify your own bandwidths, you could do # that as follows. bw <- npudistbw(formula=~ordered(year)+gdp, bws=c(0.5, 1.0), bandwidth.compute=FALSE, ckertype="epanechnikov", ckerorder=8) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you preferred, say, nearest-neighbor bandwidths and a generalized # kernel estimator for the continuous variable, you would use the # bwtype="generalized_nn" argument. bw <- npudistbw(formula=~ordered(year)+gdp, bwtype = "generalized_nn") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, compute bandwidths using cross-validation, fixed bandwidths, and # a second-order Gaussian kernel for the continuous variable (default). # Note - this may take a few minutes depending on the speed of your # computer. bw <- npudistbw(formula=~ordered(year)+gdp) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Finally, if you wish to use initial values for numerical search, you # can either provide a vector of bandwidths as in bws=c(...) or a # bandwidth object from a previous run, as in bw <- npudistbw(formula=~ordered(year)+gdp, bws=c(1, 1)) summary(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous. data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # We compute bandwidths for the kernel cumulative distribution estimator # using the normal-reference rule-of-thumb. Otherwise, we use the # defaults (second-order Gaussian kernel, fixed bandwidths). Note that # the bandwidth object you compute inherits all properties of the # estimator (kernel type, kernel order, estimation method) and can be # fed directly into the plotting utility plot() or into the npudist() # function. bw <- npudistbw(dat=data, bwmethod="normal-reference") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, specify a value for the bandwidths manually (0.5 for the first # variable, 1.0 for the second)... bw <- npudistbw(dat=data, bws=c(0.5, 1.0), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, if you wanted to use the 1.587 sigma n^{-1/(2p+q)} rule-of-thumb # for the bandwidth for the continuous variable and, say, no smoothing # for the discrete variable, you would use the bwscaling=TRUE argument # and feed in the values 0 for the first variable (year) and 1.587 for # the second (gdp). Note that in the printout it reports the `scale # factors' rather than the `bandwidth' as reported in some of the # previous examples. bw <- npudistbw(dat=data, bws=c(0, 1.587), bwscaling=TRUE, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you wished to use, say, an eighth-order Epanechnikov kernel for the # continuous variables and specify your own bandwidths, you could do # that as follows: bw <- npudistbw(dat=data, bws=c(0.5, 1.0), bandwidth.compute=FALSE, ckertype="epanechnikov", ckerorder=8) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you preferred, say, nearest-neighbor bandwidths and a generalized # kernel estimator for the continuous variable, you would use the # bwtype="generalized_nn" argument. bw <- npudistbw(dat=data, bwtype = "generalized_nn") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, compute bandwidths using cross-validation, fixed bandwidths, and # a second order Gaussian kernel for the continuous variable (default). # Note - this may take a few minutes depending on the speed of your # computer. bw <- npudistbw(dat=data) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Finally, if you wish to use initial values for numerical search, you # can either provide a vector of bandwidths as in bws=c(...) or a # bandwidth object from a previous run, as in bw <- npudistbw(dat=data, bws=c(1, 1)) summary(bw) }) ## End(Not run)## Not run: # EXAMPLE 1 (INTERFACE=FORMULA): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous. data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # We compute bandwidths for the kernel cumulative distribution estimator # using the normal-reference rule-of-thumb. Otherwise, we use the # defaults (second order Gaussian kernel, fixed bandwidths). Note that # the bandwidth object you compute inherits all properties of the # estimator (kernel type, kernel order, estimation method) and can be # fed directly into the plotting utility plot() or into the npudist() # function. bw <- npudistbw(formula=~ordered(year)+gdp, bwmethod="normal-reference") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, specify a value for the bandwidths manually (0.5 for the first # variable, 1.0 for the second)... bw <- npudistbw(formula=~ordered(year)+gdp, bws=c(0.5, 1.0), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, if you wanted to use the 1.587 sigma n^{-1/(2p+q)} rule-of-thumb # for the bandwidth for the continuous variable and, say, no smoothing # for the discrete variable, you would use the bwscaling=TRUE argument # and feed in the values 0 for the first variable (year) and 1.587 for # the second (gdp). Note that in the printout it reports the `scale # factors' rather than the `bandwidth' as reported in some of the # previous examples. bw <- npudistbw(formula=~ordered(year)+gdp, bws=c(0, 1.587), bwscaling=TRUE, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you wished to use, say, an eighth-order Epanechnikov kernel for the # continuous variables and specify your own bandwidths, you could do # that as follows. bw <- npudistbw(formula=~ordered(year)+gdp, bws=c(0.5, 1.0), bandwidth.compute=FALSE, ckertype="epanechnikov", ckerorder=8) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you preferred, say, nearest-neighbor bandwidths and a generalized # kernel estimator for the continuous variable, you would use the # bwtype="generalized_nn" argument. bw <- npudistbw(formula=~ordered(year)+gdp, bwtype = "generalized_nn") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, compute bandwidths using cross-validation, fixed bandwidths, and # a second-order Gaussian kernel for the continuous variable (default). # Note - this may take a few minutes depending on the speed of your # computer. bw <- npudistbw(formula=~ordered(year)+gdp) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Finally, if you wish to use initial values for numerical search, you # can either provide a vector of bandwidths as in bws=c(...) or a # bandwidth object from a previous run, as in bw <- npudistbw(formula=~ordered(year)+gdp, bws=c(1, 1)) summary(bw) }) # EXAMPLE 1 (INTERFACE=DATA FRAME): For this example, we load Giovanni # Baiocchi's Italian GDP panel (see Italy for details), then create a # data frame in which year is an ordered factor, GDP is continuous. data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # We compute bandwidths for the kernel cumulative distribution estimator # using the normal-reference rule-of-thumb. Otherwise, we use the # defaults (second-order Gaussian kernel, fixed bandwidths). Note that # the bandwidth object you compute inherits all properties of the # estimator (kernel type, kernel order, estimation method) and can be # fed directly into the plotting utility plot() or into the npudist() # function. bw <- npudistbw(dat=data, bwmethod="normal-reference") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, specify a value for the bandwidths manually (0.5 for the first # variable, 1.0 for the second)... bw <- npudistbw(dat=data, bws=c(0.5, 1.0), bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, if you wanted to use the 1.587 sigma n^{-1/(2p+q)} rule-of-thumb # for the bandwidth for the continuous variable and, say, no smoothing # for the discrete variable, you would use the bwscaling=TRUE argument # and feed in the values 0 for the first variable (year) and 1.587 for # the second (gdp). Note that in the printout it reports the `scale # factors' rather than the `bandwidth' as reported in some of the # previous examples. bw <- npudistbw(dat=data, bws=c(0, 1.587), bwscaling=TRUE, bandwidth.compute=FALSE) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you wished to use, say, an eighth-order Epanechnikov kernel for the # continuous variables and specify your own bandwidths, you could do # that as follows: bw <- npudistbw(dat=data, bws=c(0.5, 1.0), bandwidth.compute=FALSE, ckertype="epanechnikov", ckerorder=8) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # If you preferred, say, nearest-neighbor bandwidths and a generalized # kernel estimator for the continuous variable, you would use the # bwtype="generalized_nn" argument. bw <- npudistbw(dat=data, bwtype = "generalized_nn") summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Next, compute bandwidths using cross-validation, fixed bandwidths, and # a second order Gaussian kernel for the continuous variable (default). # Note - this may take a few minutes depending on the speed of your # computer. bw <- npudistbw(dat=data) summary(bw) # Sleep for 5 seconds so that we can examine the output... if (interactive()) Sys.sleep(5) # Finally, if you wish to use initial values for numerical search, you # can either provide a vector of bandwidths as in bws=c(...) or a # bandwidth object from a previous run, as in bw <- npudistbw(dat=data, bws=c(1, 1)) summary(bw) }) ## End(Not run)
Constructs the unconditional distribution hat operator associated with
npudist bandwidth objects. The returned operator maps a
right-hand side y to ; with y = 1 this reproduces the
fitted unconditional distribution function.
npudisthat(bws, tdat = stop("training data 'tdat' missing"), edat, y = NULL, output = c("matrix", "apply"))npudisthat(bws, tdat = stop("training data 'tdat' missing"), edat, y = NULL, output = c("matrix", "apply"))
These arguments identify the fitted bandwidth object, training data, and evaluation data.
bws |
A fitted unconditional distribution bandwidth object of class |
edat |
Optional evaluation data. If omitted, the operator is built on the training data. |
tdat |
Training data used to construct the operator. |
These arguments control whether the operator is returned as a matrix or applied directly.
output |
Either |
y |
Optional right-hand side vector or matrix with one row per training observation. |
For output = "matrix", the return value is a matrix with class
c("npudisthat", "matrix") and attributes storing the bandwidth object,
training data, evaluation data, and call metadata.
For output = "apply", the function returns H y directly. Matrix
right-hand sides are applied column-wise.
This helper is intended for object-fed repeated evaluation once a bandwidth object has already been constructed. It does not perform bandwidth selection.
Either a hat matrix of class "npudisthat" or the applied result
H y, depending on output.
## Not run: data(cps71) tx <- data.frame(age = cps71$age) bw <- npudistbw(dat = tx, bwtype = "fixed", bandwidth.compute = FALSE, bws = 1.0) H <- npudisthat(bws = bw, tdat = tx) dist.hat <- npudisthat(bws = bw, tdat = tx, y = rep(1, nrow(tx)), output = "apply") dist.core <- fitted(npudist(bws = bw, tdat = tx)) head(cbind(dist.core, dist.hat), n = 2L) ## End(Not run)## Not run: data(cps71) tx <- data.frame(age = cps71$age) bw <- npudistbw(dat = tx, bwtype = "fixed", bandwidth.compute = FALSE, bws = 1.0) H <- npudisthat(bws = bw, tdat = tx) dist.hat <- npudisthat(bws = bw, tdat = tx, y = rep(1, nrow(tx)), output = "apply") dist.core <- fitted(npudist(bws = bw, tdat = tx)) head(cbind(dist.core, dist.hat), n = 2L) ## End(Not run)
npuniden.boundary computes kernel univariate unconditional
density estimates given a vector of continuously distributed training
data and, optionally, a bandwidth (otherwise least squares
cross-validation is used for its selection). Lower and upper bounds
[a,b] can be supplied (default is the empirical support
) and if a
is set to -Inf there is only one bound on the right, while if
b is set to Inf there is only one bound on the left. If
a is set to -Inf and b to Inf and the
Gaussian type 1 kernel function is used, this will deliver the
standard unadjusted kernel density estimate.
npuniden.boundary(X = NULL, Y = NULL, h = NULL, a = min(X), b = max(X), bwmethod = c("cv.ls","cv.ml"), cv = c("grid-hybrid","numeric"), grid = NULL, kertype = c("gaussian1","gaussian2", "beta1","beta2", "fb","fbl","fbu", "rigaussian","gamma"), nmulti = 1, proper = FALSE)npuniden.boundary(X = NULL, Y = NULL, h = NULL, a = min(X), b = max(X), bwmethod = c("cv.ls","cv.ml"), cv = c("grid-hybrid","numeric"), grid = NULL, kertype = c("gaussian1","gaussian2", "beta1","beta2", "fb","fbl","fbu", "rigaussian","gamma"), nmulti = 1, proper = FALSE)
These arguments identify evaluation points, observations, support bounds, and optional bandwidths.
a |
an optional lower bound (defaults to lower bound of empirical support |
b |
an optional upper bound (defaults to upper bound of empirical support |
h |
an optional positive bandwidth. For |
X |
a required numeric vector of training data lying in |
Y |
an optional numeric vector of evaluation data lying in |
These arguments control the boundary-corrected bandwidth search.
bwmethod |
whether to conduct bandwidth search via least squares cross-validation
( |
cv |
an optional argument for search (default is likely more reliable in the presence of local maxima) |
grid |
an optional grid used for the initial grid search when |
kertype |
an optional kernel specification (defaults to "gaussian1") |
nmulti |
number of multi-starts used when |
This argument controls optional proper-density repair.
proper |
an optional logical value indicating whether to enforce proper density
and distribution function estimates over the range |
Reported standard errors use the number of training observations in
X, not the number of requested evaluation points.
Beta kernels require finite support bounds. Their bandwidths and automatic
search starts refer to ; changing data units does not rescale
h. The "beta2" bound prevents its left and right boundary
regions from overlapping. Inadmissible explicit bandwidths or grid values
are rejected rather than clipped.
F integrates the fitted density from a to each evaluation
point, including when a=-Inf. It is independent of the order,
multiplicity and extent of the requested evaluation grid. Continuous
quadrature shares an adaptive integration representation across evaluation
points; infinite supports are transformed without truncating their tails.
The ordinary unbounded Gaussian case uses its analytic distribution function.
Accurate CDFs on sparse evaluation grids can require substantially more work
than evaluating the density at those few points. This additional work occurs
after bandwidth selection, not within the cross-validation objective.
With proper=TRUE, the positive part of the raw fitted density is
normalized by its finite positive mass over the entire declared support.
The same normalization is used for f and F; the CDF is not
separately clipped or rescaled on the requested grid. This replaces the
former constant upward shift, which could create infinite mass on unbounded
support. Failed numerical convergence or invalid normalizing mass is reported
as an error. This normalization does not alter the raw proper=FALSE
kernel definitions or cross-validation objectives.
The "gaussian2" kernel uses the continuous limit of its truncated-
moment ratios at the support midpoint. The same stable algebra also avoids
loss of these ratios when both boundary Gaussian ordinates underflow; no
different kernel is substituted. At arbitrarily large bandwidths, moments
are scaled to the declared support before taking ratios, retaining the
Gaussian2 limit rather than replacing it by a uniform kernel.
Sampled total integrals used elsewhere in this helper collapse duplicate integration coordinates, not training observations. Endpoint correction applies only on uniform grids; irregular grids use the trapezoidal rule.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
Typical usages are (see below for a complete list of options and also the examples at the end of this help file)
model <- npuniden.boundary(X,a=-2,b=3)
npuniden.boundary implements a variety of methods for
estimating a univariate density function defined over a continuous
random variable in the presence of bounds via the use of so-called
boundary or edge kernel functions.
The kernel functions "beta1" and "beta2" are Chen's
(1999) type 1 and 2 kernel functions with biases of , the
"gamma" kernel function is from Chen (2000) with a bias of
, "rigaussian" is the reciprocal inverse Gaussian
kernel function (Scaillet (2004), Igarashi & Kakizawa (2014)) with
bias of , and "gaussian1" and "gaussian2" are
truncated Gaussian kernel functions with biases of and
, respectively. The kernel functions "fb",
"fbl" and "fbu" are floating boundary polynomial
biweight kernels with biases of (Scott (1992), Page
146). Without exception, these kernel functions are asymmetric in
general with shape that changes depending on where the density is
being estimated (i.e., how close the estimation point in
is to a boundary). This function is written purely in
R, so to see the exact form for each of these kernel functions, simply
enter the name of this function in R (i.e., enter
npuniden.boundary after loading this package) and scroll up for
their definitions.
The kernel functions "gamma", "rigaussian", and
"fbl" have support . The kernel function
"fbu" has support . The rest have support on
. Note that the two sided support default values are
a=min(X) and b=max(X).
Note that data-driven bandwidth selection is more nuanced in bounded
settings, therefore it would be prudent to manually select a bandwidth
that is, say, 1/25th of the range of the data and manually inspect the
estimate (say h=0.05 when ). Also, it may be
wise to compare the density estimate with that from a histogram with
the option breaks=25. Note also that the kernel functions
"gaussian2", "fb", "fbl" and "fbu" can
assume negative values leading to potentially negative density
estimates, and must be trimmed when conducting likelihood
cross-validation which can lead to oversmoothing. Least squares
cross-validation is unaffected and appears to be more reliable in such
instances hence is the default here.
Scott (1992, Page 149) writes “While boundary kernels can be very useful, there are potentially serious problems with real data. There are an infinite number of boundary kernels reflecting the spectrum of possible design constraints, and these kernels are not interchangeable. Severe artifacts can be introduced by any one of them in inappropriate situations. Very careful examination is required to avoid being victimized by the particular boundary kernel chosen. Artifacts can unfortunately be introduced by the choice of the support interval for the boundary kernel.”
Note that since some kernel functions can assume negative values, this
can lead to improper density estimates. The estimated distribution
function is obtained via numerical integration of the estimated
density function and may itself not be proper even when evaluated on
the full range of the data . Setting the option
proper=TRUE will render the density and distribution estimates
proper over the full range of the data, though this may not in
general be a mean square error optimal strategy.
Finally, note that this function is pretty bare-bones relative to other functions in this package. For one, at this time there is no automatic print support so kindly see the examples for illustrations of its use, among other differences.
npuniden.boundary returns the following components:
f |
estimated density at |
F |
integral of the fitted density from |
sd.f |
asymptotic standard error of the estimated density at the points X |
sd.F |
asymptotic standard error of the estimated distribution at the points X |
h |
bandwidth used |
nmulti |
number of multi-starts used |
Jeffrey S. Racine [email protected]
Bouezmarni, T. and Rolin, J.-M. (2003). “Consistency of the beta kernel density function estimator,” The Canadian Journal of Statistics / La Revue Canadienne de Statistique, 31(1):89-98.
Chen, S. X. (1999). “Beta kernel estimators for density functions,” Computational Statistics & Data Analysis, 31(2):131-145.
Chen, S. X. (2000). “Probability density function estimation using gamma kernels,” Annals of the Institute of Statistical Mathematics, 52(3):471-480.
Diggle, P. (1985). “A kernel method for smoothing point process data,” Journal of the Royal Statistical Society. Series C (Applied Statistics), 34(2):138-147.
Igarashi, G. and Y. Kakizawa (2014). “Re-formulation of inverse Gaussian, reciprocal inverse Gaussian, and Birnbaum-Saunders kernel estimators,” Statistics & Probability Letters, 84:235-246.
Igarashi, G. and Y. Kakizawa (2015). “Bias corrections for some asymmetric kernel estimators,” Journal of Statistical Planning and Inference, 159:37-63.
Igarashi, G. (2016). “Bias reductions for beta kernel estimation,” Journal of Nonparametric Statistics, 28(1):1-30.
Racine, J. S. and Q. Li and Q. Wang, “Boundary-adaptive kernel density estimation: the case of (near) uniform density”, Journal of Nonparametric Statistics, 2024, 36 (1), 146-164, https://doi.org/10.1080/10485252.2023.2250011.
Scaillet, O. (2004). “Density estimation using inverse and reciprocal inverse Gaussian kernels,” Journal of Nonparametric Statistics, 16(1-2):217-226.
Scott, D. W. (1992). “Multivariate density estimation: Theory, practice, and visualization,” New York: Wiley.
Zhang, S. and R. J. Karunamuni (2010). “Boundary performance of the beta kernel estimators,” Journal of Nonparametric Statistics, 22(1):81-104.
np.kernels, np.options, plot
The Ake, bde, and Conake packages and the function npuniden.reflect.
## Not run: ## Example 1: f(0)=0, f(1)=1, plot boundary corrected density, ## unadjusted density, and DGP set.seed(42) n <- 100 X <- sort(rbeta(n,5,1)) dgp <- dbeta(X,5,1) model.g1 <- npuniden.boundary(X,kertype="gaussian1") model.g2 <- npuniden.boundary(X,kertype="gaussian2") model.b1 <- npuniden.boundary(X,kertype="beta1") model.b2 <- npuniden.boundary(X,kertype="beta2") model.fb <- npuniden.boundary(X,kertype="fb") model.unadjusted <- npuniden.boundary(X,a=-Inf,b=Inf) ylim <- c(0,max(c(dgp,model.g1$f,model.g2$f,model.b1$f,model.b2$f,model.fb$f))) if (interactive()) plot(X,dgp,ylab="Density",ylim=ylim,type="l") lines(X,model.g1$f,lty=2,col=2) lines(X,model.g2$f,lty=3,col=3) lines(X,model.b1$f,lty=4,col=4) lines(X,model.b2$f,lty=5,col=5) lines(X,model.fb$f,lty=6,col=6) lines(X,model.unadjusted$f,lty=7,col=7) rug(X) legend("topleft",c("DGP", "Boundary Kernel (gaussian1)", "Boundary Kernel (gaussian2)", "Boundary Kernel (beta1)", "Boundary Kernel (beta2)", "Boundary Kernel (floating boundary)", "Unadjusted"),col=1:7,lty=1:7,bty="n") ## Example 2: f(0)=0, f(1)=0, plot density, distribution, DGP, and ## asymptotic point-wise confidence intervals set.seed(42) X <- sort(rbeta(100,5,3)) model <- npuniden.boundary(X) oldpar <- par(no.readonly = TRUE) on.exit(par(oldpar), add = TRUE) par(mfrow=c(1,2)) ylim=range(c(model$f,model$f+1.96*model$sd.f,model$f-1.96*model$sd.f,dbeta(X,5,3))) if (interactive()) plot(X,model$f,ylim=ylim,ylab="Density",type="l",) lines(X,model$f+1.96*model$sd.f,lty=2) lines(X,model$f-1.96*model$sd.f,lty=2) lines(X,dbeta(X,5,3),col=2) rug(X) legend("topleft",c("Density","DGP"),lty=c(1,1),col=1:2,bty="n") if (interactive()) plot(X,model$F,ylab="Distribution",type="l") lines(X,model$F+1.96*model$sd.F,lty=2) lines(X,model$F-1.96*model$sd.F,lty=2) lines(X,pbeta(X,5,3),col=2) rug(X) legend("topleft",c("Distribution","DGP"),lty=c(1,1),col=1:2,bty="n") ## Example 3: Age for working age males in the cps71 data set bounded ## below by 21 and above by 65 data(cps71) with(cps71, { model <- npuniden.boundary(age,a=21,b=65) par(mfrow=c(1,1)) hist(age,prob=TRUE,main="") lines(age,model$f) lines(density(age,bw=model$h),col=2) legend("topright",c("Boundary Kernel","Unadjusted"),lty=c(1,1),col=1:2,bty="n") }) ## End(Not run)## Not run: ## Example 1: f(0)=0, f(1)=1, plot boundary corrected density, ## unadjusted density, and DGP set.seed(42) n <- 100 X <- sort(rbeta(n,5,1)) dgp <- dbeta(X,5,1) model.g1 <- npuniden.boundary(X,kertype="gaussian1") model.g2 <- npuniden.boundary(X,kertype="gaussian2") model.b1 <- npuniden.boundary(X,kertype="beta1") model.b2 <- npuniden.boundary(X,kertype="beta2") model.fb <- npuniden.boundary(X,kertype="fb") model.unadjusted <- npuniden.boundary(X,a=-Inf,b=Inf) ylim <- c(0,max(c(dgp,model.g1$f,model.g2$f,model.b1$f,model.b2$f,model.fb$f))) if (interactive()) plot(X,dgp,ylab="Density",ylim=ylim,type="l") lines(X,model.g1$f,lty=2,col=2) lines(X,model.g2$f,lty=3,col=3) lines(X,model.b1$f,lty=4,col=4) lines(X,model.b2$f,lty=5,col=5) lines(X,model.fb$f,lty=6,col=6) lines(X,model.unadjusted$f,lty=7,col=7) rug(X) legend("topleft",c("DGP", "Boundary Kernel (gaussian1)", "Boundary Kernel (gaussian2)", "Boundary Kernel (beta1)", "Boundary Kernel (beta2)", "Boundary Kernel (floating boundary)", "Unadjusted"),col=1:7,lty=1:7,bty="n") ## Example 2: f(0)=0, f(1)=0, plot density, distribution, DGP, and ## asymptotic point-wise confidence intervals set.seed(42) X <- sort(rbeta(100,5,3)) model <- npuniden.boundary(X) oldpar <- par(no.readonly = TRUE) on.exit(par(oldpar), add = TRUE) par(mfrow=c(1,2)) ylim=range(c(model$f,model$f+1.96*model$sd.f,model$f-1.96*model$sd.f,dbeta(X,5,3))) if (interactive()) plot(X,model$f,ylim=ylim,ylab="Density",type="l",) lines(X,model$f+1.96*model$sd.f,lty=2) lines(X,model$f-1.96*model$sd.f,lty=2) lines(X,dbeta(X,5,3),col=2) rug(X) legend("topleft",c("Density","DGP"),lty=c(1,1),col=1:2,bty="n") if (interactive()) plot(X,model$F,ylab="Distribution",type="l") lines(X,model$F+1.96*model$sd.F,lty=2) lines(X,model$F-1.96*model$sd.F,lty=2) lines(X,pbeta(X,5,3),col=2) rug(X) legend("topleft",c("Distribution","DGP"),lty=c(1,1),col=1:2,bty="n") ## Example 3: Age for working age males in the cps71 data set bounded ## below by 21 and above by 65 data(cps71) with(cps71, { model <- npuniden.boundary(age,a=21,b=65) par(mfrow=c(1,1)) hist(age,prob=TRUE,main="") lines(age,model$f) lines(density(age,bw=model$h),col=2) legend("topright",c("Boundary Kernel","Unadjusted"),lty=c(1,1),col=1:2,bty="n") }) ## End(Not run)
npuniden.reflect computes kernel univariate unconditional
density estimates given a vector of continuously distributed training
data and, optionally, a bandwidth (otherwise likelihood
cross-validation is used for its selection). Lower and upper bounds
[a,b] can be supplied (default is [0,1]) and if a
is set to -Inf there is only one bound on the right, while if
b is set to Inf there is only one bound on the left.
npuniden.reflect(X = NULL, Y = NULL, h = NULL, a = 0, b = 1, ...)npuniden.reflect(X = NULL, Y = NULL, h = NULL, a = 0, b = 1, ...)
These arguments identify evaluation points, observations, support bounds, and optional bandwidths.
a |
an optional lower bound (defaults to 0) |
b |
an optional upper bound (defaults to 1) |
h |
an optional bandwidth (>0) |
X |
a required numeric vector of training data lying in |
Y |
an optional numeric vector of evaluation data lying in |
Further arguments are passed to npudensbw and npudens.
... |
optional arguments passed to |
Reported standard errors use the number of training observations in
X, not the number of requested evaluation points.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
Typical usages are (see below for a complete list of options and also the examples at the end of this help file)
model <- npuniden.reflect(X,a=-2,b=3)
npuniden.reflect implements the data-reflection method for
estimating a univariate density function defined over a continuous
random variable in the presence of bounds.
Note that data-reflection imposes a zero derivative at the boundary,
i.e., .
npuniden.reflect returns the following components:
f |
estimated density at the points X |
F |
estimated distribution at the points X (numeric integral of f) |
sd.f |
asymptotic standard error of the estimated density at the points X |
sd.F |
asymptotic standard error of the estimated distribution at the points X |
h |
bandwidth used |
nmulti |
number of multi-starts used |
Jeffrey S. Racine [email protected]
Boneva, L. I., Kendall, D., and Stefanov, I. (1971). “Spline transformations: Three new diagnostic aids for the statistical data- analyst,” Journal of the Royal Statistical Society. Series B (Methodological), 33(1):1-71.
Cline, D. B. H. and Hart, J. D. (1991). “Kernel estimation of densities with discontinuities or discontinuous derivatives,” Statistics, 22(1):69-84.
Hall, P. and Wehrly, T. E. (1991). “A geometrical method for removing edge effects from kernel- type nonparametric regression estimators,” Journal of the American Statistical Association, 86(415):665-672.
np.kernels, np.options, plot
The Ake, bde, and Conake packages and the function npuniden.boundary.
## Not run: ## Example 1: f(0)=0, f(1)=1, plot boundary corrected density, ## unadjusted density, and DGP set.seed(42) n <- 100 X <- sort(rbeta(n,5,1)) dgp <- dbeta(X,5,1) model <- npuniden.reflect(X) model.unadjusted <- npuniden.boundary(X,a=-Inf,b=Inf) ylim <- c(0,max(c(dgp,model$f,model.unadjusted$f))) if (interactive()) plot(X,model$f,ylab="Density",ylim=ylim,type="l") lines(X,model.unadjusted$f,lty=2,col=2) lines(X,dgp,lty=3,col=3) rug(X) legend("topleft",c("Data-Reflection","Unadjusted","DGP"),col=1:3,lty=1:3,bty="n") ## Example 2: f(0)=0, f(1)=0, plot density, distribution, DGP, and ## asymptotic point-wise confidence intervals set.seed(42) X <- sort(rbeta(100,5,3)) model <- npuniden.reflect(X) oldpar <- par(no.readonly = TRUE) on.exit(par(oldpar), add = TRUE) par(mfrow=c(1,2)) ylim=range(c(model$f,model$f+1.96*model$sd.f,model$f-1.96*model$sd.f,dbeta(X,5,3))) if (interactive()) plot(X,model$f,ylim=ylim,ylab="Density",type="l",) lines(X,model$f+1.96*model$sd.f,lty=2) lines(X,model$f-1.96*model$sd.f,lty=2) lines(X,dbeta(X,5,3),col=2) rug(X) legend("topleft",c("Density","DGP"),lty=c(1,1),col=1:2,bty="n") if (interactive()) plot(X,model$F,ylab="Distribution",type="l") lines(X,model$F+1.96*model$sd.F,lty=2) lines(X,model$F-1.96*model$sd.F,lty=2) lines(X,pbeta(X,5,3),col=2) rug(X) legend("topleft",c("Distribution","DGP"),lty=c(1,1),col=1:2,bty="n") ## Example 3: Age for working age males in the cps71 data set bounded ## below by 21 and above by 65 data(cps71) with(cps71, { model <- npuniden.reflect(age,a=21,b=65) par(mfrow=c(1,1)) hist(age,prob=TRUE,main="",ylim=c(0,max(model$f))) lines(age,model$f) lines(density(age,bw=model$h),col=2) legend("topright",c("Data-Reflection","Unadjusted"),lty=c(1,1),col=1:2,bty="n") }) ## End(Not run)## Not run: ## Example 1: f(0)=0, f(1)=1, plot boundary corrected density, ## unadjusted density, and DGP set.seed(42) n <- 100 X <- sort(rbeta(n,5,1)) dgp <- dbeta(X,5,1) model <- npuniden.reflect(X) model.unadjusted <- npuniden.boundary(X,a=-Inf,b=Inf) ylim <- c(0,max(c(dgp,model$f,model.unadjusted$f))) if (interactive()) plot(X,model$f,ylab="Density",ylim=ylim,type="l") lines(X,model.unadjusted$f,lty=2,col=2) lines(X,dgp,lty=3,col=3) rug(X) legend("topleft",c("Data-Reflection","Unadjusted","DGP"),col=1:3,lty=1:3,bty="n") ## Example 2: f(0)=0, f(1)=0, plot density, distribution, DGP, and ## asymptotic point-wise confidence intervals set.seed(42) X <- sort(rbeta(100,5,3)) model <- npuniden.reflect(X) oldpar <- par(no.readonly = TRUE) on.exit(par(oldpar), add = TRUE) par(mfrow=c(1,2)) ylim=range(c(model$f,model$f+1.96*model$sd.f,model$f-1.96*model$sd.f,dbeta(X,5,3))) if (interactive()) plot(X,model$f,ylim=ylim,ylab="Density",type="l",) lines(X,model$f+1.96*model$sd.f,lty=2) lines(X,model$f-1.96*model$sd.f,lty=2) lines(X,dbeta(X,5,3),col=2) rug(X) legend("topleft",c("Density","DGP"),lty=c(1,1),col=1:2,bty="n") if (interactive()) plot(X,model$F,ylab="Distribution",type="l") lines(X,model$F+1.96*model$sd.F,lty=2) lines(X,model$F-1.96*model$sd.F,lty=2) lines(X,pbeta(X,5,3),col=2) rug(X) legend("topleft",c("Distribution","DGP"),lty=c(1,1),col=1:2,bty="n") ## Example 3: Age for working age males in the cps71 data set bounded ## below by 21 and above by 65 data(cps71) with(cps71, { model <- npuniden.reflect(age,a=21,b=65) par(mfrow=c(1,1)) hist(age,prob=TRUE,main="",ylim=c(0,max(model$f))) lines(age,model$f) lines(density(age,bw=model$h),col=2) legend("topright",c("Data-Reflection","Unadjusted"),lty=c(1,1),col=1:2,bty="n") }) ## End(Not run)
npuniden.sc computes shape constrained kernel univariate
unconditional density estimates given a vector of continuously
distributed training data and a bandwidth. Lower and upper bounds
[a,b] can be supplied (default is [0,1]) and if a
is set to -Inf there is only one bound on the right, while if
b is set to Inf there is only one bound on the left.
npuniden.sc(X = NULL, Y = NULL, h = NULL, a = 0, b = 1, lb = NULL, ub = NULL, extend.range = 0, num.grid = 0, function.distance = TRUE, integral.equal = FALSE, constraint = c("density", "mono.incr", "mono.decr", "concave", "convex", "log-concave", "log-convex"))npuniden.sc(X = NULL, Y = NULL, h = NULL, a = 0, b = 1, lb = NULL, ub = NULL, extend.range = 0, num.grid = 0, function.distance = TRUE, integral.equal = FALSE, constraint = c("density", "mono.incr", "mono.decr", "concave", "convex", "log-concave", "log-convex"))
These arguments identify evaluation points, observations, support bounds, and optional bandwidths.
a |
an optional lower bound on the support of |
b |
an optional upper bound on the support of |
h |
a bandwidth ( |
X |
a required numeric vector of training data lying in |
Y |
an optional numeric vector of evaluation data lying in |
These arguments set optional lower and upper density bounds used with constraint = \"density\".
lb |
an optional scalar lower bound ( |
ub |
an optional scalar upper bound ( |
These arguments control grid construction, distance metric, and mass preservation.
extend.range |
number specifying the fraction by which the range of the training data
should be extended for the additional grid points (passed to the
function |
function.distance |
a logical value that, if |
integral.equal |
a logical value, that, if |
num.grid |
number of additional grid points (in addition to |
This argument chooses the monotonicity, convexity, or log-shape constraint.
constraint |
a character string indicating whether the estimate is to be
constrained to be monotonically increasing
( |
Reported standard errors use the number of training observations in
X, not the number of requested evaluation points.
Numerical integration collapses duplicate integration coordinates, not
training observations, and restores the evaluation order and multiplicity.
Sampled total integrals use a uniform-grid endpoint correction only when
the distinct coordinates are uniformly spaced; otherwise they use the
nonuniform trapezoidal rule. The F and F.sc calculations instead
integrate the retained fitted density functions from the declared support
lower bound, including infinite support. Integration does not add QP
constraint nodes or refit the coefficients. The sampled-range normalization
selected by integral.equal is preserved; these distribution integrals
do not separately force whole-support unit mass or impose shape constraints
away from the QP grid. Log-shaped fits are integrated on the density scale.
Accurate absolute integration can add noticeable work when only a few
evaluation points are requested; its adaptive representation is reused
across points and failed convergence is reported explicitly.
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
Typical usages are (see below for a complete list of options and also the examples at the end of this help file)
model <- npuniden.sc(X,a=-2,b=3)
npuniden.sc implements a methods for estimating a univariate
density function defined over a continuous random variable in the
presence of bounds subject to a variety of shape constraints. The
bounded estimates use the truncated Gaussian kernel function.
Note that for the log-constrained estimates, the derivative estimate returned is that for the log-constrained estimate not the non-log value of the estimate returned by the function. See Example 5 below hat manually plots the log-density and returned derivative (no transformation is needed when plotting the density estimate itself).
If the quadratic program solver fails to find a solution, the
unconstrained estimate is returned with an immediate warning. Possible
causes to be investigated are undersmoothing, sparsity, and the
presence of non-sample grid points. To investigate the possibility of
undersmoothing try using a larger bandwidth, to investigate sparsity
try decreasing extend.range, and to investigate non-sample grid
points try setting num.grid to 0.
Mean square error performance seems to improve generally when using
additional grid points in the empirical support of X and
Y (i.e., in the observed range of the data sample) but appears
to deteriorate when imposing constraints beyond the empirical support
(i.e., when extend.range is positive). Increasing the number of
additional points beyond a hundred or so appears to have a limited
impact.
The option function.distance=TRUE appears to perform better for
imposing convexity, concavity, log-convexity and log-concavity, while
function.distance=FALSE appears to perform better for imposing
monotonicity, whether increasing or decreasing (based on simulations
for the Beta(s1,s2) distribution with sample size ).
A list with the following elements:
f |
unconstrained density estimate |
f.sc |
shape constrained density estimate |
se.f |
asymptotic standard error of the unconstrained density estimate |
se.f.sc |
asymptotic standard error of the shape constrained density estimate |
f.deriv |
unconstrained derivative estimate (of order 1 or 2 or log thereof) |
f.sc.deriv |
shape constrained derivative estimate (of order 1 or 2 or log thereof) |
F |
unconstrained distribution estimate |
F.sc |
shape constrained distribution estimate |
integral.f |
the integral of the unconstrained estimate over |
integral.f.sc |
the integral of the constrained estimate over |
solve.QP |
logical, if |
attempts |
number of attempts when |
Jeffrey S. Racine [email protected]
Du, P. and C. Parmeter and J. Racine (2024), “Shape Constrained Kernel PDF and PMF Estimation”, Statistica Sinica, 34 (1), 257-289, doi:10.5705/ss.202021.0112
np.kernels, np.options, plot
The logcondens, LogConDEAD, and scdensity packages,
and the function npuniden.boundary.
## Not run: n <- 100 set.seed(42) ## Example 1: N(0,1), constrain the density to lie within lb=.1 and ub=.2 X <- sort(rnorm(n)) h <- npuniden.boundary(X,a=-Inf,b=Inf)$h foo <- npuniden.sc(X,h=h,constraint="density",a=-Inf,b=Inf,lb=.1,ub=.2) ylim <- range(c(foo$f.sc,foo$f)) if (interactive()) plot(X,foo$f.sc,type="l",ylim=ylim,xlab="X",ylab="Density") lines(X,foo$f,col=2,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ## Example 2: Beta(5,1), DGP is monotone increasing, impose valid ## restriction X <- sort(rbeta(n,5,1)) h <- npuniden.boundary(X)$h foo <- npuniden.sc(X=X,h=h,constraint=c("mono.incr")) oldpar <- par(no.readonly = TRUE) on.exit(par(oldpar), add = TRUE) par(mfrow=c(1,2)) ylim <- range(c(foo$f.sc,foo$f)) if (interactive()) plot(X,foo$f.sc,type="l",ylim=ylim,xlab="X",ylab="Density") lines(X,foo$f,col=2,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ylim <- range(c(foo$f.sc.deriv,foo$f.deriv)) if (interactive()) plot(X,foo$f.sc.deriv,type="l",ylim=ylim,xlab="X",ylab="First Derivative") lines(X,foo$f.deriv,col=2,lty=2) abline(h=0,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ## Example 3: Beta(1,5), DGP is monotone decreasing, impose valid ## restriction X <- sort(rbeta(n,1,5)) h <- npuniden.boundary(X)$h foo <- npuniden.sc(X=X,h=h,constraint=c("mono.decr")) par(mfrow=c(1,2)) ylim <- range(c(foo$f.sc,foo$f)) if (interactive()) plot(X,foo$f.sc,type="l",ylim=ylim,xlab="X",ylab="Density") lines(X,foo$f,col=2,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ylim <- range(c(foo$f.sc.deriv,foo$f.deriv)) if (interactive()) plot(X,foo$f.sc.deriv,type="l",ylim=ylim,xlab="X",ylab="First Derivative") lines(X,foo$f.deriv,col=2,lty=2) abline(h=0,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ## Example 4: N(0,1), DGP is log-concave, impose invalid concavity ## restriction X <- sort(rnorm(n)) h <- npuniden.boundary(X,a=-Inf,b=Inf)$h foo <- npuniden.sc(X=X,h=h,a=-Inf,b=Inf,constraint=c("concave")) par(mfrow=c(1,2)) ylim <- range(c(foo$f.sc,foo$f)) if (interactive()) plot(X,foo$f.sc,type="l",ylim=ylim,xlab="X",ylab="Density") lines(X,foo$f,col=2,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ylim <- range(c(foo$f.sc.deriv,foo$f.deriv)) if (interactive()) plot(X,foo$f.sc.deriv,type="l",ylim=ylim,xlab="X",ylab="Second Derivative") lines(X,foo$f.deriv,col=2,lty=2) abline(h=0,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ## Example 45: Beta(3/4,3/4), DGP is convex, impose valid restriction X <- sort(rbeta(n,3/4,3/4)) h <- npuniden.boundary(X)$h foo <- npuniden.sc(X=X,h=h,constraint=c("convex")) par(mfrow=c(1,2)) ylim <- range(c(foo$f.sc,foo$f)) if (interactive()) plot(X,foo$f.sc,type="l",ylim=ylim,xlab="X",ylab="Density") lines(X,foo$f,col=2,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ylim <- range(c(foo$f.sc.deriv,foo$f.deriv)) if (interactive()) plot(X,foo$f.sc.deriv,type="l",ylim=ylim,xlab="X",ylab="Second Derivative") lines(X,foo$f.deriv,col=2,lty=2) abline(h=0,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ## Example 6: N(0,1), DGP is log-concave, impose log-concavity ## restriction X <- sort(rnorm(n)) h <- npuniden.boundary(X,a=-Inf,b=Inf)$h foo <- npuniden.sc(X=X,h=h,a=-Inf,b=Inf,constraint=c("log-concave")) par(mfrow=c(1,2)) ylim <- range(c(log(foo$f.sc),log(foo$f))) if (interactive()) plot(X,log(foo$f.sc),type="l",ylim=ylim,xlab="X",ylab="Log-Density") lines(X,log(foo$f),col=2,lty=2) rug(X) legend("topleft",c("Constrained-log","Unconstrained-log"),lty=1:2,col=1:2,bty="n") ylim <- range(c(foo$f.sc.deriv,foo$f.deriv)) if (interactive()) plot(X, foo$f.sc.deriv, type="l", ylim=ylim, xlab="X", ylab="Second Derivative of Log-Density") lines(X,foo$f.deriv,col=2,lty=2) abline(h=0,lty=2) rug(X) legend("topleft",c("Constrained-log","Unconstrained-log"),lty=1:2,col=1:2,bty="n") ## End(Not run)## Not run: n <- 100 set.seed(42) ## Example 1: N(0,1), constrain the density to lie within lb=.1 and ub=.2 X <- sort(rnorm(n)) h <- npuniden.boundary(X,a=-Inf,b=Inf)$h foo <- npuniden.sc(X,h=h,constraint="density",a=-Inf,b=Inf,lb=.1,ub=.2) ylim <- range(c(foo$f.sc,foo$f)) if (interactive()) plot(X,foo$f.sc,type="l",ylim=ylim,xlab="X",ylab="Density") lines(X,foo$f,col=2,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ## Example 2: Beta(5,1), DGP is monotone increasing, impose valid ## restriction X <- sort(rbeta(n,5,1)) h <- npuniden.boundary(X)$h foo <- npuniden.sc(X=X,h=h,constraint=c("mono.incr")) oldpar <- par(no.readonly = TRUE) on.exit(par(oldpar), add = TRUE) par(mfrow=c(1,2)) ylim <- range(c(foo$f.sc,foo$f)) if (interactive()) plot(X,foo$f.sc,type="l",ylim=ylim,xlab="X",ylab="Density") lines(X,foo$f,col=2,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ylim <- range(c(foo$f.sc.deriv,foo$f.deriv)) if (interactive()) plot(X,foo$f.sc.deriv,type="l",ylim=ylim,xlab="X",ylab="First Derivative") lines(X,foo$f.deriv,col=2,lty=2) abline(h=0,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ## Example 3: Beta(1,5), DGP is monotone decreasing, impose valid ## restriction X <- sort(rbeta(n,1,5)) h <- npuniden.boundary(X)$h foo <- npuniden.sc(X=X,h=h,constraint=c("mono.decr")) par(mfrow=c(1,2)) ylim <- range(c(foo$f.sc,foo$f)) if (interactive()) plot(X,foo$f.sc,type="l",ylim=ylim,xlab="X",ylab="Density") lines(X,foo$f,col=2,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ylim <- range(c(foo$f.sc.deriv,foo$f.deriv)) if (interactive()) plot(X,foo$f.sc.deriv,type="l",ylim=ylim,xlab="X",ylab="First Derivative") lines(X,foo$f.deriv,col=2,lty=2) abline(h=0,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ## Example 4: N(0,1), DGP is log-concave, impose invalid concavity ## restriction X <- sort(rnorm(n)) h <- npuniden.boundary(X,a=-Inf,b=Inf)$h foo <- npuniden.sc(X=X,h=h,a=-Inf,b=Inf,constraint=c("concave")) par(mfrow=c(1,2)) ylim <- range(c(foo$f.sc,foo$f)) if (interactive()) plot(X,foo$f.sc,type="l",ylim=ylim,xlab="X",ylab="Density") lines(X,foo$f,col=2,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ylim <- range(c(foo$f.sc.deriv,foo$f.deriv)) if (interactive()) plot(X,foo$f.sc.deriv,type="l",ylim=ylim,xlab="X",ylab="Second Derivative") lines(X,foo$f.deriv,col=2,lty=2) abline(h=0,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ## Example 45: Beta(3/4,3/4), DGP is convex, impose valid restriction X <- sort(rbeta(n,3/4,3/4)) h <- npuniden.boundary(X)$h foo <- npuniden.sc(X=X,h=h,constraint=c("convex")) par(mfrow=c(1,2)) ylim <- range(c(foo$f.sc,foo$f)) if (interactive()) plot(X,foo$f.sc,type="l",ylim=ylim,xlab="X",ylab="Density") lines(X,foo$f,col=2,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ylim <- range(c(foo$f.sc.deriv,foo$f.deriv)) if (interactive()) plot(X,foo$f.sc.deriv,type="l",ylim=ylim,xlab="X",ylab="Second Derivative") lines(X,foo$f.deriv,col=2,lty=2) abline(h=0,lty=2) rug(X) legend("topleft",c("Constrained","Unconstrained"),lty=1:2,col=1:2,bty="n") ## Example 6: N(0,1), DGP is log-concave, impose log-concavity ## restriction X <- sort(rnorm(n)) h <- npuniden.boundary(X,a=-Inf,b=Inf)$h foo <- npuniden.sc(X=X,h=h,a=-Inf,b=Inf,constraint=c("log-concave")) par(mfrow=c(1,2)) ylim <- range(c(log(foo$f.sc),log(foo$f))) if (interactive()) plot(X,log(foo$f.sc),type="l",ylim=ylim,xlab="X",ylab="Log-Density") lines(X,log(foo$f),col=2,lty=2) rug(X) legend("topleft",c("Constrained-log","Unconstrained-log"),lty=1:2,col=1:2,bty="n") ylim <- range(c(foo$f.sc.deriv,foo$f.deriv)) if (interactive()) plot(X, foo$f.sc.deriv, type="l", ylim=ylim, xlab="X", ylab="Second Derivative of Log-Density") lines(X,foo$f.deriv,col=2,lty=2) abline(h=0,lty=2) rug(X) legend("topleft",c("Constrained-log","Unconstrained-log"),lty=1:2,col=1:2,bty="n") ## End(Not run)
npunitest implements the consistent metric entropy test of
Maasoumi and Racine (2002) for two arbitrary, stationary
univariate nonparametric densities on common support.
npunitest(data.x = NULL, data.y = NULL, method = c("integration","summation"), bootstrap = TRUE, B = 399, bw.x = NULL, bw.y = NULL, random.seed = 42, ...)npunitest(data.x = NULL, data.y = NULL, method = c("integration","summation"), bootstrap = TRUE, B = 399, bw.x = NULL, bw.y = NULL, random.seed = 42, ...)
These arguments identify the two samples, statistic variant, and any supplied bandwidths.
bw.x, bw.y
|
numeric (scalar) bandwidths. Defaults to plug-in (see details below). |
data.x, data.y
|
common support univariate vectors containing the variables. |
method |
a character string used to specify whether to compute
the integral version or the summation version of the statistic. Can
be set as |
These arguments control bootstrap execution and reproducibility settings.
B |
an integer value specifying the number of bootstrap
replications to use. Defaults to |
bootstrap |
a logical value which specifies whether to conduct the bootstrap
test or not. If set to |
random.seed |
an integer used to seed R's random number generator. This is to ensure replicability. Defaults to 42. |
Further arguments are passed to the bandwidth-selection routines used by the test.
... |
additional arguments supplied to specify the bandwidth
type, kernel types, and so on. This is used since we specify bw as
a numeric scalar and not a |
Documentation guide: see np.kernels for kernels, np.options for global options, and plot for plotting options.
npunitest computes the nonparametric metric entropy (normalized
Hellinger of Granger, Maasoumi and Racine (2004)) for testing
equality of two univariate density/probability functions,
. See Maasoumi and Racine (2002)
for details. Default bandwidths are of the plug-in variety
(bw.SJ for continuous variables and direct plug-in for
discrete variables). The bootstrap is conducted via simple resampling
with replacement from the pooled data.x and data.y
(data.x only for summation).
Missing observations are omitted independently from the two samples before bandwidth selection and overlap checks. Each sample must retain at least one observation; automatic bandwidth selection can require more.
For categorical data, the declared factor levels define the finite domain of the probability comparison, including levels not observed in a sample. The two samples share the union of their declared levels, retained in all bootstrap samples. Plug-in bandwidths use that category count, and the discrete statistic sums over the entire common domain, not only observed categories. Existing kernel normalization is unchanged. Numeric ordered levels retain their numeric scale. Qualitative ordered samples must specify the same level order or an order-consistent subset; otherwise declare a common ordered level set explicitly before calling the test.
The summation version of this statistic can be numerically unstable
when data.x and data.y lack common support or when the
overlap is sparse (the summation version involves division of
densities while the integration version involves differences, and the
statistic in such cases can be reported as exactly 0.5 or 0). Warning
messages are produced when this occurs (‘integration recommended’)
and should be heeded.
For numeric data using the fixed second-order Gaussian density
estimator, the integration
statistic uses deterministic corrected composite trapezoidal
quadrature. The integration domain extends eight bandwidths beyond
the pooled observed support and uses four evaluation points per
smallest bandwidth. During a default numeric iid bootstrap,
resampling counts are evaluated in bounded chunks on the same
quadrature grid for integration or on the original support for
summation. This avoids repeated adaptive integration and
repeated reconstruction of resampled data. The summation density
ratios are evaluated by a registered native routine without forming a
sample-by-sample kernel matrix.
The accelerated route is also used when ... contains only
options explicitly equivalent to the defaults: bwtype="fixed",
ckertype="gaussian", and ckerorder=2. Other density
options retain the corresponding general estimator and numerical
integration route. In particular, generalized and adaptive
nearest-neighbour bandwidths use duplicate-preserving resamples and
recompute their realized neighbour radii; bootstrap counts are not
treated as fixed-bandwidth observation weights.
npunitest returns an object of type unitest with the
following components
Srho |
the statistic |
Srho.bootstrap |
contains the bootstrap replications of |
P |
the P-value of the statistic |
boot.num |
number of bootstrap replications |
bw.x, bw.y
|
scalar bandwidths for |
summary supports object of type unitest.
The bootstrap upper-tail p-value is the proportion of bootstrap statistics greater than or equal to the observed statistic. Ties count as at least as extreme, giving the conservative tie convention for discrete statistics. This is the ordinary bootstrap proportion, without an add-one correction; a reported zero is possible with a finite number of replications.
npunitest uses an entropy-distance measure to compare
univariate density or probability functions. The statistic is based on
the normalized Hellinger-type distance described in the entropy-test
literature referenced below.
For book-length background, see Racine (2019), Chapter 2 Continuous Density and Cumulative Distribution Functions, especially the entropy and density-test material. For related density and testing background, see Li and Racine (2007), Chapters 1, 12, and 13.
See the example below for proper usage.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Granger, C.W. and E. Maasoumi and J.S. Racine (2004), “A dependence metric for possibly nonlinear processes”, Journal of Time Series Analysis, 25, 649-669.
Maasoumi, E. and J.S. Racine (2002), “Entropy and predictability of stock market returns,” Journal of Econometrics, 107, 2, pp 291-312.
np.kernels, np.options, plot
npdeneqtest,npdeptest,npsdeptest,npsymtest
## Not run: set.seed(1234) n <- 1000 ## Compute the statistic only for data drawn from same distribution x <- rnorm(n) y <- rnorm(n) npunitest(x,y,bootstrap=FALSE) if (interactive()) Sys.sleep(5) ## Conduct the test for this data npunitest(x,y,B=99) if (interactive()) Sys.sleep(5) ## Conduct the test for data drawn from different distributions having ## the same mean and variance x <- rchisq(n,df=5) y <- rnorm(n,mean=5,sd=sqrt(10)) mean(x) mean(y) sd(x) sd(y) npunitest(x,y,B=99) if (interactive()) Sys.sleep(5) ## Two sample t-test for equality of means t.test(x,y) ## F test for equality of variances and asymptotic ## critical values Fstat <- var(x)/var(y) qf(c(0.025,0.975),df1=n-1,df2=n-1) ## Plot the nonparametric density estimates on the same axes fx <- density(x) fy <- density(y) xlim <- c(min(fx$x,fy$x),max(fx$x,fy$x)) ylim <- c(min(fx$y,fy$y),max(fx$y,fy$y)) if (interactive()) plot(fx,xlim=xlim,ylim=ylim,xlab="Data",main="f(x), f(y)") lines(fy$x,fy$y,col="red") if (interactive()) Sys.sleep(5) ## Test for equality of log(wage) distributions data(wage1) with(wage1, { lwage.male <- lwage[female=="Male"] lwage.female <- lwage[female=="Female"] npunitest(lwage.male,lwage.female,B=99) if (interactive()) Sys.sleep(5) ## Plot the nonparametric density estimates on the same axes f.m <- density(lwage.male) f.f <- density(lwage.female) xlim <- c(min(f.m$x,f.f$x),max(f.m$x,f.f$x)) ylim <- c(min(f.m$y,f.f$y),max(f.m$y,f.f$y)) plot(f.m,xlim=xlim,ylim=ylim, xlab="log(wage)", main="Male/Female log(wage) Distributions") lines(f.f$x,f.f$y,col="red",lty=2) rug(lwage.male) legend(-1,1.2,c("Male","Female"),lty=c(1,2),col=c("black","red")) }) if (interactive()) Sys.sleep(5) ## Conduct the test for data drawn from different discrete probability ## distributions x <- factor(rbinom(n,2,.5)) y <- factor(rbinom(n,2,.1)) npunitest(x,y,B=99) ## End(Not run)## Not run: set.seed(1234) n <- 1000 ## Compute the statistic only for data drawn from same distribution x <- rnorm(n) y <- rnorm(n) npunitest(x,y,bootstrap=FALSE) if (interactive()) Sys.sleep(5) ## Conduct the test for this data npunitest(x,y,B=99) if (interactive()) Sys.sleep(5) ## Conduct the test for data drawn from different distributions having ## the same mean and variance x <- rchisq(n,df=5) y <- rnorm(n,mean=5,sd=sqrt(10)) mean(x) mean(y) sd(x) sd(y) npunitest(x,y,B=99) if (interactive()) Sys.sleep(5) ## Two sample t-test for equality of means t.test(x,y) ## F test for equality of variances and asymptotic ## critical values Fstat <- var(x)/var(y) qf(c(0.025,0.975),df1=n-1,df2=n-1) ## Plot the nonparametric density estimates on the same axes fx <- density(x) fy <- density(y) xlim <- c(min(fx$x,fy$x),max(fx$x,fy$x)) ylim <- c(min(fx$y,fy$y),max(fx$y,fy$y)) if (interactive()) plot(fx,xlim=xlim,ylim=ylim,xlab="Data",main="f(x), f(y)") lines(fy$x,fy$y,col="red") if (interactive()) Sys.sleep(5) ## Test for equality of log(wage) distributions data(wage1) with(wage1, { lwage.male <- lwage[female=="Male"] lwage.female <- lwage[female=="Female"] npunitest(lwage.male,lwage.female,B=99) if (interactive()) Sys.sleep(5) ## Plot the nonparametric density estimates on the same axes f.m <- density(lwage.male) f.f <- density(lwage.female) xlim <- c(min(f.m$x,f.f$x),max(f.m$x,f.f$x)) ylim <- c(min(f.m$y,f.f$y),max(f.m$y,f.f$y)) plot(f.m,xlim=xlim,ylim=ylim, xlab="log(wage)", main="Male/Female log(wage) Distributions") lines(f.f$x,f.f$y,col="red",lty=2) rug(lwage.male) legend(-1,1.2,c("Male","Female"),lty=c(1,2),col=c("black","red")) }) if (interactive()) Sys.sleep(5) ## Conduct the test for data drawn from different discrete probability ## distributions x <- factor(rbinom(n,2,.5)) y <- factor(rbinom(n,2,.1)) npunitest(x,y,B=99) ## End(Not run)
Cross country GDP growth panel covering the period 1960-1995 used by
Liu and Stengos (2000) and Maasoumi, Racine, and Stengos (2007). There
are 616 observations in total. data("oecdpanel") makes available
the dataset "oecdpanel" plus an additional object "bw".
data("oecdpanel")data("oecdpanel")
A data frame with 7 columns, and 616 rows. This panel covers 7 5-year periods: 1960-1964, 1965-1969, 1970-1974, 1975-1979, 1980-1984, 1985-1989 and 1990-1994.
A separate local-linear rbandwidth object (bw) has
been computed for the user's convenience which can be used to
visualize this dataset using plot(bw).
the first column, of type numeric: growth rate
of real GDP per capita for each 5-year period
the second column, of type factor: equal to
1 for OECD members, 0 otherwise
the third column, of type integer
the fourth column, of type numeric: per capita
real GDP at the beginning of each 5-year period
the fifth column, of type numeric: average
annual population growth rate for each 5-year period
the sixth column, of type numeric: average
investment/GDP ratio for each 5-year period
the seventh column, of type numeric:
average secondary school enrolment rate for each 5-year period
Thanasis Stengos
Liu, Z. and T. Stengos (1999), “Non-linearities in cross country growth regressions: a semiparametric approach,” Journal of Applied Econometrics, 14, 527-538.
Maasoumi, E. and J.S. Racine and T. Stengos (2007), “Growth and convergence: a profile of distribution dynamics and mobility,” Journal of Econometrics, 136, 483-508
data("oecdpanel") with(oecdpanel, { summary(oecdpanel) })data("oecdpanel") with(oecdpanel, { summary(oecdpanel) })
Plotting is provided via plot S3 methods, which generate
plots of
nonparametric statistical objects such as regressions, quantile
regressions, partially linear regressions, single-index models,
densities and distributions, given training data and a bandwidth
object. plot(...) is the supported public interface.
## S3 method for class 'bandwidth' plot(x, ...) ## S3 method for class 'conbandwidth' plot(x, ...) ## S3 method for class 'plbandwidth' plot(x, ...) ## S3 method for class 'rbandwidth' plot(x, ...) ## S3 method for class 'scbandwidth' plot(x, ...) ## S3 method for class 'sibandwidth' plot(x, ...)## S3 method for class 'bandwidth' plot(x, ...) ## S3 method for class 'conbandwidth' plot(x, ...) ## S3 method for class 'plbandwidth' plot(x, ...) ## S3 method for class 'rbandwidth' plot(x, ...) ## S3 method for class 'scbandwidth' plot(x, ...) ## S3 method for class 'sibandwidth' plot(x, ...)
This argument identifies the object to plot.
x |
an object generated by the np package. The most convenient
inputs are fitted estimator objects returned by invocations of
|
...
Named options passed via ... include:
Data and evaluation controls
dataan optional data.frame used to resolve stored
formula calls when explicit training data arguments are not
supplied.
grid.controloptional detailed grid controls created by
np_grid_control.
nevalthe number of evaluation points used for each plotted continuous
margin, defaulting to 50L. Continuous numeric variables use
this grid even when their observed values are integers or have few
distinct values. Categorical margins use their levels. For
npudens/npudist perspective surfaces with numeric
ordered margins, the grid uses the ordered levels observed in the
training data. Their one-dimensional categorical slices use all
declared levels, including unused levels. A surface with two
continuous margins has neval^2 evaluation points.
xdat, ydat, zdat
training data used when plotting bandwidth objects. xdat
is the regressor/conditioning data, ydat is the response
or conditional outcome data, and zdat is the auxiliary
semiparametric covariate block when relevant.
xq, yq, zq
quantiles used to hold non-plotted variables fixed when constructing slices.
xtrim, ytrim, ztrim
trimming/expansion controls for the evaluation support.
Plot content controls
coef, coef.index
coefficient-function plotting controls for semiparametric families where supported.
common.scalea logical value specifying whether multiple panels should share a common plotting scale when feasible.
gradient.order, gradients
derivative plotting controls for families that support
gradients/derivatives. For npreg local-polynomial
objects, gradient.order requests the continuous-predictor
derivative order to generate on the plot evaluation grid; if
omitted the first derivative/effect is plotted. Location-scale
quantile-regression nplsqreg objects use the same
coordinate-wise local-polynomial contract while preserving their
existing tau-indexed output; no mixed partials are generated.
When a requested continuous derivative order exceeds that
coordinate's fitted degree, its values remain NA and its plot
panel remains present but empty if another derivative or categorical
effect is available. Plotting stops with an informative error only
when no requested component is available. Ordered and unordered
categorical panels remain first-order finite differences, denoted by
labels.
For
npconmode objects,
gradients=TRUE plots stored class-probability gradients/effects
for the selected response level, computed by
npconmode(..., gradients=TRUE, level=...).
levelresponse level to plot for class-probability displays when supported,
notably plot.conmode. If omitted, the default for
npconmode objects is the base/reference response level
levels(y)[1]. These plots require probabilities stored by
npconmode(..., probabilities=TRUE). Currently
plot.conmode displays stored object-fed probability/effect
payloads only; probability/effect interval bands and surface grids are
not yet implemented for this route.
layout"auto" or TRUE requests automatic
par(mfrow=...) management for multi-panel plots.
"current" or FALSE preserves the user's current
graphics layout.
outputone of "plot", "data", or "both".
"both" is the public spelling for the historical
"plot-data" behavior.
proper, proper.control, proper.method
controls for proper conditional density/distribution handling where implemented.
tauthe quantile index or indices used for quantile-regression-related
plotting routes when relevant. A vector of tau values overlays
the corresponding conditional quantile curves and reuses the stored
bandwidth object. With errors="asymptotic" or
errors="bootstrap", intervals are constructed separately for
each requested tau; bootstrap work is shared across tau
values within each resample. For npqreg objects whose
conditional-distribution bandwidths were selected with
nomad=TRUE, plotting reuses the stored LP
regtype.engine and selected degree.engine metadata.
Interval and bootstrap controls
alphathe nominal significance level used for interval/band
construction. The default is 0.05, corresponding to a
nominal variability level of .
This nominal level describes the construction; it is not by itself
a claim that smoothing bias is negligible or that the displayed
bounds have literal confidence coverage for the unknown target.
Bthe bootstrap replication count.
bandone of "pmzsd", "pointwise",
"bonferroni", "simultaneous", or "all".
The common bandwidth-engine default is "pmzsd"; direct
npcopula and npconmode plots retain their
method-specific "pointwise" default. The meaning of a band
name depends on whether errors="bootstrap" or
errors="asymptotic"; see Details.
boot.controloptional detailed bootstrap controls created by
np_boot_control. This controls non-fixed bootstrap
behavior, wild-bootstrap multipliers, and dependent-bootstrap
block length.
bootstrapthe bootstrap resampling scheme. Regression-family plots support
"wild", "inid", "fixed", and
"geom"; density/distribution-family plots support
"inid", "fixed", and "geom".
boxplot.outliers, factor.boxplot
boxplot-style bootstrap summary controls for factor/categorical displays when available.
centerone of "estimate" or "bias-corrected". When
bootstrap errors are requested, center="bias-corrected"
centers plotted uncertainty bands or bars on a bootstrap
bias-corrected estimate. The package chooses the validated
correction engine for the requested bootstrap route. Wild
bootstrap regression routes use the standard wild-bootstrap
correction. Pairwise and dependent-bootstrap routes
"inid", "fixed", and "geom" use an
oversmoothed pilot correction for fixed-bandwidth estimators where
that route has been implemented and validated. Unsupported
combinations fail clearly rather than silently using a weak
correction.
For one-dimensional regression curves, the
ordinary estimate remains visible and the selected bias-corrected
estimate is drawn as an additional center line when available.
Fixed-bandwidth regression gradient plots use the same returned
gradient-bias convention described below.
errorsone of "none", "bootstrap", or
"asymptotic". The default is "none".
Bootstrap errors can use either a symmetric normal-quantile rule
based on bootstrap standard deviations or full bootstrap
quantile/rank distributions, according to band.
Asymptotic errors use pointwise standard errors and normal
quantiles where available.
Rendering and view controls
data.overlaylogical; when TRUE, overlay raw data on regression,
quantile-regression, single-index, partially linear, and smooth
coefficient plot surfaces and expand plot limits to include the data. For
npqreg level plots the data layer is drawn first by
default, so quantile curves are overlaid on top; ordered and
factor conditioning variables use the natural boxplot-style
display from plot(). The option is ignored for
derivative/gradient plots and coefficient plots. Overlay points
default to small, light markers and can be customized with
standard points() arguments passed via ... (for
example pch, cex, col, and bg).
Default is TRUE.
legendlegend control for legends drawn by the package, including
vector-tau npqreg level plots and
band="all" uncertainty legends. TRUE draws the
default legend,
FALSE, NULL, or NA suppresses it, a
single character string supplies the legend position, and a
list is merged into the default legend call for
custom labels, placement, or styling. For plot routes with
more than one package-drawn legend, named sublists such as
legend=list(tau=list(x="topright"), bands=FALSE) may
be used when a route distinguishes those legend roles.
data.ruglogical; when TRUE, draw a rug-style support cue for the
plotted coordinates. For ordinary 1D base plots this behaves
like a standard rug. For eligible 2D surface plots, the base
renderer draws short floor-rug ticks and
renderer="rgl" draws the analogous 3D floor-rug ticks
on supported surface routes. In this rollout tranche,
data.rug=TRUE is implemented across the current base
plot families and across supported rgl surface routes;
unsupported renderer/geometry combinations still fail clearly
rather than being ignored silently. On mixed base plot layouts,
rug marks are drawn for continuous panels and omitted for
categorical panels.
This option is distinct from data.overlay:
data.rug shows where observations lie in the plotted
covariate support, while data.overlay is the
regression-only 3D response overlay used on supported surface
plots. On supported regression surfaces, both options may be
used together. Default is FALSE.
perspectivea logical value specifying whether bivariate continuous surfaces
are displayed with persp-style plots when relevant.
phi, theta, view
view controls for bivariate continuous surface plots.
render.controloptional detailed rendering controls created by
np_render_control, including band-versus-bar
uncertainty display controls.
rendererthe surface-rendering backend for eligible bivariate continuous
plots. "base" uses the existing base R
persp path. "rgl" is currently a
fail-closed backend for supported plain 2D surface routes in
npreg/npregbw,
npplreg/npplregbw,
npscoef/npscoefbw,
npudens/npudensbw,
npudist/npudistbw,
npcdens/npcdensbw, and
npcdist/npcdistbw. In this tranche,
renderer="rgl" requires perspective=TRUE,
view="fixed" and output="plot";
unsupported combinations still error rather than falling back
silently. The suggested packages
rgl and htmlwidgets must be installed when
renderer="rgl" is
requested. When drawn, the rgl surface is displayed via
the active rgl backend, which on this rollout path is
typically the RStudio Viewer or a browser/WebGL window rather
than the base graphics plot pane. The base and rgl
renderers share the same viridis palette mapper and neutral-gray
three-face reference-grid default. When col is omitted,
the rgl surface uses a value-based
hcl.colors(..., "viridis") gradient. When the
inherited base-view defaults theta=0 and phi=20
are left unchanged, the rgl backend uses
theta=0, phi=-70, and fov=55 to approximate
the base perspective in the square interactive viewport. The widget
automatically uses up to two backing-store pixels per CSS pixel on
high-DPI displays. Axis titles retain rgl's native screen-facing text
orientation while the scene is rotated. For the currently supported npreg,
npplreg, and plain mean-surface
npscoef surface routes, data.overlay=TRUE
adds observed data as an interactive point cloud. For all
currently supported rgl surface routes,
errors != "none" adds interval surfaces;
band="all" draws pointwise,
simultaneous, and bonferroni band families with distinct,
colorblind-safer colors when those bands are available for the route.
Unsupervised and conditional density/distribution surface
routes do not use observed-data point overlays in this tranche.
For npscoef/npscoefbw, renderer="rgl"
currently applies only to the plain mean-surface route;
coefficient-mode plots remain on the base renderer.
Common
rgl display controls may be supplied
directly in ... on supported routes, including surface
arguments such as alpha, back, and
front, and view arguments such as fov and
zoom. Additional backend-specific arguments may be
passed through using prefixed names in ..., namely
rgl.persp3d.<arg>, rgl.view3d.<arg>,
rgl.par3d.<arg>, rgl.grid3d.<arg>, and
rgl.widget.<arg>, and rgl.legend3d.<arg>. For
the new overlay layers,
rgl.points3d.<arg> customizes observed-point overlays
and rgl.surface3d.<arg> customizes interval surfaces.
When band="all" is used on supported
rgl routes, a matching construction-aware interactive legend
is drawn using the same default labels as the base renderer, and
rgl.legend3d.<arg> may be used to customize it, for
example rgl.legend3d.bty="o" to restore a legend box or
rgl.legend3d.magnify=1 to request the original legend texture
resolution.
By default, these legends follow the base-graphics uncertainty
legend convention and are drawn without a surrounding box.
Graphical parameters
border, cex.axis, cex.lab,
cex.main, cex.sub, col, lty,
lwd, main, sub, type, xlab,
xlim, ylab, ylim, zlab, zlim
standard graphical controls forwarded to the underlying plotting primitives when relevant.
Reproducibility controls
random.seedan optional random seed used to make bootstrap plotting reproducible.
Further plotting controls are passed through ... to the relevant plot method.
... |
additional arguments supplied to control plotting behavior or passed through to underlying plotting helpers where supported. Supported named plotting controls are summarized above; standard graphical parameters are forwarded where relevant. |
Documentation guide: see np.kernels for kernels and
np.options for global options.
The preferred public interface is plot on fitted or
bandwidth objects (e.g., plot(fit) or plot(bw)).
plot is a general purpose plotting routine for visually
exploring objects generated by the np library, such as
regressions, quantile regressions, partially linear regressions,
single-index models, densities and distributions. There is no need to
call plot directly: plotting is handled by class-specific S3
plot methods for objects generated by the np
package.
Visualizing one and two dimensional datasets is a straightforward
process. The default behavior of plot is to generate a
standard 2D plot to visualize univariate data, and a perspective plot
for bivariate data. When visualizing higher dimensional data,
plot resorts to plotting a series of 1D slices of the
data. For a slice along dimension , all other variables at
indices are held constant at the quantiles
specified in the th element of xq. The default is the
median.
The slice itself is evaluated on a uniformly spaced sequence of
points. The interval of evaluation is determined by the
training data. The default behavior is to evaluate from
min(txdat[,i]) to max(txdat[,i]). The xtrim
variable allows for control over this behavior. When xtrim is
set, data is evaluated from the xtrim[i]th quantile of
txdat[,i] to the 1.0-xtrim[i]th quantile of
txdat[,i].
Furthermore, xtrim can be set to a negative
value in which case it will expand the limits of the evaluation
interval beyond the support of the training data, by measuring the
distance between min(txdat[,i]) and the xtrim[i]th
quantile of txdat[,i], and extending the support by that
distance on the lower limit of the interval. plot uses an
analogous procedure to extend the upper limit of the interval.
Numeric estimator output follows R's extended-real conventions:
mathematically defined one-sided limits are retained as -Inf or
Inf, while unavailable or indeterminate values are returned as
NA_real_. Plotting does not rewrite the estimator object or values
returned with output="data". Instead, a temporary graphics-only copy
maps every non-finite coordinate to missing geometry. Consequently lines
break at an infinite or unavailable point, interval segments at that point
are omitted, and axis limits are computed from finite values. If a panel has
no finite geometry, a finite fallback scale is used unless the user supplies
ylim. This allows exact beta endpoint derivatives and other
extended-real estimates to retain their mathematical meaning without
passing invalid coordinates or limits to a graphics backend.
Plot variability-band constructions are:
errors band construction bootstrap pmzsd center +/- z_(1-alpha/2) * bootstrap SD bootstrap pointwise pointwise bootstrap quantiles bootstrap bonferroni Bonferroni-adjusted bootstrap quantiles bootstrap simultaneous rank-based joint bootstrap band bootstrap all all three bootstrap quantile/rank families asymptotic pmzsd/pointwise center +/- z_(1-alpha/2) * asymptotic SE asymptotic bonferroni normal rule with alpha replaced by alpha/m asymptotic simultaneous finite-grid Gaussian rule for supported targets asymptotic all marginal families plus Gaussian where supported
where is the number of evaluation points used in the plotted
curve/surface ( for univariate curves,
typically for full 2D perspective
surfaces).
Thus errors="bootstrap", band="pmzsd" summarizes each
bootstrap distribution by its standard deviation and imposes a symmetric
normal-quantile shape on the displayed band. In contrast, bootstrap
"pointwise" and "bonferroni" bands use the corresponding
lower and upper empirical bootstrap quantiles separately and may be
asymmetric at each evaluation point. Bootstrap "simultaneous"
uses a joint rank construction rather than either pointwise standard
deviations or pointwise tail quantiles. With band="all", these
distinct bootstrap families are displayed together where supported.
For asymptotic errors, "pmzsd" and "pointwise" are two
names for the same symmetric normal construction. Let denote
the plotted functional (mean, gradient, density, distribution, etc.) and
its asymptotic standard error. Both use
.
"bonferroni" applies the same rule with in place
of .
Regression, single-index and smooth-coefficient mean and gradient curves support asymptotic Gaussian simultaneous variability
bands within each panel's finite evaluation grid. This supports fixed, generalized nearest-neighbor and adaptive nearest-neighbor
bandwidths with second-order Gaussian or Epanechnikov kernels and the
existing LC, LL or LP specification. Numeric, unordered-factor and
ordered-factor panels are supported, including mixed-data models and
all-categorical smoothing under its existing local-constant specification.
When there are no continuous smoothing variables, continuous-kernel settings
do not restrict joint calibration. Regression, partially linear and smooth-coefficient mean surfaces support
the same bands with both perspective and renderer="rgl" rendering.
Gradients retain their slice plots; single-index plots retain their existing
scalar-index geometry. Other continuous kernels retain a warning and
unavailable simultaneous limits. With band="all", supported curves retain the pointwise and
Bonferroni families and add the Gaussian simultaneous family.
For partially linear plots, a material influence reconstruction discrepancy (more than 1% of a standard error, with a roundoff allowance) signals numerical instability in the plotted fit. A warning identifies the affected points. Pointwise and Bonferroni limits are NA only at those points, and simultaneous limits are NA for the entire affected panel. The fitted curve is preserved; other panels retain their available bands.
Density and distribution plots (npudens, npudist,
npcdens and npcdist) also support Gaussian simultaneous
variability bands for ordinary panels and complete perspective/rgl level
grids. Supported specifications include fixed, generalized nearest-neighbor
and adaptive nearest-neighbor bandwidths with second-order Gaussian or
Epanechnikov kernels. Conditional LC, LL and LP fits retain their selected
degree and basis. Available conditional continuous derivatives and categorical
first differences are supported in slice plots; higher generalized-NN
derivatives retain their existing restrictions. Unconditional adaptive-NN
uniform kernels are supported on regular spacing and support-face domains.
Fixed continuous conditional LC specifications also support beta kernels.
Proper-projected density/CDF plots and other continuous kernel
specifications retain their documented simultaneous-band restrictions.
Conditional quantile plots have a separate finite-grid influence
construction; see npqreg for its supported level and
gradient targets and conditioning assumptions.
These density-family bands use the incumbent marginal standard errors and
the correlation of centered observation-level empirical influence rows.
Writing for the diagonal matrix of those standard errors and
for that correlation, the working covariance is .
The conditional ratio includes numerator-denominator dependence; LP uses
the accepted local solve, including smooth ridge-scale and intercept
compensation terms. Categorical contrasts subtract endpoint influence rows
before computing covariance. Conditional NN geometry is held fixed, and
unconditional generalized-NN uses its frozen-query-radius approximation;
unconditional adaptive-NN includes the same-sample random-radius contribution.
All three band families share the same marginal scale. Simultaneity is within
the complete displayed panel/grid, not across separate panels.
The Gaussian-multiplier calibration is based on the framework developed by Victor Chernozhukov, Denis Chetverikov and Kengo Kato (2013, 2015). Related Gaussian-process and simultaneous-inference results for local regression distribution estimators are due to Matias D. Cattaneo, Michael Jansson and Xinwei Ma (2024); for local polynomial conditional density estimators, see Matias D. Cattaneo, Rajita Chandak, Michael Jansson and Xinwei Ma (2024). These works provide the related methodological foundation; the implementations here retain this package's kernel estimators, marginal standard errors and density-specific influence contracts described above. They do not implement the distinct estimators or robust bias-correction procedures in those papers. This is finite-grid variability conditional on the selected model and smoothing specification, not bias correction, bandwidth-search uncertainty or honest continuous-domain confidence coverage. Gaussian approximation can be poor with small nearest-neighbor neighborhoods or sparse evaluation points, including grids extending to sample extremes. Increasing the number of Gaussian draws reduces simulation error but does not correct these limitations. Nonregular ANN geometry, unavailable marginal uncertainty and resource limits produce a warning and NA simultaneous limits, preserving other available bands. Unexpected calculation errors and material target reconstruction failures remain errors.
The separately named plot argument gaussian.draws has a fixed default
of 9999 and accepts positive integer counts subject to representability and
workspace limits, without a fixed one-million upper cap. It applies only to asymptotic
simultaneous/all requests; B remains bootstrap-only. The usual
random.seed (default 42) controls calibration without changing the
caller's random-number state. A count below
ceiling(qnorm(.975)^2 * (1-alpha) / (.1^2 * alpha)) warns and is used
unchanged. This is an approximate 95 percent Monte Carlo target for relative
error within 10 percent in the simulated maximum's upper-tail probability.
It is about 7299 draws at alpha=0.05 and 38031 at alpha=0.01.
The maximum's tail probability is for either a slice or a full
neval^2 perspective/rgl grid; the number of points affects the maximum
distribution and computational cost, but does not divide this tail probability.
This recommendation does not guarantee critical-value accuracy or statistical
coverage and is not a draw-count prescription in Chernozhukov, Chetverikov and
Kato (2013). Explicit counts are never increased silently.
Simulation uses bounded blocks and the bootstrap progress mechanism to
report completed draws, elapsed time and estimated time remaining during
interactive computation. It uses a conservative 64 MiB workspace budget;
reduce neval or gaussian.draws if the workspace is too large.
Regression, single-index and smooth-coefficient slice covariance calibration
is limited to 512 grid points. Density-family plots switch to an
observation-level factor above 512 points and budget up to 128 MiB for
influence construction. This admission accounts for training size as well as
grid size and LP workspaces: with the default 50 by 50 density-family surface,
the factor/calibration allowance alone limits admission to about 1677 training
observations; additional workspaces can lower that limit. Reducing
neval reduces the surface grid quadratically. An over-budget request
warns and retains the available marginal bands with NA simultaneous limits.
Surfaces and partially linear plots instead
use observation-level influence factors, avoiding a grid-by-grid covariance
matrix and that grid-size limit.
Write for the training smoother and for its evaluation
influence map. The covariance is
, where
.
For regression derivatives, replace by the corresponding derivative
influence map; the training smoother and normalized residuals remain those
of the fitted mean. Available higher-order continuous partials use the
existing gradient.order contract. For categorical regression
gradients, use the difference of the two endpoint influence rows. Unordered
factors compare each level with the first retained level; ordered factors
use adjacent-level differences, with the first forward difference repeated
at the first level. This retains the covariance between endpoints, gives
zero width for an unordered reference contrast, and calibrates jointly over
all displayed levels. Simultaneity remains within each panel, not across
separate panels.
A simulated maximum of the absolute standardized joint Gaussian coordinates
supplies one multiplier for the existing standard errors. Its simulated
critical value is bounded by the analytical pointwise and Bonferroni critical
values, ensuring that these three band widths remain ordered despite Monte
Carlo variation. The raw simulated critical value is retained as
critical.raw in the calibration metadata for nonzero-variance panels.
For regression, single-index and smooth-coefficient plots, if the joint
calculation cannot reproduce the plotted target or standard errors, has
unidentified residual information, or exceeds its workspace/grid budget,
the plot warns and returns unavailable (NA) simultaneous limits.
With band="all", pointwise and Bonferroni intervals are retained.
This can occur in sparse, locally ridged tails even after bandwidth selection.
Invalid arguments, invalid covariance objects and unexpected computation
errors still fail explicitly.
This Gaussian/multiplier connection follows the framework developed by Victor Chernozhukov, Denis Chetverikov and Kengo Kato (2013); see also their Gaussian comparison and anti-concentration results (2015). Conditional on the data and the fitted smoothing specification, simulating this covariance has the same Gaussian law as applying independent standard normal multipliers to the observation-level influence contributions. The covariance is assembled once per panel, so calibration requires no repeated estimator fits. These references concern the Gaussian approximation and multiplier framework; the covariance above retains this package's estimator-specific standard-error convention and does not by itself establish bias correction or honest confidence coverage.
Density-family output objects retain band.calibration and, for
band="all", band.errors. With conditional gradients these
are lists indexed by the explanatory-variable component. Calibration records
the draw count, grid size, critical value and working dependence contract.
Single-index bands additionally condition on the fitted index coefficients;
gradient panels multiply the scalar-index derivative by the corresponding
fitted index coefficient and its widths by that coefficient's absolute value;
negative coefficients exchange lower and upper widths for asymmetric
bootstrap intervals before scaling.
They retain the scalar-index regression standard-error convention. Smooth-coefficient bands describe the
noniterated plotted mean or existing slope-coefficient gradient selected by
coef.index, and use fitted raw training residuals in place
of the normalized residuals above. These gradients hold the smoothing
coordinates fixed, including when explanatory and smoothing variables
overlap; they are not total derivatives through those coordinates.
The separate coef=TRUE display remains excluded. A joint
request reports unavailable simultaneous limits if its influence map cannot
reproduce the incumbent plotted target and standard errors, including
incompatible locally deficient solve configurations. These three families
retain their existing pointwise intervals.
Partially linear mean plots use the complete response map of the fitted
estimator, including coefficient estimation. Write and
, with each column using its own nuisance smoother, and
let . The evaluation map is ; the training
map is . The plot covariance is
, using the complete training
map in the normalized-residual formula above. Thus the shared-observation
cross-covariances are retained. This corrects the previous partially linear
plot helper, which added component variances separately; its pointwise and
Bonferroni plot widths consequently change as well. Coefficient estimates
and their reported covariance are unchanged. With raw residuals in place of
normalized residuals, this response map gives exactly the conditional
covariance of independent fixed-design wild-bootstrap multipliers.
Partially linear curves and surfaces use influence-factor calibration.
Their nuisance influence projections reuse the scalar fit's accepted local
factorization or global inverse; the fitted estimator and its ridge policy
are unchanged. Reconstruction differences below one percent of a plotted
standard error are treated as negligible on the interval scale. Material
discrepancies raise an error.
Nearest-neighbor radii are held at the fitted design for this conditional asymptotic calculation. Training residuals retain the estimator's training evaluation convention, which can differ from explicit evaluation at the same coordinates. A blocked response-map calculation preserves that distinction without retaining a full training smoother. This can add computation for NN and partially linear asymptotic bands; it does not repeat bandwidth selection or propagate its sampling variability.
Bandwidths and the polynomial specification are held fixed. This construction
neither corrects smoothing bias nor guarantees finite-sample confidence
coverage. It does not cover points between the grid or jointly cover different
panels. Returned data include compact band.calibration metadata;
band="all" also returns the three width matrices in band.errors.
Surface widths follow the flattened evaluation-grid order. For a single-index
gradient object, each width family is an evaluation-point by bound by
coefficient array, aligned with the returned gradient columns. Factor-based
calibration reports rank=NA because no eigendecomposition is
computed.
On an eligible single-panel plot rendered by base graphics,
a missing sub argument allows the plot method to add a concise
variability subtitle after finite bounds have actually been drawn. This
includes individual figures in a sequence with
options(plot.par.mfrow=FALSE) when the active graphics layout is
a full-frame single panel. Levels and supported gradients/effects follow
the same rule. Categorical interval bars use interval rather than band
terminology.
The wording distinguishes symmetric -times-standard-error
bands from bootstrap quantile and rank constructions. For example, at
the default alpha=0.05, labels include
"95% symmetric variability band (normal quantile × asymptotic SE)"
and
"95% pointwise bootstrap variability band (quantiles)".
Bias-corrected bootstrap labels also identify their center.
The automatic subtitle uses the effective subtitle typography (including
cex.sub) and only appears when an approved one-line wording fits
the existing plot width and bottom-margin clearance. It does not enlarge
margins or reduce the plotting region; when no wording fits, it is
silently omitted. Supplying sub, including sub="" or
sub=NULL, suppresses
the automatic label without changing that route's existing handling of the
supplied subtitle.
Package-managed multi-panel base figures instead receive one shared
annotation at the top of each page, using existing whitespace without
changing margins, panel sizes, or fonts. Simultaneous and Bonferroni wording
identifies the within-panel scope; for multiple quantile curves, the scope
is within each quantile curve, not joint across quantiles. An annotation
is omitted if its text does not fit or clearance from a main title cannot
be established. Caller-managed multi-panel layouts and partial figure
regions are not labelled with a figure-wide annotation. Bootstrap boxplots
and coefficient displays of plus/minus one standard error are not labelled
as nominal variability intervals. The global plot.par.mfrow option
also governs automatic layout for class-probability plots.
On these eligible base plots, with band="all", default legend
labels also identify the
construction, for example "Pointwise (quantiles)" and
"Simultaneous (rank-based)" for bootstrap bands, or
"Pointwise (z × SE)" and
"Bonferroni (adjusted z × SE)" for asymptotic bands. A default
legend omits any family for which no finite band was drawn. Explicit
user-supplied legend labels are preserved without relabelling or
filtering.
These automatic annotations apply to the base renderer. The
"rgl" renderer uses the same construction-aware default labels in
its existing band="all" legend, but retains its sparse interactive
presentation: it adds no automatic footer or subtitle, and panning, zooming,
responsive sizing, and widget geometry are unchanged.
When center="bias-corrected" and output="data" (or
output="both") is requested, returned
plot objects that support bootstrap bias correction include bias and
bias.corrected components where available. The sign convention
is bias = estimate - bias.corrected, so the corrected estimate
can be recovered as estimate - bias. For example, regression
plot objects use mean - bias; density objects use
dens - bias; and distribution objects use dist - bias.
Regression-gradient plot objects use the analogous convention
gbias = grad - gradient.bias.corrected, so the corrected
gradient can be recovered as grad - gbias.
Two-dimensional plots do not draw a second corrected surface in this
tranche; use output="data" to recover the corrected surface
values.
Kernel estimators are generally biased because smoothing trades variance reduction for bias. For this reason, pointwise and simultaneous error bounds centered on the fitted kernel estimate are often best interpreted as variability bounds rather than literal confidence intervals for the unknown target function. Confidence-interval interpretation requires the smoothing bias to be negligible relative to sampling variability, or to be corrected with sufficient accuracy.
When bootstrap errors are requested, center="bias-corrected"
recenters the plotted bootstrap bounds on a method-specific
Efron-Tibshirani bootstrap bias-corrected estimate, where available.
This produces bounds that are closer in spirit to confidence intervals
than variability bounds centered on the original biased estimate. Bias
correction for nonparametric estimators is difficult, however, and no
universal correction is optimal across estimators, bandwidths,
supports, and data types.
For wild-bootstrap regression routes, center="bias-corrected"
uses the standard wild-bootstrap correction, without a second
oversmoothed pilot bandwidth. This follows the wild-bootstrap
regression literature and the package's finite-sample evidence that
an additional pilot can underadjust in this route. For supported
fixed-bandwidth regression-style routes with bootstrap="inid",
"fixed", or "geom", center="bias-corrected"
estimates the bias center from a second pilot bootstrap matrix while
retaining the ordinary bootstrap matrix for variability widths. These
combinations can behave differently in finite samples, so the returned
bias and bias.corrected components should be inspected
when bias correction is scientifically important. For supported fixed
regression gradient plots, inspect gbias,
gradient.bias.corrected, or route-specific gradient-bias
components such as gc1bias; different bootstrap schemes can
give materially different derivative-bias corrections.
The pilot rule is family-specific. For fixed-bandwidth regression plots, the non-wild pilot uses the full oversmoothing-rate rule:
where is the selected bandwidth, is the continuous
kernel order, and is the number of continuous smoothing
variables in that regression route. For ordinary second-order
kernels with one continuous smoothing variable this reduces to
. Categorical variables do not enter this
continuous-rate exponent. Supported semiparametric regression and
single-index plot routes use the square-root version of this rule.
For unconditional density and distribution plots with continuous
variables, including mixed-data routes supported by the estimator, the
smooth-bootstrap perturbation rule uses , following the
density smooth-bootstrap literature. Continuous variables are
perturbed and categorical variables are resampled row-wise without
perturbation. The smooth perturbation law is drawn from the selected
ordinary continuous kernel when that kernel defines a probability law:
second-order Gaussian, uniform, and second-order Epanechnikov kernels
are supported. Epanechnikov perturbations use the package's standardized
support before multiplication by the pilot
bandwidth. Higher-order Gaussian and Epanechnikov kernels remain
valid estimation kernels, but their signed equivalent-kernel forms do
not define ordinary random perturbations, so
center="bias-corrected" with pair/block/geometric bootstrap
fails clearly for those higher-order smooth-bootstrap perturbation
routes. For conditional density/distribution plots, the
continuous dependent-variable side uses the same density-style rule
; categorical dependent variables are resampled row-wise
without perturbation. The conditioning-variable side uses a full
regression-style pilot: continuous conditioning bandwidths are
enlarged, and categorical conditioning lambdas are moved toward their
admissible upper bounds without crossing them. Categorical conditioning
values are drawn independently given the selected donor, using the selected
categorical kernel normalized over the declared possible levels for that
donor. Factor levels and their ordering are retained. For
conditional density this is
and for conditional distribution this is
where here is the total number of continuous dependent and
explanatory variables. The same conditional pilot rule is used for
supported fixed-bandwidth conditional density/distribution gradient
plots, including mixed-data routes. In mixed-data conditional
gradients, continuous dependent variables are perturbed by the
density-style rule, categorical dependent variables are resampled
row-wise without perturbation, continuous conditioning variables use
the conditional regression-style pilot, and categorical conditioning
lambdas are moved toward their admissible upper bounds as in the
corresponding level route and actually used in the categorical draws.
The conditional pilot uses donor-truncated continuous probability laws
when finite domain bounds are supplied, with the same normalization in
its reference calculation.
Each conditional pilot resample is refitted at the original estimation bandwidths and the selected LC/LL/LP specification. The bias estimate subtracts the known conditional target of the generating pilot law from the mean pilot-bootstrap estimate, not the original fitted estimate. Conditional PDF/CDF levels, continuous derivatives and categorical first differences use this same reference contract; the endpoints of a categorical contrast share each resampled dataset. Ordinary bootstrap draws still determine variability widths. A pilot reference without support, or a derivative at a nonsmooth compact-kernel knot, fails explicitly rather than silently changing the requested centering method. These are practical, evidence-backed rules-of-thumb guided by the smoothed-bootstrap and regression two-bandwidth literatures, not claims of universal optimality.
In practice, users who want confidence-style bounds should prefer
bootstrap errors with center="bias-corrected". The
ordinary fitted curve or surface remains the default estimate because
bias correction can increase variance and may have larger mean squared
error than the uncorrected estimator.
Asymptotic standard errors are taken from fitted-object components such as
merr, gerr, derr, conderr, and
congerr where implemented. Ordinary regression, single-index
mean/gradient and transformed-response least-squares quantile errors
inherit the residual normalization described in npreg.
This does not replace other families' covariance formulas.
Bootstrap resampling is conducted pairwise on (i.e., by
resampling rows of or as appropriate).
Bootstrap method support differs by estimator family:
Regression-family (npreg/npindex/npscoef/npplreg): wild, inid, fixed, geom Density/distribution-family (npudens/npudist/npcdens/npcdist/npconmode): inid, fixed, geom
hence "wild" is only available for regression-family plotting.
Bias-corrected bootstrap centering is currently restricted to supported
fixed-bandwidth plot routes. Non-fixed, adaptive-nearest-neighbor, and
generalized-nearest-neighbor bandwidth routes fail closed for
center="bias-corrected". Conditional quantile
npqreg bootstrap plots currently require center="estimate";
center="bias-corrected" fails clearly for this route. Copula
npcopula and instrumental-variable npregiv
bias-corrected bootstrap plot routes are not claimed in this release
tranche and fail clearly when unsupported bias-corrected bootstrap
controls are requested. Partially linear
npplreg level plots support the regression-family bootstrap
methods above; gradients=TRUE is not a partially linear plot
route and fails clearly.
Implementation notes for speed:
wild : fast np*hat linear-operator bootstrap path inid/fixed/geom : fast direct helper path (no internal bandwidth search)
For non-fixed density/distribution bootstrap, an explicit experimental
approximation is available via
boot.control = np_boot_control(nonfixed = "exact") or
boot.control = np_boot_control(nonfixed = "frozen"). The default
"exact" route recomputes the non-fixed geometry for each resample.
The experimental "frozen" route reuses the original-sample
non-fixed geometry throughout the bootstrap run. This option is currently
implemented only for unconditional and conditional density/distribution
bootstrap routes and remains off by default. For generalized/adaptive
nearest-neighbor runs, "frozen" is an approximation that can alter
interval/band width by holding the original-sample nearest-neighbor
geometry fixed across bootstrap resamples; "exact" remains the
recommended setting for production inference. This approximation can be
more noticeable for conditional density/distribution plotting than for the
regression-style plot families because the conditional bootstrap paths
freeze both numerator and denominator nearest-neighbor geometry before
recombining them. In practice, conditional distribution bands are often
closer, while conditional density bands can differ more materially from
"exact" under generalized/adaptive nearest-neighbor bandwidths.
For smooth coefficient plots (npscoef) under non-fixed bandwidths,
"exact" can also be much more expensive than "frozen" on
large jobs, because the coefficient field must be recomputed for each
bootstrap resample rather than reusing the original-sample geometry. This
recomputation cannot in general be avoided without a more aggressive
approximation: for npscoef the local weighted systems that define the
coefficient vector depend on the bootstrap resample weights/counts at each
evaluation point, so unlike npplreg there is no single global
coefficient vector that can be updated once per draw.
inid admits general heteroskedasticity of unknown form, though
it does not allow for dependence. fixed conducts Kunsch's (1988)
block bootstrap for dependent data, while geom conducts Politis
and Romano's (1994) stationary bootstrap.
For local polynomial conditional density/distribution plotting
(npcdens/npcdist with regtype="ll" or
regtype="lp") and proper=TRUE, the plotted estimate is
rendered proper slice-by-slice on the fixed evaluation grid: each
conditional density slice is projected to be nonnegative and to integrate
to one using trapezoidal quadrature weights from the evaluation
-grid, while each conditional distribution slice is projected to
be monotone and bounded in . When
errors="bootstrap", the bootstrap resample surfaces
are computed first on that same fixed grid and then properized
resample-by-resample using the same grid geometry before
"pointwise", "bonferroni", "simultaneous", and
"all" bands are constructed. Thus the bootstrap distribution used
to form these bands is built from properized resample surfaces. The final
lower/upper band surfaces are interval envelopes and are not themselves
separately re-projected to satisfy the density/distribution shape
constraints.
For consistency of the block and stationary bootstrap, the (mean)
block length should grow with the sample size at an
appropriate rate. If is not given, then a default growth rate
of is used. This rate is
“optimal” under certain conditions (see Politis and Romano
(1994) for more details). However, in general the growth rate depends on
the specific properties of the DGP. A default value for
() has been determined by a Monte Carlo simulation using a
Gaussian AR(1) process (AR(1)-parameter of 0.5, 500
observations). has been chosen such that the mean square
error for the bootstrap estimate of the variance of the empirical mean
is minimized.
The default bootstrap replication count is B=9999, including
copula plots. Class-probability plots retain their default B=399.
Estimator and test bootstrap defaults are separate. For pointwise percentile intervals the bare
tail-resolution reference is
.
For "bonferroni", "simultaneous", and "all", the warning
uses ,
where is the actual within-panel evaluation count, including
on a full perspective grid. For rank-based
simultaneous intervals this is a conservative Bonferroni reference.
These are bare rank-scale floors, not integrality requirements, Monte Carlo
precision targets or coverage guarantees. Meeting a floor may still leave
noisy endpoints; larger B can stabilize them. At alpha=0.05,
a 50-point curve has a floor of 1999, while a 50 by 50 surface has a floor of
99999. Below the floor the plot warns and uses the requested count unchanged.
Bootstrap standard-deviation bands ("pmzsd") do not estimate empirical
tail quantiles and are not subject to this tail-resolution warning.
Typical plotting calls:
## Asymptotic pointwise/bonferroni intervals plot(fit, errors="asymptotic", band="pointwise") plot(fit, errors="asymptotic", band="bonferroni") ## Regression-family bootstrap (wild available) plot(fit, errors="bootstrap", bootstrap="wild") ## Density/distribution-family bootstrap (use inid/fixed/geom) plot(fit, errors="bootstrap", bootstrap="inid")
Compound public plot argument names use dots, consistent with the package
interface. Retired underscore spellings are not accepted. Use errors,
bootstrap, B, band, alpha, center,
output, data.overlay, data.rug, layout, and the
control constructors documented in np_boot_control,
np_grid_control, and np_render_control.
Setting output will instruct plot what data
to return. Option summary:plot: instruct plot to just plot the data and
return NULL both: instruct plot to plot the data and return
the data used to generate the plots. The data will be a list of
objects of the appropriate type, with one object per plot. For
example, invoking plot on 3D density data will have it
return a list of three npdensity objects. If biases were calculated,
they are stored in a component named biasdata: instruct plot to generate data only and no plots
If you are using data of mixed types, then it is advisable to use the
data.frame function to construct your input data and not
cbind, since cbind will typically not work as
intended on mixed data types and will coerce the data to the same
type.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
Aitchison, J. and C.G.G. Aitken (1976), “Multivariate binary discrimination by the kernel method,” Biometrika, 63, 413-420.
Cao-Abad, R. (1991), “Rate of convergence for the wild bootstrap in nonparametric regression,” The Annals of Statistics, 19, 2226-2231.
Cattaneo, Matias D., Rajita Chandak, Michael Jansson and Xinwei Ma (2024), “Boundary adaptive local polynomial conditional density estimators,” Bernoulli, 30(4), 3193-3223. doi:10.3150/23-BEJ1711.
Cattaneo, Matias D., Michael Jansson and Xinwei Ma (2024), “Local regression distribution estimators,” Journal of Econometrics, 240(2), 105074. doi:10.1016/j.jeconom.2021.01.006.
Chernozhukov, Victor, Denis Chetverikov and Kengo Kato (2013), “Gaussian approximations and multiplier bootstrap for maxima of sums of high-dimensional random vectors,” The Annals of Statistics, 41(6), 2786-2819. doi:10.1214/13-AOS1161.
Chernozhukov, Victor, Denis Chetverikov and Kengo Kato (2015), “Comparison and anti-concentration bounds for maxima of Gaussian random vectors,” Probability Theory and Related Fields, 162, 47-70. doi:10.1007/s00440-014-0565-9.
Hall, P. and J.S. Racine and Q. Li (2004), “Cross-validation and the estimation of conditional probability densities,” Journal of the American Statistical Association, 99, 1015-1026.
Hall, P. (1992a), “Effect of bias estimation on coverage accuracy of bootstrap confidence intervals for a probability density,” The Annals of Statistics, 20, 675-694.
Hall, P. (1992b), “On bootstrap confidence intervals in nonparametric regression,” The Annals of Statistics, 20, 695-711.
Hardle, W. and J.S. Marron (1991), “Bootstrap simultaneous error bars for nonparametric regression,” The Annals of Statistics, 19, 778-796.
Kunsch, H.R. (1989), “The jackknife and the bootstrap for general stationary observations,” The Annals of Statistics, 17, 1217-1241.
Li, Q. and J.S. Racine (2007), Nonparametric Econometrics: Theory and Practice, Princeton University Press.
Pagan, A. and A. Ullah (1999), Nonparametric Econometrics, Cambridge University Press.
Politis, D.N. and J.P. Romano (1994), “The stationary bootstrap,” Journal of the American Statistical Association, 89, 1303-1313.
Silverman, B.W. and G.A. Young (1987), “The bootstrap: to smooth or not to smooth?” Biometrika, 74, 469-479.
De Angelis, D. and G.A. Young (1992), “Smoothing the bootstrap,” International Statistical Review, 60, 45-56.
Scott, D.W. (1992), Multivariate Density Estimation. Theory, Practice and Visualization, New York: Wiley.
Silverman, B.W. (1986), Density Estimation, London: Chapman and Hall.
Wang, M.C. and J. van Ryzin (1981), “A class of smooth estimators for discrete distributions,” Biometrika, 68, 301-309.
np.kernels, np.options
np.options
## Not run: # EXAMPLE 1: For this example, we load Giovanni Baiocchi's Italian GDP # panel (see Italy for details), then create a data frame in which year # is an ordered factor, GDP is continuous, compute bandwidths using # likelihood cross-validation, then create a grid of data on which the # density will be evaluated for plotting purposes data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # Compute bandwidths using likelihood cross-validation (default). Note # that this may take a minute or two depending on the speed of your # computer... bw <- npudensbw(dat=data) fit <- npudens(tdat=data, bws=bw) # You can always do things manually, as the following example demonstrates # Create an evaluation data matrix year.seq <- sort(unique(year)) gdp.seq <- seq(1,36,length=50) data.eval <- expand.grid(year=year.seq,gdp=gdp.seq) # Generate the estimated density computed for the evaluation data fhat <- fitted(npudens(tdat = data, edat = data.eval, bws=bw)) # Coerce the data into a matrix for plotting with persp() f <- matrix(fhat, length(unique(year)), 50) # Next, create a 3D perspective plot of the PDF f persp(as.integer(levels(year.seq)), gdp.seq, f, col="lightblue", ticktype="detailed", ylab="GDP", xlab="Year", zlab="Density", theta=300, phi=50) # Sleep for 5 seconds so that we can examine the output... Sys.sleep(5) # However, plot simply streamlines this process and aids in the # visualization process (<ctrl>-C will interrupt on *NIX systems, <esc> # will interrupt on MS Windows systems). plot(fit) # plot also streamlines construction of variability bounds (<ctrl>-C # will interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems) plot(fit, errors = "asymptotic") # EXAMPLE 2: For this example, we simulate multivariate data, and plot the # partial regression surfaces for a locally linear estimator and its # derivatives. set.seed(123) n <- 100 x1 <- runif(n) x2 <- runif(n) x3 <- runif(n) x4 <- rbinom(n, 2, .3) y <- 1 + x1 + x2 + x3 + x4 + rnorm(n) X <- data.frame(x1, x2, x3, ordered(x4)) bw <- npregbw(xdat=X, ydat=y, regtype="ll", bwmethod="cv.aic") fit <- npreg(bws=bw) plot(fit) # Sleep for 5 seconds so that we can examine the output... Sys.sleep(5) # Now plot the gradients... plot(fit, gradients=TRUE) # Plot the partial regression surfaces with bias-corrected bootstrapped # nonparametric confidence intervals... this may take a minute or two # depending on the speed of your computer as the bootstrapping must be # completed prior to results being displayed... plot(fit, errors="bootstrap", center="bias-corrected", band="simultaneous") # EXAMPLE 3: This example demonstrates how to retrieve plotting data from # plot(). When plot() is called with the arguments # `output="both"' (or "data"), it returns plotting objects # named r1, r2, and so on (rg1, rg2, and so on when `gradients=TRUE' is # set). Each plotting object's index (1,2,...) corresponds to the index # of the explanatory data data frame xdat (and zdat if appropriate). # Take the cps71 data by way of example. In this case, there is only one # object returned by default, `r1', since xdat is univariate. data("cps71", package = "np") # Compute bandwidths for local linear regression using cv.aic... bw <- npregbw(xdat=cps71$age, ydat=cps71$logwage, regtype="ll", bwmethod="cv.aic") fit <- npreg(bws=bw) # Generate the plot and return plotting data, and store output in # `plot.out' (NOTE: the call to `output' is necessary). plot.out <- plot(fit, perspective=FALSE, errors="bootstrap", B=25, output="both") # Now grab the r1 object that plot plotted on the screen, and take # what you need. First, take the output, lower error bound and upper # error bound... logwage.eval <- fitted(plot.out$r1) logwage.se <- se(plot.out$r1) logwage.lower.ci <- logwage.eval + logwage.se[,1] logwage.upper.ci <- logwage.eval + logwage.se[,2] # Next grab the x data evaluation data. xdat is a data.frame(), so we # need to coerce it into a vector (take the `first column' of data frame # even though there is only one column) age.eval <- plot.out$r1$eval[,1] # Now we could plot this if we wished, or direct it to whatever end use # we envisioned. We plot the results using R's plot() routines... with(cps71, plot(age, logwage, cex=0.2, xlab="Age", ylab="log(Wage)")) lines(age.eval,logwage.eval) lines(age.eval,logwage.lower.ci,lty=3) lines(age.eval,logwage.upper.ci,lty=3) # Bias-corrected bootstrap output includes the estimated bias and the # bias-corrected center when available. The sign convention is # bias = estimate - bias.corrected, so bias.corrected = estimate - bias. plot.out <- plot(fit, perspective=FALSE, errors="bootstrap", center="bias-corrected", B=25, output="data") logwage.eval <- fitted(plot.out$r1) logwage.bias <- plot.out$r1$bias logwage.bc <- plot.out$r1$bias.corrected stopifnot(all.equal(logwage.bc, logwage.eval - logwage.bias)) # If you wanted plot() data for gradients, you would use the argument # `gradients=TRUE' in the call to plot() as the following # demonstrates... plot.out <- plot(fit, perspective=FALSE, errors="bootstrap", B=25, output="both", gradients=TRUE) # Now grab object that plot() plotted on the screen. First, take the # output, lower error bound and upper error bound... note that gradients # are stored in objects rg1, rg2 etc. grad.eval <- gradients(plot.out$rg1) grad.se <- gradients(plot.out$rg1, se = TRUE) grad.lower.ci <- grad.eval + grad.se[,1] grad.upper.ci <- grad.eval + grad.se[,2] # Next grab the x evaluation data. xdat is a data.frame(), so we need to # coerce it into a vector (take `first column' of data frame even though # there is only one column) age.eval <- plot.out$rg1$eval[,1] # We plot the results using R's plot() routines... plot(age.eval,grad.eval,cex=0.2, ylim=c(min(grad.lower.ci),max(grad.upper.ci)), xlab="Age",ylab="d log(Wage)/d Age",type="l") lines(age.eval,grad.lower.ci,lty=3) lines(age.eval,grad.upper.ci,lty=3) # EXAMPLE 4: Variations on local polynomial conditional density # estimation with proper = TRUE. data("Italy") Italy2 <- within(Italy, { year <- as.numeric(as.character(year)) }) # Plot only: make the plotted surface proper on the plot evaluation grid. fhat <- npcdens(gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1) plot(fhat, proper = TRUE) # Fit an object whose fitted values are themselves proper. ctrl_fit <- list( mode = "slice", apply = "fitted", slice.grid.size = 101L, slice.extend.factor = 0.1 ) fhat_fit <- npcdens( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_fit ) fit_proper <- fitted(fhat_fit) fit_raw <- fhat_fit$condens.raw # Display the repaired and raw fitted values for cases where the raw # fitted density is negative. head(cbind(fit_proper, fit_raw)[which(fit_raw < 0), ]) # Predict on a common explicit y-grid for several years, and render # those predictions proper. g.grid <- seq(min(Italy2$gdp), max(Italy2$gdp), length.out = 200) nd_grid <- expand.grid( gdp = g.grid, year = c(1955, 1975, 1995) ) pred_grid <- predict(fhat, newdata = nd_grid, proper = TRUE) # Predict on paired rows with different gdp grids by year, and still # make the predictions proper via slice mode. g1 <- seq(quantile(Italy2$gdp, 0.10), quantile(Italy2$gdp, 0.60), length.out = 60) g2 <- seq(quantile(Italy2$gdp, 0.30), quantile(Italy2$gdp, 0.90), length.out = 35) nd_slice <- rbind( data.frame(gdp = g1, year = rep(1960, length(g1))), data.frame(gdp = g2, year = rep(1985, length(g2))) ) pred_slice <- predict( fhat, newdata = nd_slice, proper = TRUE, proper.control = list(mode = "slice") ) # One object that carries properization for fitted values and for later # predict() calls. ctrl_both <- list( mode = "slice", apply = "both", slice.grid.size = 101L, slice.extend.factor = 0.1 ) fhat_both <- npcdens( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_both ) fit_both <- fitted(fhat_both) pred_both <- predict( fhat_both, newdata = nd_slice, proper.control = ctrl_both ) plot(fhat_both) }) ## End(Not run)## Not run: # EXAMPLE 1: For this example, we load Giovanni Baiocchi's Italian GDP # panel (see Italy for details), then create a data frame in which year # is an ordered factor, GDP is continuous, compute bandwidths using # likelihood cross-validation, then create a grid of data on which the # density will be evaluated for plotting purposes data("Italy") with(Italy, { data <- data.frame(ordered(year), gdp) # Compute bandwidths using likelihood cross-validation (default). Note # that this may take a minute or two depending on the speed of your # computer... bw <- npudensbw(dat=data) fit <- npudens(tdat=data, bws=bw) # You can always do things manually, as the following example demonstrates # Create an evaluation data matrix year.seq <- sort(unique(year)) gdp.seq <- seq(1,36,length=50) data.eval <- expand.grid(year=year.seq,gdp=gdp.seq) # Generate the estimated density computed for the evaluation data fhat <- fitted(npudens(tdat = data, edat = data.eval, bws=bw)) # Coerce the data into a matrix for plotting with persp() f <- matrix(fhat, length(unique(year)), 50) # Next, create a 3D perspective plot of the PDF f persp(as.integer(levels(year.seq)), gdp.seq, f, col="lightblue", ticktype="detailed", ylab="GDP", xlab="Year", zlab="Density", theta=300, phi=50) # Sleep for 5 seconds so that we can examine the output... Sys.sleep(5) # However, plot simply streamlines this process and aids in the # visualization process (<ctrl>-C will interrupt on *NIX systems, <esc> # will interrupt on MS Windows systems). plot(fit) # plot also streamlines construction of variability bounds (<ctrl>-C # will interrupt on *NIX systems, <esc> will interrupt on MS Windows # systems) plot(fit, errors = "asymptotic") # EXAMPLE 2: For this example, we simulate multivariate data, and plot the # partial regression surfaces for a locally linear estimator and its # derivatives. set.seed(123) n <- 100 x1 <- runif(n) x2 <- runif(n) x3 <- runif(n) x4 <- rbinom(n, 2, .3) y <- 1 + x1 + x2 + x3 + x4 + rnorm(n) X <- data.frame(x1, x2, x3, ordered(x4)) bw <- npregbw(xdat=X, ydat=y, regtype="ll", bwmethod="cv.aic") fit <- npreg(bws=bw) plot(fit) # Sleep for 5 seconds so that we can examine the output... Sys.sleep(5) # Now plot the gradients... plot(fit, gradients=TRUE) # Plot the partial regression surfaces with bias-corrected bootstrapped # nonparametric confidence intervals... this may take a minute or two # depending on the speed of your computer as the bootstrapping must be # completed prior to results being displayed... plot(fit, errors="bootstrap", center="bias-corrected", band="simultaneous") # EXAMPLE 3: This example demonstrates how to retrieve plotting data from # plot(). When plot() is called with the arguments # `output="both"' (or "data"), it returns plotting objects # named r1, r2, and so on (rg1, rg2, and so on when `gradients=TRUE' is # set). Each plotting object's index (1,2,...) corresponds to the index # of the explanatory data data frame xdat (and zdat if appropriate). # Take the cps71 data by way of example. In this case, there is only one # object returned by default, `r1', since xdat is univariate. data("cps71", package = "np") # Compute bandwidths for local linear regression using cv.aic... bw <- npregbw(xdat=cps71$age, ydat=cps71$logwage, regtype="ll", bwmethod="cv.aic") fit <- npreg(bws=bw) # Generate the plot and return plotting data, and store output in # `plot.out' (NOTE: the call to `output' is necessary). plot.out <- plot(fit, perspective=FALSE, errors="bootstrap", B=25, output="both") # Now grab the r1 object that plot plotted on the screen, and take # what you need. First, take the output, lower error bound and upper # error bound... logwage.eval <- fitted(plot.out$r1) logwage.se <- se(plot.out$r1) logwage.lower.ci <- logwage.eval + logwage.se[,1] logwage.upper.ci <- logwage.eval + logwage.se[,2] # Next grab the x data evaluation data. xdat is a data.frame(), so we # need to coerce it into a vector (take the `first column' of data frame # even though there is only one column) age.eval <- plot.out$r1$eval[,1] # Now we could plot this if we wished, or direct it to whatever end use # we envisioned. We plot the results using R's plot() routines... with(cps71, plot(age, logwage, cex=0.2, xlab="Age", ylab="log(Wage)")) lines(age.eval,logwage.eval) lines(age.eval,logwage.lower.ci,lty=3) lines(age.eval,logwage.upper.ci,lty=3) # Bias-corrected bootstrap output includes the estimated bias and the # bias-corrected center when available. The sign convention is # bias = estimate - bias.corrected, so bias.corrected = estimate - bias. plot.out <- plot(fit, perspective=FALSE, errors="bootstrap", center="bias-corrected", B=25, output="data") logwage.eval <- fitted(plot.out$r1) logwage.bias <- plot.out$r1$bias logwage.bc <- plot.out$r1$bias.corrected stopifnot(all.equal(logwage.bc, logwage.eval - logwage.bias)) # If you wanted plot() data for gradients, you would use the argument # `gradients=TRUE' in the call to plot() as the following # demonstrates... plot.out <- plot(fit, perspective=FALSE, errors="bootstrap", B=25, output="both", gradients=TRUE) # Now grab object that plot() plotted on the screen. First, take the # output, lower error bound and upper error bound... note that gradients # are stored in objects rg1, rg2 etc. grad.eval <- gradients(plot.out$rg1) grad.se <- gradients(plot.out$rg1, se = TRUE) grad.lower.ci <- grad.eval + grad.se[,1] grad.upper.ci <- grad.eval + grad.se[,2] # Next grab the x evaluation data. xdat is a data.frame(), so we need to # coerce it into a vector (take `first column' of data frame even though # there is only one column) age.eval <- plot.out$rg1$eval[,1] # We plot the results using R's plot() routines... plot(age.eval,grad.eval,cex=0.2, ylim=c(min(grad.lower.ci),max(grad.upper.ci)), xlab="Age",ylab="d log(Wage)/d Age",type="l") lines(age.eval,grad.lower.ci,lty=3) lines(age.eval,grad.upper.ci,lty=3) # EXAMPLE 4: Variations on local polynomial conditional density # estimation with proper = TRUE. data("Italy") Italy2 <- within(Italy, { year <- as.numeric(as.character(year)) }) # Plot only: make the plotted surface proper on the plot evaluation grid. fhat <- npcdens(gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1) plot(fhat, proper = TRUE) # Fit an object whose fitted values are themselves proper. ctrl_fit <- list( mode = "slice", apply = "fitted", slice.grid.size = 101L, slice.extend.factor = 0.1 ) fhat_fit <- npcdens( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_fit ) fit_proper <- fitted(fhat_fit) fit_raw <- fhat_fit$condens.raw # Display the repaired and raw fitted values for cases where the raw # fitted density is negative. head(cbind(fit_proper, fit_raw)[which(fit_raw < 0), ]) # Predict on a common explicit y-grid for several years, and render # those predictions proper. g.grid <- seq(min(Italy2$gdp), max(Italy2$gdp), length.out = 200) nd_grid <- expand.grid( gdp = g.grid, year = c(1955, 1975, 1995) ) pred_grid <- predict(fhat, newdata = nd_grid, proper = TRUE) # Predict on paired rows with different gdp grids by year, and still # make the predictions proper via slice mode. g1 <- seq(quantile(Italy2$gdp, 0.10), quantile(Italy2$gdp, 0.60), length.out = 60) g2 <- seq(quantile(Italy2$gdp, 0.30), quantile(Italy2$gdp, 0.90), length.out = 35) nd_slice <- rbind( data.frame(gdp = g1, year = rep(1960, length(g1))), data.frame(gdp = g2, year = rep(1985, length(g2))) ) pred_slice <- predict( fhat, newdata = nd_slice, proper = TRUE, proper.control = list(mode = "slice") ) # One object that carries properization for fitted values and for later # predict() calls. ctrl_both <- list( mode = "slice", apply = "both", slice.grid.size = 101L, slice.extend.factor = 0.1 ) fhat_both <- npcdens( gdp ~ year, data = Italy2, regtype = "lp", degree = 3, nmulti = 1, proper = TRUE, proper.control = ctrl_both ) fit_both <- fitted(fhat_both) pred_both <- predict( fhat_both, newdata = nd_slice, proper.control = ctrl_both ) plot(fhat_both) }) ## End(Not run)
se is a generic function which extracts standard errors
from objects.
se(x)se(x)
Object to interrogate for standard errors.
x |
an object for which the extraction of standard errors is meaningful. |
This function extracts stored standard errors; it does not select
bandwidths, refit a model, or run a bootstrap. For estimators with a
se fitting control, request se = TRUE when those errors
will be needed. With se = FALSE, errors are deliberately absent
and this accessor explains how to refit with se = TRUE, reusing
the bandwidth object without repeating bandwidth selection.
Requested but unavailable standard errors may remain NA;
extraction does not replace or recompute them.
Standard errors extracted from the model object x.
This method currently only supports objects from the np library.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
fitted, residuals, coef,
and gradients, for related methods;
np for supported objects.
x <- rnorm(10) se(npudens(npudensbw(~x), se = TRUE))x <- rnorm(10) se(npudens(npudensbw(~x), se = TRUE))
uocquantile is a function which computes quantiles of an
unordered, ordered or continuous variable x.
uocquantile(x, prob)uocquantile(x, prob)
Variable and requested probability for mixed-type quantile extraction.
x |
an ordered, unordered or continuous variable. |
prob |
quantile to compute. |
uocquantile is a function which computes quantiles of
an unordered, ordered or continuous variable x. If x
is unordered, the mode is returned. If x is ordered, the level
for which the cumulative distribution is >= prob is returned. If
x is continuous, quantile is invoked and the
result returned.
A quantile computed from x.
Tristen Hayfield [email protected], Jeffrey S. Racine [email protected]
x <- rbinom(n = 100, size = 10, prob = 0.5) uocquantile(x, 0.5)x <- rbinom(n = 100, size = 10, prob = 0.5) uocquantile(x, 0.5)
Cross-section wage data consisting of a random sample
taken from the U.S. Current Population Survey for the year 1976. There
are 526 observations in total. data("wage1") makes available the
dataset "wage" plus additional objects "bw.all" and
"bw.subset".
data("wage1")data("wage1")
A data frame with 24 columns, and 526 rows.
Two local-linear rbandwidth objects (bw.all and
bw.subset) have been computed for the user's convenience
which can be used to visualize this dataset using
plot(bw.all)
column 1, of type numeric, average hourly earnings
column 2, of type numeric, years of education
column 3, of type numeric, years potential experience
column 4, of type numeric, years with current employer
column 5, of type factor, =“Nonwhite” if nonwhite, “White” otherwise
column 6, of type factor, =“Female” if female, “Male” otherwise
column 7, of type factor, =“Married” if Married, “Nonmarried” otherwise
column 8, of type numeric, number of dependants
column 9, of type numeric, =1 if live in SMSA
column 10, of type numeric, =1 if live in north central U.S
column 11, of type numeric, =1 if live in southern region
column 12, of type numeric, =1 if live in western region
column 13, of type numeric, =1 if work in construction industry
column 14, of type numeric, =1 if in non-durable manufacturing industry
column 15, of type numeric, =1 if in transportation, communications, public utility
column 16, of type numeric, =1 if in wholesale or retail
column 17, of type numeric, =1 if in services industry
column 18, of type numeric, =1 if in professional services industry
column 19, of type numeric, =1 if in professional occupation
column 20, of type numeric, =1 if in clerical occupation
column 21, of type numeric, =1 if in service occupation
column 22, of type numeric, log(wage)
column 23, of type numeric, exper
column 24, of type numeric, tenure
Jeffrey M. Wooldridge
Wooldridge, J.M. (2000), Introductory Econometrics: A Modern Approach, South-Western College Publishing.
data("wage1") with(wage1, { summary(wage1) })data("wage1") with(wage1, { summary(wage1) })