Skip to contents

Bias-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.

Usage

# 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, ...)

Arguments

Plot Object

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 npudens, npcdens, npreg, npconmode, npplreg, npindex, or npscoef. Bandwidth objects returned by npudensbw, npcdensbw, npregbw, npplregbw, npindexbw, or npscoefbw are also supported when plotting should construct the fitted object.

Plot Options Passed Through ...

Named options passed via ... include:

Data and evaluation controls

data

replacement 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; see np-data-interfaces.

grid_control

optional detailed grid controls created by np_grid_control.

neval

the 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. Single-index plots have one index axis and reject grid_control$xq. Their grid_control$xtrim selects the lower and upper quantiles of the fitted index.

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. For smooth-coefficient plots with coef = TRUE, coef_index selects 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_scale

a 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 \(\Delta\) labels. For npconmode objects, gradients=TRUE plots stored class-probability gradients/effects for the selected response level, computed by npconmode(..., gradients=TRUE, level=...).

level

response 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). Supported probability/effect intervals and surface grids use the selected response level; see npconmode for eligibility.

layout

"auto" or TRUE requests automatic par(mfrow=...) management for multi-panel plots. "current" or FALSE preserves the user's current graphics layout.

output

one of "plot", "data", or "plot-data". Data-returning modes use the common np_plot_data schema.

proper, proper_control, proper_method

controls for proper conditional density/distribution handling where implemented.

tau

the 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

alpha

the 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.

B

the bootstrap replication count.

band

one 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_control

optional detailed bootstrap controls created by np_boot_control. This controls non-fixed bootstrap behavior, wild-bootstrap multipliers, and dependent-bootstrap block length.

bias_control

regression auxiliary settings created by np_bias_control, or optional fixed-bandwidth density settings created by np_udens_bias_control. Used with center="bias-corrected". Omitting the control selects the corresponding corrected construction. The default estimate center is unchanged. Explicit construction="legacy" retains the previous bootstrap correction. Density Gaussian/inid support, finite-draw restrictions and practical coverage limitations are detailed in np_udens_bias_control.

bootstrap

the bootstrap resampling scheme. Regression-family plots support "wild", "inid", "fixed", and "geom"; density/distribution-family plots support "inid", "fixed", and "geom". Experimental regression calibration="smoothed-percentile" additionally uses bootstrap="residual"; see np_boot_control for its scope and defaults.

boxplot_outliers, factor_boxplot

boxplot-style bootstrap summary controls for factor/categorical displays when available.

center

one of "estimate" (the default) or "bias-corrected". For ordinary regression, the latter selects iterated correction with Gaussian or bootstrap calibration; see np_bias_control for 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.

errors

one 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_overlay

logical; 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.

legend

legend 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_rug

logical; 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.

perspective

a 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_control

optional detailed rendering controls created by np_render_control, including band-versus-bar uncertainty display controls.

renderer

the 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. In continuous two-dimensional regression panels, xlim sets the display limits without changing the evaluation grid or the family used to calibrate simultaneous bands.

Reproducibility controls

random_seed

an optional random seed used to make bootstrap plotting reproducible.

Additional Arguments

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.

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)
})
} # }