Location-Scale Kernel Quantile Regression with Mixed Data Types

nplsqreg computes a location-scale kernel estimate of the conditional quantile function for a one dimensional dependent variable and mixed continuous, unordered factor, and ordered factor explanatory data. Unlike npqreg, which obtains conditional quantiles by inverting an estimated conditional distribution, nplsqreg estimates the requested conditional quantile surface directly using a locally weighted quantile-kernel construction.

Usage

nplsqreg(bws, ...)

# S3 method for class 'lsqregression'
predict(object, se.fit = FALSE, ..., tau = NULL)

# S3 method for class 'formula'
nplsqreg(bws, data = NULL, newdata = NULL, tau = 0.5,
       gradients = FALSE, residuals = FALSE, subset, na.action,
       gradient.order = 1L, se = FALSE, ...)

# S3 method for class 'lsqregressionbandwidth'
nplsqreg(bws, txdat = NULL, tydat = NULL,
       tau = bws$tau, se = FALSE, ...)

# Default S3 method
nplsqreg(bws,
       txdat = stop("training data 'txdat' missing"),
       tydat = stop("training data 'tydat' missing"),
       tau = 0.5,
       exdat,
       gradients = FALSE,
       residuals = FALSE,
       gradient.order = 1L,
       se = FALSE,
       ...)

Arguments

object: a fitted lsqregression object.
se.fit: logical; whether prediction standard errors are returned. Defaults to FALSE.

Data, Bandwidth Inputs And Formula Interface

These arguments identify the bandwidth specification, formula/data interface, and training data.

bws

a formula, an lsqregressionbandwidth object returned by nplsqregbw, an rbandwidth object, a numeric bandwidth vector, or omitted for automatic bandwidth selection. Exact nplsqreg reuse is through the fitted object's $bws component; $reg.bws is internal regression state. A formula-based rbandwidth retains its training sample and bandwidth specification; supplying data explicitly replaces the training sample. With bandwidth.compute = FALSE, its bandwidths are held fixed in the quantile fit.

data

This argument belongs to the formula interface (including supported formula-bearing bandwidth-object refits). Native calls must supply their vectors, matrices or data frames directly, or use with(data, ...). Supplying data, including explicit data = NULL, to a native route that does not consume it is an error; see np-data-interfaces.

an optional data frame, list or environment containing the variables in the model. If not found in data, the variables are taken from environment(bws).

subset

an optional vector specifying a subset of observations to be used by the formula method. When using a formula-based regression bandwidth object as a starting bandwidth, a row-changing subset requires explicit data; NULL and TRUE reuse all retained rows. A stored LSQ bandwidth object cannot be resubsetted; rebuild it with nplsqregbw() for another training sample.

na.action

a function specifying the action to take when missing values are found by the formula method.

txdat

a $p$-variate data frame of explanatory data used as training data. Defaults to the training data stored in bws.

tydat

a one dimensional numeric vector of dependent data. Defaults to the training response stored in bws.

Evaluation Data And Returned Quantities

These arguments control where the quantile regression is evaluated and which fitted quantities are returned.

newdata: an optional data frame in which to look for evaluation covariates for formula fits. If omitted, the training data are used.
exdat: a $p$-variate data frame of evaluation points. By default, evaluation takes place on txdat. The native exdat argument takes precedence over newdata when both are supplied.
gradients: a logical value indicating whether gradients and categorical effects of the conditional quantile with respect to the conditioning variables should be computed and returned. Defaults to FALSE.
se: a logical value indicating whether asymptotic standard errors should be computed and retained. Defaults to FALSE. Request se=TRUE when se() or gradient standard errors will be used.
gradient.order: for a final regtype="lp" fit with gradients=TRUE, a positive integer scalar or one positive integer per continuous predictor. Each entry requests that coordinate's derivative order; it does not request mixed partial derivatives. The default is the first derivative. Ordered and unordered predictors retain their existing first-difference effect semantics.
residuals: a logical value indicating whether residuals should be returned for training-data fits. Defaults to FALSE.

Quantile Index And Additional Controls

These arguments control the requested quantile probability and the bandwidth selection, prediction, or plotting route.

tau: a numeric scalar or vector specifying the quantile probability or probabilities $\tau$. Values must lie strictly in $(0,1)$. For predict(), omit tau or use NULL to predict all stored quantiles. Otherwise supply distinct, exactly matching stored values in the desired order. Unfitted values are an error; prediction does not select bandwidths or recalibrate a new quantile.
...: additional arguments supplied to nplsqregbw when bandwidths are computed internally, to npreg for the final transformed-response fit, or to plotting and prediction methods as appropriate. Common bandwidth-selection controls include regtype, bwtype, nmulti, degree, nomad, search.engine, tau.search, delta, scale, regtype.pilot, nomad.pilot, and pilot.args. The primary nomad control accepts FALSE, TRUE, or "auto"; AUTO uses exhaustive/cell degree search with one continuous smoothing dimension and NOMAD/Powell with two or more.

