Fit a Local-Likelihood Density or Bernoulli Smoother — fit.local.likelihood • geosmooth

Fits a local likelihood model at each evaluation point and reads off one raw fitted value at that evaluation anchor. Density and Bernoulli workflows should convert the returned fitted field with normalize.density when the target is a subject-occupation density.

Usage

fit.local.likelihood(
  X,
  y,
  X.eval = NULL,
  likelihood.family = c("density", "bernoulli"),
  support.size = min(15L, nrow(X)),
  degree = 1L,
  kernel = c("gaussian", "tricube", "epanechnikov", "triangular"),
  bandwidth.multiplier = 1,
  support.grid = NULL,
  degree.grid = NULL,
  kernel.grid = NULL,
  bandwidth.multiplier.grid = NULL,
  lambda.ridge.grid = NULL,
  foldid = NULL,
  cv.folds = 5L,
  cv.seed = 1L,
  coordinate.method = c("coordinates", "local.pca"),
  chart.dim = NULL,
  chart.dim.grid = NULL,
  selection.strategy = c("grid", "sparse_kd", "plateau_kd"),
  chart.dim.max = NULL,
  design.margin = 2L,
  auto.chart.support.metric = c("coordinates", "operator", "both"),
  auto.chart.selection.metric = c("coordinates", "operator"),
  quadrature.weights = NULL,
  lambda.ridge = 1e-08,
  min.local.mass = sqrt(.Machine$double.eps),
  min.nonzero.mass = 1L,
  fallback = c("degree0", "zero", "chart_kernel", "na"),
  optimizer = c("newton", "optim"),
  max.iter = 50L,
  tol = 1e-08,
  return.details = TRUE
)

Arguments

X: Numeric matrix with one row per source/support point.
y: Numeric response vector. For likelihood.family = "density", this must be a nonnegative mass/intensity vector with positive total mass. For "bernoulli", values must lie in [0, 1].
X.eval: Optional numeric matrix of evaluation points. Defaults to X.
likelihood.family: Local likelihood family.
support.size: Number of source points in each local support.
degree: Local chart feature degree. Supported values are 0, 1, and 2. The density branch omits an intercept because the intercept is not identifiable in the normalized local density likelihood. The Bernoulli branch includes an intercept in its internal logistic feature map.
kernel: Kernel name. Supported values are "gaussian", "tricube", "epanechnikov", and "triangular".
bandwidth.multiplier: Positive multiplier applied to the local support radius.
support.grid: Optional integer candidate neighborhood sizes for cross-validation. CV selection is currently implemented for likelihood.family = "bernoulli".
degree.grid: Optional local polynomial degree candidates for Bernoulli cross-validation.
kernel.grid: Optional kernel candidates for Bernoulli cross-validation.
bandwidth.multiplier.grid: Optional bandwidth-multiplier candidates for Bernoulli cross-validation.
lambda.ridge.grid: Optional ridge-penalty candidates for Bernoulli cross-validation.
foldid: Optional positive integer vector assigning source rows to cross-validation folds.
cv.folds: Number of folds used when foldid is not supplied.
cv.seed: Random seed used to generate folds when foldid is not supplied.
coordinate.method: Local coordinate method. "coordinates" uses centered ambient coordinates. "local.pca" projects centered support points onto a local PCA basis.
chart.dim: Local PCA dimension when coordinate.method = "local.pca". If NULL, the dimension is min(ncol(X), support.size - 1). The deployable input-only policies "auto" and "local.auto" use the same local-PCA dimension diagnostics as fit.lps; "auto" resolves one global chart dimension, while "local.auto" resolves one dimension per evaluation anchor.
chart.dim.grid: Optional candidate chart dimensions for experimental cross-validation. Numeric grids can be evaluated with selection.strategy = "sparse_kd".
selection.strategy: Candidate-selection strategy. "grid" evaluates the requested candidate grid. "sparse_kd" evaluates a sparse support-size by chart-dimension skeleton when chart.dim.grid is supplied. "plateau_kd" uses the same geometry-only support-size and chart-dimension plateau rule as fit.lps.
chart.dim.max: Optional explicit maximum chart dimension for the sparse coupled candidate family.
design.margin: Nonnegative integer feasibility margin used to screen local polynomial design size before candidate evaluation.
auto.chart.support.metric: Support system used by chart.dim = "auto" or "local.auto". Local-likelihood smoothers currently use coordinate supports for both coordinate and operator diagnostics.
auto.chart.selection.metric: Which auto chart-dimension diagnostic to use when both coordinate and operator summaries are requested.
quadrature.weights: Optional positive reference-measure weights. Defaults to unit weights.
lambda.ridge: Nonnegative ridge penalty on identifiable coefficients.
min.local.mass: Minimum local kernel-weighted mass needed before attempting a higher-degree density fit. For Bernoulli fits this is used only as diagnostic telemetry.
min.nonzero.mass: Minimum number of locally weighted positive-mass source points needed before attempting a higher-degree local fit.
fallback: Fallback policy for underidentified or failed higher-degree local fits. Zero local mass always uses "zero".
optimizer: Optimizer for nonzero-degree density fits. "newton" is implemented; "optim" is accepted and delegates to BFGS.
max.iter: Maximum optimizer iterations.
tol: Convergence tolerance for gradient norm and step norm.
return.details: Logical; if TRUE, keep per-evaluation diagnostics.

Value

A list with class "local_likelihood" containing fitted.values, selected controls, and local solver diagnostics.

Details

The likelihood.family = "density" branch uses a local exponential tilt of the chart reference measure. The "bernoulli" branch uses a weighted local logistic likelihood and returns fitted probabilities at the evaluation anchors.

Examples

X <- matrix(seq(0, 1, length.out = 21), ncol = 1)
y <- exp(-20 * (X[, 1] - 0.5)^2)
y <- y / sum(y)
fit.local.likelihood(X, y, likelihood.family = "density",
                     support.size = 7L, degree = 0L)
#> Local likelihood 
#>   Training rows: 21 ; evaluation rows: 21 ; responses: 1 
#>   Observed responses: 21 ; nonfinite fitted entries: 0 
#>   Output: finite output 
#>   Convergence: unavailable (no stored stopping certificate) 
#>   Selected: support.size=7, degree=0, kernel=gaussian, lambda.ridge=1e-08,
#>     likelihood.family=density, cv.rmse.observed=NA, cv.brier.observed=NA,
#>     cv.logloss.observed=NA 
#>   Local fallbacks: 0 
#>   Local status: ok=21 
#>   Prediction scope: stored evaluation rows; supply X.eval when fitting