Nonparametric Regression Hat Operator

Constructs nonparametric regression hat operators for npreg-compatible bandwidth objects. The returned operator \(H^{(s)}\) maps responses to fitted values or derivative estimates via \(H^{(s)} y\).

Usage

npreghat(bws, ...)

# S3 method for class 'formula'
npreghat(bws, 
         data = NULL, 
         newdata = NULL, 
         ...)

# S3 method for class 'rbandwidth'
npreghat(bws,
         txdat = stop("training data 'txdat' missing"),
         exdat, y = NULL,
         output = c("matrix", "apply", "constraint"),
         basis = NULL,
         bernstein.basis = NULL,
         degree = NULL,
         deriv = NULL,
         leave.one.out = FALSE,
         ridge = 0,
         s = NULL, 
         ...)

# S3 method for class 'npregression'
npreghat(bws, 
         txdat, 
         y, 
         ...)

# S3 method for class 'npreghat'
predict(object, 
        newdata = NULL, y = NULL,
        output = c("matrix", "apply", "constraint"),
        s = attr(object, "s"),
        leave.one.out = attr(object, "leave.one.out"),
        deriv = NULL, 
        ...)

Arguments

Data, Bandwidth Inputs And Formula Interface

These arguments identify the fitted bandwidth object, formula/data interface, training data, and evaluation data.

bws

An object of class rbandwidth or npregression.

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. A data frame used with the formula interface.

exdat

Optional evaluation predictors.

newdata

Optional evaluation data for formula and predict methods. Without a new evaluation grid, prediction retains the operator's original training-observation or external-query identity, including when changing the derivative order. An explicit grid remains external even when its coordinates equal the training data; this distinction can affect nearest-neighbor radii. Formula newdata is evaluated with the trained predictor transformations. Explicit native exdat takes precedence over newdata and is already in the transformed predictor coordinates. Retained operators carry their effective polynomial specification, including construction-time degree, basis and Bernstein overrides.

txdat

Training predictors.

Local-Polynomial Controls

These arguments control local-polynomial basis, degree, derivatives, leave-one-out behavior, and ridge stabilization.

basis

Local polynomial basis: "glp", "additive", or "tensor".

bernstein.basis

Logical; select the stabilized LP representation. For GLP, TRUE selects the degree-graded, orthonormal shifted-Legendre representation; additive and tensor bases retain their Bernstein representations. See npreg for the definitions.

degree

Optional local polynomial degree vector override (LP path).

deriv

Convenience alias for s.

leave.one.out

Logical; if TRUE, compute in-sample leave-one-out hat weights. This cannot be combined with explicit exdat/newdata. Local-constant first-derivative weights with leave.one.out = TRUE are not currently supported; local-constant level weights and the supported local-polynomial leave-one-out derivatives remain available.

ridge

A finite nonnegative scalar. The default 0 retains the existing automatic numerical ridging policy. Computational owners that implement only that policy reject an explicit nonzero value rather than ignoring it; the generic mixed-derivative owner continues to support an explicit base ridge, with absolute increments 1/n.train on that explicit-ridge route. Default higher and mixed derivatives instead share the canonical LP solve-admission and automatic ridge policy used by fitting. Wider systems restore the response intercept from the signed pristine Gram intercept.

s

Derivative multi-index over continuous predictors, with finite non-negative integer entries. A named vector selects predictors by their continuous-variable names; omitted coordinates have order zero. An unnamed scalar selects the first continuous predictor. Unknown or duplicated names are errors. Explicit s takes precedence over the deriv alias; an explicit deriv in prediction overrides the retained selector.

Method Objects

This argument identifies a fitted hat-operator object supplied to an S3 method.

object

An object returned by npreghat.

Operator Output

These arguments control whether the operator is returned as a matrix, applied directly, or returned as a quadratic-programming constraint design matrix.

output

Either "matrix" for the hat matrix, "apply" for direct application to y, or "constraint" for the row-weighted transpose t(H) * y.

y

Optional response vector or matrix for apply mode. For output = "constraint", y is required and must be a vector or one-column object. When the fitted response is a factor, explicit or borrowed factor responses use its retained numerical level coding, including numeric level labels. Payload levels are aligned to the fitted levels. Explicit numerical vectors or matrices are applied as supplied, without recoding.

Additional Arguments