Details

The tau prediction argument must be named. Selecting one stored quantile returns the ordinary scalar prediction vector (or the scalar prediction list when se.fit = TRUE). Selecting several returns prediction and standard-error matrices with columns in the requested order, preserving the stored quantile labels and aligning residual.scale. Omitting tau, or supplying NULL, preserves the fitted object's original scalar or matrix output shape.

Prediction with se.fit = TRUE reports known training mean squared error in residual.scale, retaining MSE units, or NA when training provenance is unavailable. Evaluation outcomes do not replace this training score. No additional fit is performed to recover it. This score concerns the regression on the transformed quantile response. For vector tau, residual.scale is a named vector with one training MSE for each requested quantile, matching the prediction columns.

A stored lsqregressionbandwidth object retains its training sample, pilots and transformed response. Replacement data, a row-changing subset, or a new na.action is an error: use nplsqregbw() to construct bandwidth state on the new sample. Use newdata or exdat for prediction instead.

Formula fits retain trained terms and prediction expressions, so data-dependent transformations are reused for newdata rather than recalculated on each prediction grid. The same terms are retained by the scalar children of vector-tau fits. Native exdat already contains model coordinates and is not transformed again. An unnamed evaluation argument in ... follows newdata for formula predictions and exdat for native predictions; name se.fit explicitly when using this positional form. Older saved objects without trained terms retain their formula-based fallback.

Omitted training rows are restored as NA in fitted values and residuals, including fits obtained from a retained bandwidth object and multiple quantile probabilities. Prediction restores omitted evaluation rows in both estimates and standard errors. Explicit training inputs own their row positions; a complete-case replacement is not padded using an older bandwidth object's omissions.

For native (non-formula) objects, named newdata columns are matched to the retained variable names and reordered as needed. Extra columns are ignored; missing, duplicate or ambiguous names are errors. An unnamed matrix or vector remains positional for a single evaluation role. Explicit native evaluation arguments retain their positional contract and take precedence over newdata.

Formula variables of class ts, including lagged variables, are aligned on their common time support before fitting. Other variables must already have the length of that intersection. Supply explicitly aligned rows when using native data arguments instead of a formula.

The estimator follows the locally weighted quantile-kernel approach of Racine and Li (2017). Given a conditional scale pilot $\hat\sigma(X_i)$, define $$ Y_i^\delta = Y_i + \hat\sigma(X_i)\Phi^{-1}(\delta), $$ where $0 < \delta < 1$ and $\Phi^{-1}$ is the standard normal quantile function. For a requested quantile probability $\tau$, nplsqregbw selects the bandwidths and $\delta$ by leave-one-out check-loss cross-validation. With the selected bandwidths and $\delta$, nplsqreg then fits a kernel regression of $Y_i^\delta$ on $X_i$ using the ordinary mixed-data machinery in npreg. The fitted mean of the transformed response is the estimated conditional quantile.

The scale pilot is interpreted as a conditional standard deviation. The default pilot estimates the conditional mean, smooths squared residuals, floors the fitted variance before taking square roots, and then uses the resulting positive scale vector in the quantile-kernel transformation. The local-linear residual-variance pilot follows the idea of Fan and Yao (1998); regtype.pilot can be used to select the pilot regression type independently of the final quantile fit.

If tau has length greater than one, tau.search="full" performs a separate bandwidth/$\delta$ search for each quantile while sharing the same pilot scale. The explicit tau.search="refined" route fits the central quantile first and warm-starts the remaining quantiles, recording the search order and warm-start provenance in the returned object. The conservative default is tau.search="full".

Gradients and categorical effects are those returned by the final npreg fit on the transformed response. Thus ordered-factor effects are finite-difference contrasts and unordered-factor effects follow the corresponding mixed-data regression semantics. For a local-polynomial fit, gradient.order is applied coordinate by coordinate to continuous predictors. Availability follows npreg: Apart from the established all-degree-zero first-derivative compatibility route, components whose order exceeds their fitted polynomial degree are returned as NA with a warning whenever another continuous derivative or categorical first-difference effect is available; plots retain those components as empty panels. A request with no available component is rejected. No mixed partials, Hessians, derivative tensors, or multiple derivative orders are stored. With vector tau, the existing evaluation-by-coordinate-by-tau array layout is retained. The gradients method extracts exactly the stored order and rejects any different requested order; it does not recompute derivatives after fitting.

