General Purpose Plotting of Nonparametric Objects
np.plot.RdBias-corrected bounds are experimental (pre-beta research), incomplete, and not recommended for general-purpose inference. See the experimental-status section below.
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.
Arguments
- x
an object generated by the np package. The most convenient inputs are fitted estimator objects returned by invocations of
npudens,npcdens,npreg,npconmode,npplreg,npindex, ornpscoef. Bandwidth objects returned bynpudensbw,npcdensbw,npregbw,npplregbw,npindexbw, ornpscoefbware also supported when plotting should construct the fitted object.
Data and evaluation controls
datareplacement training data for the partially linear formula-bandwidth plot route, when explicit training inputs are omitted. Other plot routes do not consume this argument and reject it, including explicit
NULL. Refit with the intended data before plotting; seenp-data-interfaces.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. Fornpudens/npudistperspective 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 hasneval^2evaluation points.xdat,ydat,zdattraining data used when plotting bandwidth objects.
xdatis the regressor/conditioning data,ydatis the response or conditional outcome data, andzdatis the auxiliary semiparametric covariate block when relevant.xq,yq,zqquantiles used to hold non-plotted variables fixed when constructing slices. Single-index plots have one index axis and reject
grid_control$xq. Theirgrid_control$xtrimselects the lower and upper quantiles of the fitted index.xtrim,ytrim,ztrimtrimming/expansion controls for the evaluation support.
Plot content controls
coef,coef_indexcoefficient-function plotting controls for semiparametric families where supported. For smooth-coefficient plots with
coef = TRUE,coef_indexselects the intercept as 1 and then the fitted regressors in order. An index beyond the available coefficients is an error; it is not replaced by the last coefficient.common_scalea logical value specifying whether multiple panels should share a common plotting scale when feasible.
gradient_order,gradientsderivative plotting controls for families that support gradients/derivatives. For
npreglocal-polynomial objects,gradient_orderrequests the continuous-predictor derivative order to generate on the plot evaluation grid; if omitted the first derivative/effect is plotted. Location-scale quantile-regressionnplsqregobjects use the same coordinate-wise local-polynomial contract while preserving their existingtau-indexed output; no mixed partials are generated. When a requested continuous derivative order exceeds that coordinate's fitted degree, its values remainNAand 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 \(\Delta\) labels. Fornpconmodeobjects,gradients=TRUEplots stored class-probability gradients/effects for the selected response level, computed bynpconmode(..., gradients=TRUE, level=...).levelresponse level to plot for class-probability displays when supported, notably
plot.conmode. If omitted, the default fornpconmodeobjects is the base/reference response levellevels(y)[1]. These plots require probabilities stored bynpconmode(..., probabilities=TRUE). Supported probability/effect intervals and surface grids use the selected response level; seenpconmodefor eligibility.layout"auto"orTRUErequests automaticpar(mfrow=...)management for multi-panel plots."current"orFALSEpreserves the user's current graphics layout.outputone of
"plot","data", or"plot-data". Data-returning modes use the commonnp_plot_dataschema.proper,proper_control,proper_methodcontrols 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
tauvalues overlays the corresponding conditional quantile curves and reuses the stored bandwidth object. Witherrors="asymptotic"orerrors="bootstrap", intervals are constructed separately for each requestedtau; bootstrap work is shared acrosstauvalues within each resample. Fornpqregobjects whose conditional-distribution bandwidths were selected withnomad=TRUE, plotting reuses the stored LPregtype.engineand selecteddegree.enginemetadata.
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 \(1-\alpha=0.95\). 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"; directnpcopulaandnpconmodeplots retain their method-specific"pointwise"default. The meaning of a band name depends on whethererrors="bootstrap"orerrors="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.bias_controlregression auxiliary settings created by
np_bias_control, or optional fixed-bandwidth density settings created bynp_udens_bias_control. Used withcenter="bias-corrected". Omitting the control selects the corresponding corrected construction. The default estimate center is unchanged. Explicitconstruction="legacy"retains the previous bootstrap correction. Density Gaussian/inid support, finite-draw restrictions and practical coverage limitations are detailed innp_udens_bias_control.bootstrapthe bootstrap resampling scheme. Regression-family plots support
"wild","inid","fixed", and"geom"; density/distribution-family plots support"inid","fixed", and"geom". Experimental regressioncalibration="smoothed-percentile"additionally usesbootstrap="residual"; seenp_boot_controlfor its scope and defaults.boxplot_outliers,factor_boxplotboxplot-style bootstrap summary controls for factor/categorical displays when available.
centerone of
"estimate"(the default) or"bias-corrected". For ordinary regression, the latter selects iterated correction with Gaussian or bootstrap calibration; seenp_bias_controlfor its supported scope, auxiliary settings and coverage qualifications. Other estimator families retain their method-specific bootstrap corrections. Unsupported combinations fail explicitly. 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 toband. 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. Fornpqreglevel 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 fromplot(). The option is ignored for derivative/gradient plots and coefficient plots. Overlay points default to small, light markers and can be customized with standardpoints()arguments passed via...(for examplepch,cex,col, andbg). Default isTRUE.legendlegend control for legends drawn by the package, including vector-
taunpqreglevel plots andband="all"uncertainty legends.TRUEdraws the default legend,FALSE,NULL, orNAsuppresses it, a single character string supplies the legend position, and a list is merged into the defaultlegendcall for custom labels, placement, or styling. For plot routes with more than one package-drawn legend, named sublists such aslegend=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 andrenderer="rgl"draws the analogous 3D floor-rug ticks on supported surface routes. In this rollout tranche,data_rug=TRUEis implemented across the current base plot families and across supportedrglsurface 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 fromdata_overlay:data_rugshows where observations lie in the plotted covariate support, whiledata_overlayis the regression-only 3D response overlay used on supported surface plots. On supported regression surfaces, both options may be used together. Default isFALSE.perspectivea logical value specifying whether bivariate continuous surfaces are displayed with
persp-style plots when relevant.phi,theta,viewview 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 Rpersppath."rgl"is currently a fail-closed backend for supported plain 2D surface routes innpreg/npregbw,npplreg/npplregbw,npscoef/npscoefbw,npudens/npudensbw,npudist/npudistbw,npcdens/npcdensbw, andnpcdist/npcdistbw. In this tranche,renderer="rgl"requiresperspective=TRUE,view="fixed"andoutput="plot"; unsupported combinations still error rather than falling back silently. The suggested packagesrglandhtmlwidgetsmust be installed whenrenderer="rgl"is requested. When drawn, therglsurface is displayed via the activerglbackend, which on this rollout path is typically the RStudio Viewer or a browser/WebGL window rather than the base graphics plot pane. The base andrglrenderers share the same viridis palette mapper and neutral-gray three-face reference-grid default. Whencolis omitted, therglsurface uses a value-basedhcl.colors(..., "viridis")gradient. When the inherited base-view defaultstheta=0andphi=20are left unchanged, therglbackend usestheta=0,phi=-70, andfov=55to 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 supportednpreg,npplreg, and plain mean-surfacenpscoefsurface routes,data_overlay=TRUEadds observed data as an interactive point cloud. For all currently supportedrglsurface 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. Fornpscoef/npscoefbw,renderer="rgl"currently applies only to the plain mean-surface route; coefficient-mode plots remain on the base renderer. Commonrgldisplay controls may be supplied directly in...on supported routes, including surface arguments such asalpha,back, andfront, and view arguments such asfovandzoom. Additional backend-specific arguments may be passed through using prefixed names in..., namelyrgl.persp3d.<arg>,rgl.view3d.<arg>,rgl.par3d.<arg>,rgl.grid3d.<arg>, andrgl.widget.<arg>, andrgl.legend3d.<arg>. For the new overlay layers,rgl.points3d.<arg>customizes observed-point overlays andrgl.surface3d.<arg>customizes interval surfaces. Whenband="all"is used on supportedrglroutes, a matching construction-aware interactive legend is drawn using the same default labels as the base renderer, andrgl.legend3d.<arg>may be used to customize it, for examplergl.legend3d.bty="o"to restore a legend box orrgl.legend3d.magnify=1to 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,zlimstandard graphical controls forwarded to the underlying plotting primitives when relevant. In continuous two-dimensional regression panels,
xlimsets the display limits without changing the evaluation grid or the family used to calibrate simultaneous bands.
Reproducibility controls
random_seedan optional random seed used to make bootstrap plotting reproducible.
Details
Seeded temporary operations follow np_rng_scope.
Ordinary bias-corrected distribution calibration with unsigned fixed blocks
refuses multi-tile replay when a custom uniform generator exposes no state
beyond the header of .Random.seed. Select a qualified built-in
generator explicitly before plotting. Single-tile and complete-state paths
retain their existing behavior; numeric nearest-neighbor replay has a separate
construction and is not qualified by this restriction.
Experimental local-constant conditional CDF and density corrected bands are
available through np_conditional_bias_control. They require
explicit selection and preserve existing methods. Their bootstrap response law
is selected explicitly by bootstrap="conditional-pilot", with
calibration="symmetric-sd" or "asymmetric-sd"; it is not pairs
resampling. Read the control help for correction differences, finite-grid
limits, signed returned offsets and known coverage limitations.
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 \(i\), all other variables at
indices \(j \ne i\) are held constant at the quantiles
specified in the \(j\)th element of xq. The default is the
median.
The slice itself is evaluated on a uniformly spaced sequence of
\(neval\) points. By default its limits are the training-data minimum
and maximum. Use grid_control = np_grid_control(xtrim = c(a, b))
to select the a and b quantiles for each numeric variable
in the X block, with 0 <= a < b <= 1. This pair is a range,
not a separate trim amount for each variable. Single-index plots apply
it to the fitted index. Categorical grids continue to use their levels.
In conditional and semiparametric plots it does not alter the separate
response or auxiliary-variable grid controls.
Direct xtrim arguments to the legacy density, distribution,
regression, conditional and semiparametric engines retain their original
meaning: one symmetric tail proportion per X variable (a scalar is recycled).
Negative proportions expand the grid limits by the corresponding tail
distances. This legacy direct-argument convention is distinct from the
ordered range in np_grid_control().
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.
The default variability and legacy bootstrap constructions are listed below. Iterated bias-corrected regression uses the separate construction described immediately after this table.
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 \(m\) is the number of evaluation points used in the plotted curve/surface (\(m=\texttt{neval}\) for univariate curves, typically \(m=\texttt{neval}^2\) for full 2D perspective surfaces).
For regression with center="bias-corrected" and the default
np_bias_control(construction="iterated"), "pmzsd"
retains the symmetric normal-quantile rule around the corrected center.
The other three band types use empirical quantiles of the corrected process.
Gaussian and Mammen calibration use replicate-specific studentization:
pointwise limits use marginal absolute studentized statistics, simultaneous
limits use their within-target maxima, and Bonferroni limits use marginal
tail probabilities adjusted by the number of grid points. An outward
envelope preserves nesting and singleton equality. These bands are symmetric
around the corrected center; asymptotic pointwise limits need not equal
\(z_{1-\alpha/2}\) times the corrected standard error. Other supported
bootstrap laws retain their documented corrected-process calibration;
see np_bias_control for law-specific definitions and support.
In the default and legacy constructions in the table,
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.
Corrected unconditional density and distribution plots also support the
default "pmzsd": the corrected center plus or minus
\(z_{1-\alpha/2}\) times the family-owned corrected scale. This normal
rule is separate from their calibrated pointwise and joint envelopes;
see np_udens_bias_control and
np_udist_bias_control. Their explicit quantile-band
constructions are unchanged.
Outside these corrected constructions, asymptotic "pmzsd"
and "pointwise" are two names for the same symmetric normal
construction. Let \(T(x)\) denote
the plotted functional (mean, gradient, density, distribution, etc.) and
\(\widehat{se}(x)\) its asymptotic standard error. Both use
\(T(x)\pm z_{1-\alpha/2}\widehat{se}(x)\).
"bonferroni" applies the same rule with \(\alpha/m\) in place
of \(\alpha\).
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.
Estimate-centered unconditional density plots also support fixed second-order
beta kernels with known finite ckerbound="fixed" bounds in one or two
continuous coordinates. These bands retain the fitted curve and its incumbent
marginal standard errors, using centered beta-kernel contributions for
cross-grid dependence. They describe variability around the smoothed target;
they do not correct smoothing bias. Range-derived bounds, nearest-neighbor,
mixed and higher-dimensional beta specifications keep their existing joint-band
restrictions. Beta CDF admission is unchanged.
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.
Known-fixed-bound order-2 beta density plots support a separate corrected
guide-region plus residual construction in one or two continuous dimensions.
With omitted bias_control, request asymptotic errors or independent
bootstrap calibration="symmetric-sd"/"asymmetric-sd", and
explicitly choose pointwise, simultaneous, Bonferroni or all three bands
together with band="all". Range-derived bounds and
literal endpoints are rejected. All slices share one finite calibration
family; core fits and estimator SEs are unchanged. See
np_udens_bias_control for the distinct beta endpoint rules,
restrictions and limitations. SD Bonferroni intervals use marginal empirical
ranks with an unconditional hull containing the same-draw simultaneous band.
Low tail resolution warns; no draws or Gaussian tail substitutions are added.
All-band requests reuse one preparation and preserve existing components.
Known-fixed-bound order-2 Gaussian density plots also support corrected
asymptotic and independent symmetric-sd/asymmetric-sd intervals for one or
two continuous coordinates, with omitted bias_control and explicit
pointwise/simultaneous/Bonferroni bands or band="all". FG-D combines complete ratio-pilot and empirical
residual intervals with a nonlinear guide region; it is distinct from beta
correction and unbounded D8. Range-derived bounds and literal endpoints are
rejected. All slices form one finite calibration family. See
np_udens_bias_control for assumptions and endpoint rules.
For one continuous variable, these known-fixed-bound order-2 beta and Gaussian
density plots additionally support asymptotic normal intervals with omitted
band or band="pmzsd" and omitted bias_control.
The corrected center is unchanged. The complete influence variance is
integrated under the normalized positive ratio pilot, including guide and
cross-covariance terms, and uses ordinary normal critical values.
These are marginal intervals, distinct from the calibrated guide-region bands;
band="all" retains its three existing calibrated components.
Fixed-bound order-2 beta plots also support these normal intervals for two
continuous coordinates. Their complete variance retains the joint guide-score
dependence and all guide/kernel cross terms under the ratio pilot; the
original corrected center is unchanged. Normal interval calculations process
targets in blocks while retaining the complete requested grid. Admission
accounts for the target results and both guide preparations within the
existing 192 MiB plot-workspace limit; requests whose actual geometry exceeds
that limit still stop. This is distinct from full-covariance calibrated bands
and does not bound the memory used by the entire R process.
This normal approximation can be
less accurate at sparse boundary targets in small samples. Two-dimensional
Gaussian normal intervals, bootstrap pmzsd, estimated bounds and literal
support endpoints are not admitted by this additional construction. See
np_udens_bias_control for its assumptions and limitations.
Known-fixed-bound order-2 uniform and Epanechnikov density plots support
corrected asymptotic pointwise, Bonferroni, simultaneous and all bands for
one continuous coordinate and a fixed bandwidth. The plot-only local-cubic
correction retains the fitted physical bandwidth and combines a nonlinear
guide region with the envelope of complete pilot and empirical residual
covariance bands. This does not alter the original second-order estimate.
Supply an explicit band and omit density bias controls; explicit existing
controls retain their own constructions. Observations and evaluation points
must be strictly inside the supplied finite bounds, with at least ten
observations. Range-estimated bounds, literal endpoints, nearest-neighbor
bandwidths, higher orders and multivariate calibrated compact correction
are not admitted by this construction.
With errors="asymptotic", omitted band or
band="pmzsd" instead uses the same corrected center and complete
normalized ratio-pilot influence variance with normal critical values.
Guide and cross-covariance contributions are included. These marginal
intervals require no simulated draws; they are distinct from the calibrated
pointwise and simultaneous bands. The one-coordinate normal route retains
a 192 MiB plot-workspace limit. Its quadrature uses the full target grid,
so some moderate grids (for example, around 100 targets) exceed this limit
depending on bandwidth, support and data geometry. The check can refuse a
request after the first numerical refinement has completed; no smaller
grid is substituted automatically. Finite-sample accuracy can be weaker at
individual sparse or tail targets. These asymptotic normal intervals also
support two continuous coordinates under the same fixed-bound, fixed-bandwidth
and interior-target restrictions, with omitted density bias controls and
0 < alpha < 0.5. The two-dimensional variance includes joint
guide-score dependence and every guide/kernel cross term. Target blocks
recompute their own compact-support quadrature; the complete requested grid
is retained within the 192 MiB plot-workspace bound. Normal intervals remain
marginal and keep their separate construction. A separate fixed-bound q2
addition supports asymptotic pointwise and Bonferroni calibrated intervals,
and independent symmetric-sd/asymmetric-sd intervals with all four explicit
band types. These require omitted density bias controls and the same interior
data/target restrictions. For SD bands explicitly select bootstrap="inid"
and the calibration in boot_control. Asymptotic simultaneous/all and
bootstrap pmzsd are not admitted by this addition. See
np_udens_bias_control for the distinct uncertainty constructions
and their conservative, finite-grid evidence.
For corrected bootstrap bands, supply errors="bootstrap", explicit
bootstrap="inid", an explicit band, and
boot_control=np_boot_control(calibration="symmetric-sd") or
boot_control=np_boot_control(calibration="asymmetric-sd").
Each literal resample refits the guide; the residual functional, rather than
the complete corrected curve, is bootstrapped at the original empirical
residual scale. The original nonlinear guide region is included once.
Complete intervals under the pilot and empirical transport scales are
enveloped. Symmetric calibration uses an outward-rounded containing hull;
asymmetric calibration inverts signed roots. All three components of
band="all" share one preparation, refit set and stream. Omitted
controls retain their existing behavior; this does not select a new default.
The simultaneous claim concerns the supplied finite family, not a continuum.
Saved-sample screening for these experimental SD bands was substantially
conservative, with very wide intervals possible near singular edges. It does
not guarantee nominal coverage for arbitrary densities or very small samples.
Low finite-draw tail resolution, particularly for Bonferroni bands, is reported
without changing B; defined finite limits are retained.
Default bias-corrected unconditional unbounded Gaussian density plots use the D8
positive-pilot construction for eligible asymptotic requests; see
np_udens_bias_control. It uses complete corrected covariance
and a standardized full-grid Gaussian maximum, combining all slices in one
plot call. Explicit density controls and bootstrap inference retain their
existing constructions. The following incumbent-scale description applies
to the other density-family Gaussian bands.
These density-family bands use the incumbent marginal standard errors and the correlation of centered observation-level empirical influence rows. Writing \(D\) for the diagonal matrix of those standard errors and \(R\) for that correlation, the working covariance is \(D R D\). 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.
Selected corrected regression and multi-tile fixed numeric joint CDF requests are also refused before seeding when a custom uniform generator exposes only a seed header without replay state. The generator is never changed silently; users may explicitly select a qualified built-in generator. A nonempty seed payload does not certify arbitrary custom state or callback behavior.
Explicit joint-scale and saved version-2 positive-covariance density controls refuse Box–Muller factor replay above 512 targets on fixed numeric Gaussian geometry. This covers all band displays because these providers compute joint calibration internally; the default density provider is unchanged. The explicit CDF construction also refuses Box–Muller factor replay above 32 targets for simultaneous or all bands on fixed numeric Gaussian geometry. Its smaller covariance and deterministic marginal bands remain available. Ordinary complete retained native training values and formula training frames can establish the regression replay size even without retained residuals. This includes retained simple-symbol formulas with quoted predictor names. Explicit training arguments take precedence; calls and NA policies are not reevaluated by the early check. If the early check cannot determine the regression sample size, the existing resolved-data Gaussian cache owner also refuses Box–Muller requests above its 16 MiB limit, before internal replay. This backstop uses the training data after the original data/NA processing; it does not evaluate those callbacks again. Unlike the early check, it runs inside the existing plot seed scope, whose caller-state admission and restoration contract is described below. Known unsafe Box–Muller replay is refused before seeding for corrected Gaussian regression above the 16 MiB retained-innovation limit when ordinary training data are already available, and for multi-tile fixed numeric joint CDF calibration. The error does not change the selected generator. Users may explicitly select a qualified normal generator, such as Inversion. Explicit tiled density/CDF factor providers also refuse a custom uniform generator whose visible seed contains only a header without replay state. These checks also cover unsigned geometric joint-CDF calibration on the admitted multi-tile fixed numeric geometry. Signed fixed/geometric joint-CDF requests also refuse a header-only custom uniform generator at the resolved inference owner when multiple target tiles require replay and the innovation cache is unavailable. Cached and single-tile paths retain their existing behavior. The resolved check does not reevaluate data or NA callbacks, and runs inside the existing seed scope, which separately admits and restores caller state. At the shared resolved seed-only replay owner, a nonempty custom seed payload is also insufficient: user-supplied uniform generators, and user-supplied normal generators when the requested draws consume normal variates, are refused unless the existing route retains the innovations. The same rule applies to the explicit tiled factor providers and MPI bootstrap task-state transport. It does not change the selected generator or resampling law. Normal-free paths do not refuse an unused custom normal generator. This admission rule does not certify temporary seed restoration. These checks are bounded: other reconstruction and RNG replay cases remain unqualified; non-refusal is not a general RNG safety certificate.
random_seed (default 42) controls reproducible calibration. Before
changing the seed, a temporary seed scope checks that caller state can be
restored. It refuses Box–Muller and uncertifiable user-supplied generator
state, including hidden state absent from .Random.seed; it never
silently substitutes a generator. For admitted built-in states, it restores
caller continuation and the original seed binding (including its absence).
Users may explicitly select a supported built-in generator and set a seed.
Deterministic fixed-bound beta and FG-D requests that do not enter a temporary
seed scope retain their existing behavior, including under Box–Muller.
Scope restoration is separate from replay admission within a calculation:
retained innovations can qualify replay without certifying a seed reset.
These guarantees do not certify arbitrary RNG changes made by user callbacks.
For the standard asymptotic Gaussian calibration described above (excluding
the fixed-bound beta and FG-D guide-region constructions), a
gaussian_draws 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 \(\alpha\) 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.
Fixed-bound beta and FG-D density constructions instead warn about finite
tail-rank resolution when \(\lfloor B\alpha/2\rfloor<20\) for symmetric-SD
bootstrap or asymptotic simultaneous calibration, or when
\(\lfloor B\alpha/4\rfloor<20\) for asymmetric-SD bootstrap. Here \(B\)
denotes the requested gaussian_draws for asymptotic simulation and
the requested bootstrap B otherwise. At \(\alpha=0.05\), these
warnings occur below 800 and 1600 draws, respectively. Their asymptotic
pointwise calculation uses a normal quantile without simulated draws.
These are resolution diagnostics, not guarantees of coverage or critical-value
accuracy. A finite result is returned at the requested count if the other
numerical checks pass.
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 \(S\) for the training smoother and \(L\) for its evaluation
influence map. The covariance is
\(L\operatorname{diag}(z_i^2)L^\mathsf{T}\), where
\(z_i=((I-S)y)_i/\sqrt{\sum_j(\delta_{ij}-S_{ij})^2}\).
For regression derivatives, replace \(L\) 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.
Returned np_plot_data records identify each scalar target,
its absolute interval endpoints and compact calibration metadata, including
available draw counts, grid sizes, critical values and dependence contracts.
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 \(R=X-S_xX\) and \(R_e=X_e-L_xX\), with each column using its own nuisance smoother, and let \(K=R^+(I-S_y)\). The evaluation map is \(H=L_y+R_eK\); the training map is \(S=S_y+RK\). The plot covariance is \(H\operatorname{diag}(z_i^2)H^\mathsf{T}\), 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 interval tables follow the explicit flattened grid
row identifiers. Single-index gradient targets retain their coefficient
identity. Calibration reports rank=NA when 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 \(z\)-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 variability bands.
Iterated bias-corrected regression instead identifies Gaussian studentized
quantiles and maximum-based calibration where applicable. 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.
In data-returning modes, values$estimate and
values$bias_corrected contain the original and corrected scalar
targets. The latter is NA when not computed. Absolute endpoints
are in intervals$lower and intervals$upper; use
as.data.frame(result, panel=1, target=1, band="simultaneous")
for a joined table. This convention applies to levels and derivatives.
Two-dimensional estimator plots do not draw a second corrected surface;
corrected surface values remain available in the returned table.
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.
Ordinary regression now uses the iterated construction described in
np_bias_control. The plot result records the corrected values, requested endpoints and
compact construction metadata; internal process workspaces are not returned.
Pointwise, simultaneous and Bonferroni bands share this construction.
The following legacy centering discussion applies to the other supported
families and to explicit regression construction="legacy".
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
original and corrected values should be inspected when bias correction
is scientifically important. Derivative and categorical-effect rows use the
same columns and explicit target identities.
The pilot rule is family-specific. For fixed-bandwidth regression plots, the non-wild pilot uses the full oversmoothing-rate rule: $$g_j = h_j n^{2r / ((p + 2r)(p + 4r))},$$ where \(h_j\) is the selected bandwidth, \(r\) is the continuous kernel order, and \(p\) is the number of continuous smoothing variables in that regression route. For ordinary second-order kernels with one continuous smoothing variable this reduces to \(g_j = h_j n^{4/45}\). 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 \(g_j = h_j\), 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 \([-\sqrt{5},\sqrt{5}]\) 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
\(g_y = h_y\); 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
$$g_{xj} = h_{xj} n^{2r / ((p + 2r)(p + 4r))},$$
and for conditional distribution this is
$$g_{xj} = h_{xj} n^{r / ((p + r)(p + 2r))},$$
where here \(p\) 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.
For ordinary regression confidence-style bounds, Gaussian or bootstrap
calibration can be used with center="bias-corrected". Other families
retain their supported bootstrap corrections. 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.
Estimate-centered unconditional density plots also support finite-grid
asymptotic simultaneous variability bands for fixed-bandwidth uniform kernels
with one or two continuous coordinates, either unbounded or with known
ckerbound="fixed" bounds, including one-sided and partially
bounded supports. Empirical kernel-contribution
correlations are rescaled to the existing marginal standard errors; the
Gaussian maximum is calibrated over the declared grid, not a continuum.
These bands do not correct smoothing bias or account for bandwidth selection.
band="all" retains the pointwise and Bonferroni intervals unchanged.
A constant kernel window with positive marginal uncertainty has unidentified
empirical correlation: simultaneous limits remain unavailable with a warning,
while the marginal intervals are retained. Range bounds and other new uniform
bandwidth/dimension classes are not admitted by this extension.
The same estimate-centered joint variability construction supports fixed Gaussian and Epanechnikov kernels of orders 4, 6 and 8, with one or two continuous coordinates and unbounded or finite known fixed support. Signed kernel contributions are retained in the empirical correlations. The fitted curve and ordinary marginal standard errors are not replaced. If marginal uncertainty is unavailable at any target of the requested panel, simultaneous limits for that whole panel remain unavailable with a warning; calibration does not silently use a reduced grid. Pointwise and Bonferroni intervals remain available at the other targets. Skipping an unavailable panel can change later panels' simulated critical values at Monte Carlo precision because panels share the plot call's calibration stream. Fixed-bandwidth beta kernels of orders 4, 6 and 8 also support these estimate-centered joint variability bands in one or two continuous dimensions with finite known fixed bounds. Their signed observation contributions are retained; this does not extend beta bias-corrected methods or change the native marginal standard errors. This higher-order addition does not admit CDFs, conditional estimators, nearest-neighbour bandwidths, range bounds or bias-corrected requests.
For ordinary estimate-centered plots, 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.
Outside iterated regression correction, bootstrap resampling is conducted pairwise on \((y,X,Z)\) (i.e., by resampling rows of \((y,X)\) or \((y,X,Z)\) 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.
Legacy bias-corrected bootstrap centering is 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)
Raw asymmetric iterated regression bands are available with
boot_control=np_boot_control(calibration="separate-tails");
calibration="tail-envelope" adds empirical absolute-root protection.
These options require bootstrap bias-corrected empirical bands and retain
the selected wild/inid/fixed/geom law. See np_boot_control
for scope and finite-sample limitations.
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
\(y\)-grid, while each conditional distribution slice is projected to
be monotone and bounded in \([0,1]\). 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 \(b\) should grow with the sample size \(n\) at an appropriate rate. If \(b\) is not given, then a default growth rate of \(const \times n^{1/3}\) 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 \(const\) (\(3.15\)) has been determined by a Monte Carlo simulation using a Gaussian AR(1) process (AR(1)-parameter of 0.5, 500 observations). \(const\) 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
\(B \ge \lceil 2/\alpha - 1 \rceil\).
For "bonferroni", "simultaneous", and "all", the warning
uses \(B_{\min}=\lceil 2m/\alpha-1 \rceil\),
where \(m\) is the actual within-panel evaluation count, including
\(m=\texttt{neval}^2\) 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 snake_case. Retired dotted plot
spellings are rejected with migration guidance. Non-plot APIs and control
constructor arguments retain their existing names. 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.
Empty conditional-density windows
For ordinary local-constant conditional-density plots with nonnegative kernels, finite empty empirical response windows do not establish zero uncertainty. Asymptotic and fixed-bandwidth bootstrap marginal limits are unavailable there. The estimates and all requested grid rows are retained; if any member lacks uncertainty, the full requested simultaneous band is unavailable. Available pointwise and Bonferroni limits are retained. This disclosure does not alter raw estimation, corrected inference, derivatives, or declared outside-support zeros.
Value
output="data" returns a np_plot_data object without
drawing; output="plot-data" draws and returns the same data.
output="plot" draws and invisibly returns NULL for base
graphics, or retains the existing interactive renderer result. The plot-data
object contains explicit grids, scalar targets, absolute intervals, compact
inference metadata and finite-grid coverage-family definitions. It does not
inherit a fitted-estimator class. See np_plot_data for the
schema, extraction, derivative and replay contracts.
References
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.
Author
Tristen Hayfield tristen.hayfield@gmail.com, Jeffrey S. Racine racinej@mcmaster.ca
Usage Issues
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.
Experimental status of bias-corrected inference
All bias-corrected confidence intervals and bands are experimental (pre-beta research), incomplete, and not recommended for general-purpose inference. This status remains in effect unless the documentation explicitly states otherwise for a particular method and scope. It applies wherever bias-corrected bounds are available: asymptotic and bootstrap constructions, including legacy methods, pointwise intervals, Bonferroni intervals and simultaneous bands, for levels and supported derivatives.
These methods form an ongoing research project. Implementation support, numerical checks and favorable simulation results in selected settings do not establish generally valid coverage. Coverage can fail outside the studied settings, and available options do not constitute a general solution to bias-corrected inference. Method-specific assumptions, restrictions and known failures must be considered when experimenting with these bounds.
A known limitation concerns pilot-based normal-scale, bias-corrected density
intervals, including the fixed-support beta and Gaussian constructions and
the one- and two-dimensional uniform and Epanechnikov normal constructions. These use normal critical values for
band="pmzsd" (also selected when band is omitted on these
routes). The fitted pilot reference law can substantially understate
uncertainty even when all joint bias-correction covariance terms are included.
Residual smoothing bias and sparse information can also cause poor coverage
of the true density. These limitations are not confined to numerical failures
or extreme stress tests. Data-driven bandwidth selection, including
cross-validation, does not by itself establish valid bias-corrected coverage.
Results for a particular calibrated construction do not establish coverage for
other constructions. These bounds should be used for methodological
experimentation, with independent coverage assessment for the intended setting.
Examples
if (FALSE) { # \dontrun{
# 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: Common extraction for a level and a derivative target.
data("cps71", package = "np")
bw <- npregbw(xdat=cps71$age, ydat=cps71$logwage,
regtype="ll", bwmethod="cv.aic")
fit <- npreg(bws=bw)
plot.out <- plot(fit, perspective=FALSE, errors="bootstrap",
B=25, band="pointwise", output="plot-data")
d <- as.data.frame(plot.out, panel=1, target=1)
age.eval <- d$eval_1
logwage.eval <- d$estimate
logwage.lower.ci <- d$lower
logwage.upper.ci <- d$upper
# Corrected values are descriptive targets, not offsets to add to endpoints.
p <- plot(fit, perspective=FALSE, errors="bootstrap",
center="bias-corrected", B=25, band="pointwise", output="data")
d <- as.data.frame(p, panel=1, target=1)
logwage.bc <- d$bias_corrected
logwage.bias <- d$estimate - d$bias_corrected
# The same extraction works for derivatives. Inspect the target identity.
g <- plot(fit, perspective=FALSE, gradients=TRUE, errors="bootstrap",
B=25, band="pointwise", output="data")
g$targets
grad <- as.data.frame(g, panel=1, target=1)
plot(g)
# 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)
})
} # }