Further arguments are passed to methods.

...

Additional arguments passed to methods.

Details

With a formula-derived bandwidth object, supplying only y replaces the evaluated response in retained-training-sample order: one row per observation retained after the original subset and missing-value selection. Original excluded rows are not restored; row names or equal lengths do not imply original-data order. The effective na.action is then applied jointly to the retained predictors and replacement response; any new omission indices refer to this retained sample. The selected bandwidths remain fixed, and the returned object retains the replacement sample for subsequent refits. Use data for full formula-data replacement, not together with a partial response replacement. Explicit native training arguments retain their separate positional contract.

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

Local-polynomial operators retain the fitted solve's numerical ridge adjustment; see Numerical Ridging in npreg and its Seifert–Gasser reference. A hat operator alone does not estimate residual variance or apply the residual normalization used by regression inference. Fewer nonzero-weight donor rows than basis coefficients trigger the same existing ridge policy as fitting, for levels and derivative operators. This is a structural rank bound, not a new numerical conditioning threshold.

For output = "matrix", the return value is a matrix with class c("npreghat", "matrix") so it can be used directly in matrix products, e.g. H %*% y. Attributes on the matrix store metadata used by predict.npreghat.

For output = "apply", the function returns H^{(s)} y directly and accepts matrix right-hand sides for one-shot bootstrap-style calculations.

An evaluation row whose required kernel normalization is exactly zero or non-finite is returned as an NA hat row. Defined rows remain available, and every finite nonzero normalization is used literally.

For non-beta local-polynomial mean operators with fixed or generalized nearest-neighbor bandwidths, a failed external evaluation row is returned as NA only when its pristine moment system is finite and every computed kernel weight is exactly zero. One warning identifies the affected result rows (after missing evaluation rows are omitted). This reports the computed weights; it does not distinguish absence of geometric support from numerical underflow. Defined rows retain their ordinary values. In matrix output, the corresponding ridge.used entries are NA; apply output has undefined rows, and constraint output has the corresponding undefined columns. Other solve failures and zero nearest-neighbor radii remain errors. Training, leave-one-out and internal complete-operator consumers retain strict failure behavior.

The same all-zero-weight certificate is used for external non-beta local-constant (including degree-zero local-polynomial) first-derivative operators with fixed, generalized-nearest-neighbor or adaptive-nearest-neighbor bandwidths. Unsupported rows become NA, while supported derivative rows keep their usual values. A zero sum formed by cancellation of nonzero weights, non-finite arithmetic, and invalid nearest-neighbor radii remain errors; they are not classified as empty rows.

Default higher and mixed local-polynomial derivative operators also use the finite-pristine-system, all-zero-weight certificate for external rows. Their ridge.used entries are then NA, with the same warning and output shapes described above. An explicit positive ridge retains its requested regularized operator; it is not replaced by automatic ridging or this default unavailable-row policy.

For local-constant beta kernels, one first derivative is evaluated by the same analytic C kernel used by npreg(..., gradients=TRUE). If an exact support endpoint creates a raw-kernel jump, the hat operator cannot know whether a future response will cancel it in the normalized ratio; the entire affected row is therefore returned as NA with a warning. The compiled estimator route can still return a finite response-specific gradient.

For output = "constraint", the function returns t(H^{(s)}) * y, the row-weighted transpose commonly used as the design matrix in shape-constrained quadratic-programming examples. This is a convenience route that is exactly equivalent to obtaining H with output = "matrix" and then computing t(H) * y; it does not solve a constrained estimation problem.

Value

Either a hat matrix (class "npreghat") or the applied result H^{(s)} y, or the constraint design matrix t(H^{(s)}) * y, depending on output.

Examples

if (FALSE) { # \dontrun{
data(cps71)
bw <- npregbw(xdat = cps71$age, ydat = cps71$logwage,
              regtype = "ll", bandwidth.compute = FALSE, bws = 1.0)
H <- npreghat(bws = bw, txdat = data.frame(age = cps71$age))
H.fitted <- H 
A <- npreghat(bws = bw, txdat = data.frame(age = cps71$age),
              y = cps71$logwage, output = "constraint")
all.equal(A, t(H) * cps71$logwage)
ghat <- npreg(bws = bw)
head(cbind(fitted(ghat), H.fitted), n = 2L)
} # }