A scalar quantile can be displayed as a surface by explicitly supplying perspective=TRUE when there are two continuous or numeric-labelled ordered conditioning variables. Omitting perspective, or supplying perspective=FALSE, retains the usual slice layout. Vector quantiles and gradient plots also retain their slice layout. Surface uncertainty is calibrated over the complete displayed grid for that one tau. Both the base renderer and renderer="rgl", view="fixed" support level surfaces and their interval meshes. Returned evaluation rows retain the trained predictor names and ordered-factor support; numeric axis coordinates are used only for drawing. The data overlay can be disabled with data.overlay=FALSE.

Asymptotic plot(..., band="simultaneous") and band="all" use the accepted local regression response maps for each fitted transformed-response curve. Level, continuous-derivative and paired categorical-effect factors retain common observation columns, the selected local-constant or local-polynomial specification, and the actual native moment/ridge convention. Residual normalization uses the training fit map; reconstruction checks reject numerically unidentifiable maps instead of changing the fitted estimator. The fixed-regression fitting and bandwidth selection algorithms are unchanged.

Calibration is over the retained finite grid within one panel and one tau; it is not joint over taus or panels. gaussian.draws controls the Gaussian maximum simulation, and random.seed preserves reproducibility without changing the caller's RNG state. These are variability bands under the frozen transformation convention below; they do not add uncertainty from transformation selection or remove smoothing bias, and do not cover points between the declared grid. Coverage requires a valid joint Gaussian approximation and consistent local marginal scales; arbitrary growing or data-dependent grids do not carry a uniform-coverage guarantee. Unavailable marginal errors, unidentified influences or resource limits produce a specific unavailable joint-band notice.

Standard errors are the asymptotic standard errors from that final transformed-response regression, conditional on the selected bandwidths, pilot scale, and $\delta$. They inherit the residual normalization described under Standard Errors in npreg (Ruppert et al., 1997), applied to the transformed response. This does not add uncertainty from estimating the pilot scale or transformation. Local-polynomial fits inherit the numerical-ridging policy documented there. For vector tau, quantiles are fitted separately, so estimated quantile curves are not monotonized and may cross in finite samples. Separate fits on the same observations do not imply zero cross-quantile sampling covariance.

Value

nplsqreg returns an object of class lsqregression. The generic functions fitted, quantile, se, predict, residuals, and gradients extract estimated conditional quantiles, asymptotic standard errors from the transformed-response regression, predictions, residuals when requested, and gradients or categorical effects. The functions summary, print, and plot support objects of this type. Local-polynomial fit objects retain the compact continuous-coordinate derivative order in $gradient.order.

References

Fan, J. and Q. Yao (1998), “Efficient Estimation of Conditional Variance Functions in Stochastic Regression,” Biometrika, 85, 645-660. doi:10.1093/biomet/85.3.645

Racine, J.S. and K. Li (2017), “Nonparametric conditional quantile estimation: A locally weighted quantile kernel approach,” Journal of Econometrics, 201, 72-94. doi:10.1016/j.jeconom.2017.06.020

Racine, J.S. and I. Van Keilegom (2020), “A smooth nonparametric, multivariate, mixed-data location-scale test,” Journal of Business & Economic Statistics, 38, 784-795. doi:10.1080/07350015.2019.1574227

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.

For formula fits, character-valued missing-data policies are resolved through the stats model-frame owner; pass a caller-local policy as a function object rather than its name. With replacement training data, an explicit na.action, including NULL, takes precedence over the saved policy. Native fitting still requires complete rows, so a permissive policy does not guarantee the same retained sample as stats::model.frame.

When converting a formula-based rbandwidth without replacement data, an explicitly supplied scale vector must follow the retained complete training sample in its stored order. With replacement data, scale follows the formula's ordinary subset and missing-data handling.

When reusing a bandwidth object without explicit training or evaluation data, newly constructed bandwidth objects use retained training values. A fit with explicit replacement training data retains that sample in its returned bandwidth object; evaluation grids do not replace training data. Older objects without retained samples use their stored call environment when available and may require explicit training inputs after saveRDS() and readRDS(). Custom formula transformations used on new evaluation data must still be available.

Examples

if (FALSE) { # \dontrun{
data("Italy")

model.q <- nplsqreg(gdp ~ ordered(year), data = Italy,
                    tau = c(0.25, 0.50, 0.75))
plot(model.q)

model.med <- nplsqreg(gdp ~ ordered(year), data = Italy, tau = 0.50)
model.q2 <- nplsqreg(bws = model.med$bws, tau = 0.50)
plot(model.med, gradient = TRUE)
} # }