Semiparametric Models

Practical route to partially linear, single-index, and varying-coefficient models in np.
Keywords

npplreg, npindex, npscoef, semiparametric models, partially linear, single index

Semiparametric models combine a finite-dimensional parameter with an unknown function. The three principal np families differ in where that structure is placed:

If you want a minimal downloadable script for the semiparametric route, start with np_semiparametric_quickstart.R.

LP-capable semiparametric families support joint degree-bandwidth search through nomad = "auto". For example:

## Simulate a small partially linear example, then use the automatic LP shortcut.
## nomad = "auto" uses exhaustive search for p = 1 and NOMAD otherwise.
library(np)

set.seed(42)
n <- 200
x1 <- rnorm(n)
z <- runif(n)
y <- 1 + 2 * x1 + sin(2 * pi * z) + rnorm(n, sd = 0.2)
dat <- data.frame(y, x1, z)

fit_pl_lp <- npplreg(y ~ x1 | z, data = dat, nomad = "auto", degree.max = 2L, nmulti = 1)

The same shortcut is available for supported npindex() and npscoef() routes. It requires crs, which supplies the NOMAD runtime; "auto" uses exhaustive search when there is one degree coordinate and NOMAD otherwise.

Use a semiparametric model when scientific structure supports one of these restrictions and the remaining component should stay nonparametric.

Partially linear models: npplreg

The partially linear model keeps the effect of \(X\) linear while estimating \(g(z)\) nonparametrically.

In the wage1 example, the idea is to treat some regressors parametrically while allowing experience to enter nonparametrically.

## Keep some regressors linear while letting experience vary nonparametrically
library(np)
data(wage1, package = "np")

model_pl <- npplreg(lwage ~ female + married + educ + tenure | exper, data = wage1)

summary(model_pl)

Bandwidth selection for a partially linear model may be costly because its criterion evaluates several cross-validated regressions.

npplreg() defaults to se = FALSE. Request se = TRUE when you need coef(model, se = TRUE) or vcov(model); the retained coefficient covariance allows conditional heteroskedasticity. Prediction errors and asymptotic plots request their required uncertainty separately.

Single-index models: npindex

Single-index models reduce the nonparametric dimension from \(x\) to the scalar index \(x^\mathsf{T}\beta\).

Two important routes are available in np:

  • Klein-Spady style models for binary outcomes,
  • Ichimura style models for continuous outcomes.

Binary outcomes

## Fit a binary single-index model on the mixed-data birthwt example
library(np)
data(birthwt, package = "MASS")

## Klein-Spady requires a numeric 0/1 response; predictors may be factors.
birthwt$smoke <- factor(birthwt$smoke)
birthwt$race <- factor(birthwt$race)
birthwt$ht <- factor(birthwt$ht)
birthwt$ui <- factor(birthwt$ui)
birthwt$ftv <- factor(birthwt$ftv)

model_index_binary <- npindex(low ~ smoke + race + ht + ui + ftv + age + lwt,
  method = "kleinspady",
  gradients = TRUE,
  data = birthwt)

summary(model_index_binary)

Current np and npRmpi releases retain the R model-matrix contrasts used for factor predictors, so fitting, prediction, gradients, and plots share the same single-index design. The Klein–Spady response itself must remain numeric 0/1; a factor response is rejected rather than silently interpreted through its internal codes.

Continuous outcomes

## Use the continuous-outcome single-index route on wage data
library(np)
data(wage1, package = "np")

model_index_continuous <- npindex(lwage ~ female + married + educ + exper + tenure,
  data = wage1,
  nmulti = 1)

summary(model_index_continuous)

The single-index restriction reduces the dimension of the unknown link while retaining a nonparametric response to the index.

Interpreting and tuning the single index

npindex() is the one principal estimator that defaults to se = TRUE, se.type = "asymptotic", providing asymptotic coefficient covariance and fitted-value standard errors. Set se = FALSE for a point-only fit when that extra work is not needed. Selecting se.type = "bootstrap" uses B for fitted-value, gradient, and average-gradient errors; coefficient covariance remains asymptotic in either mode.

With a local-constant uniform kernel, the link derivative is zero and cannot provide covariance for free index coefficients. Use se = FALSE when only the point estimate is required for that configuration.

The Ichimura and Klein-Spady objectives reuse the established npreg leave-one-out backend where appropriate, and npRmpi distributes post-CV fit, evaluation, and gradient work across evaluation rows. Fixed-bandwidth restarts, nearest-neighbour metadata, objective certification, and retained formula data are tightly validated.

Klein–Spady coefficient uncertainty conditionally centers the covariates on the fitted index, so reported covariance is no longer sensitive to arbitrary translations of the predictors. Coefficient-only refits retain the fitted degree and bandwidth, avoiding another automatic degree or bandwidth search.

The coefficient vector is identified only up to scale, so npindexbw() normalizes its first coefficient to one. Read the remaining coefficients as relative movements in the index, not as standalone linear-model slopes, and choose the first continuous regressor deliberately when coefficient interpretation matters.

The default optim.method = "Nelder-Mead" remains a robust derivative-free starting point for a low-dimensional search. For a higher-dimensional index, optim.method = "BFGS" can be a useful performance and sensitivity comparison. Because the objective can be nonconvex, compare objective values, convergence behavior, and fitted objects rather than selecting an optimizer by runtime alone.

Varying coefficient models: npscoef

A varying-coefficient model lets each coefficient \(\beta_j(z)\) change with the conditioning variable \(z\).

In the wage1 illustration, coefficients are allowed to vary with sex.

## Create numeric coefficient variables, then let them vary with sex
library(np)
data(wage1, package = "np")

wage1_augmented <- wage1
wage1_augmented$dfemale <- as.integer(wage1$female == "Male")
wage1_augmented$dmarried <- as.integer(wage1$married == "Notmarried")

model_scoef <- npscoef(lwage ~ dfemale + dmarried + educ + exper + tenure | female,
  betas = TRUE,
  data = wage1_augmented)

summary(model_scoef)

One practical detail matters: the X variables in the varying-coefficient part need to be numeric, so creating explicit 0/1 versions of factors can be appropriate there.

Instrumental regression

The proof-of-concept npregiv() and npregivderiv() estimators now support explicit formula/data interfaces. Use y ~ z | w for a response, endogenous regressor, and instrument; npregiv() also supports y ~ z | w | x when separate exogenous covariates are present. The returned objects have dedicated summary, fitted-value, residual, gradient, and plot methods. Evaluation grids are supplied during fitting rather than through post-fit prediction, and the current IV estimators support fixed rather than nearest-neighbour bandwidths.

Start with the instrumental-regression quickstart.

Hat and operator helpers

The public helper family now follows the estimator family directly: npreghat, npindexhat, npplreghat, and npscoefhat cover regression and semiparametric fits, while npudenshat, npudisthat, npcdenshat, and npcdisthat cover density and distribution objects. These helpers can return an explicit matrix, apply the operator without asking users to reconstruct it, or produce the transposed response-weighted output = "constraint" form used in constrained estimation.

npreghat() uses the canonical local-polynomial rank and bounded-ridge policy shared by the hat, fit, objective, and bootstrap routes. Generalized-nearest- neighbor and local-constant derivative ownership is validated explicitly. For mixed polynomial degrees, available derivative components are routed through the correct operator and unavailable components are reported explicitly rather than silently applying a different derivative.

The constrained local-polynomial scripts in the Code Catalog show the practical npreghat() workflow.

How should I choose among these?

If you want… Start with
A mostly linear model with one clearly nonlinear part npplreg
Dimension reduction through an unknown index npindex
Coefficients that vary with another variable npscoef
Maximum flexibility with fewer structural assumptions npreg
Back to top