Fit Subject-Occupation Density — fit.subject.od • geosmooth

Convenience wrapper that converts subject visit indices into a density input. Density-native methods dispatch to fit.density. LPS/PS-LPS methods fit ordinary smoother objects first and then call normalize.density; they are subject-occupation workflows, not standalone density-native methods.

Usage

fit.subject.od(
  X,
  subject.index,
  method = c("empirical", "graph_random_walk", "lps_count", "ps_lps_count",
    "lps_logistic_binary", "chart_kernel", "local_likelihood_density",
    "local_likelihood_bernoulli"),
  graph = NULL,
  graph.control = list(),
  od.control = list(),
  return.details = TRUE,
  od.cv = c("none", "visit"),
  visit.foldid = NULL,
  visit.cv.folds = 5L,
  visit.cv.seed = 1L,
  visit.cv.epsilon = 1e-15,
  ...
)

Arguments

X: Numeric matrix with one row per support point.
subject.index: Integer row indices of subject visits in X. Repeated indices are allowed.
method: Density method identifier.
graph: Optional precomputed graph object.
graph.control: Named list for random walks: walk.steps (or walk.step), affinity.method, affinity.scale, affinity.epsilon, and logical normalize. Underscore aliases are accepted, but conflicting aliases and unknown names are rejected. Must be empty for the empirical estimator.
od.control: OD-facing alias for density.control.
return.details: Logical; if TRUE, keep diagnostic details in the result.
od.cv: OD-level selection mode. "none" preserves the direct fit. "visit" holds out subject visits, fits candidates on the remaining visits, and selects the candidate minimizing held-out negative log occupation mass.
visit.foldid: Optional positive integer vector assigning subject visits to OD-level cross-validation folds. Its length must equal length(subject.index).
visit.cv.folds: Number of visit folds when visit.foldid is not supplied.
visit.cv.seed: Random seed for generated visit folds.
visit.cv.epsilon: Positive floor used in held-out -log(rho[visit]) scoring.
...: Reserved for future methods; unused arguments are errors.

Value

A list of class "density_fit". Its rho component is the estimated probability mass over the rows of X, and empirical.rho is the normalized visit-count mass. The subject component summarizes the number of visits, the number of distinct visited support points, the largest visit multiplicity, and the fraction of repeatedly visited support points. Other components describe the fitted method, normalization accounting, smoothing diagnostics, and warnings as documented in fit.density. With od.cv = "visit" and return.details = TRUE, the result also contains the visit-level cross-validation table, fold assignments, and held-out predicted masses.

Details

The "lps_logistic_binary" method name is historical. In the current OD workflow it calls fit.lps(..., outcome.family = "bernoulli"), which fits a clipped probability field with the LPS least-squares core and then converts that field to a density with normalize.density. It is not the outcome.family = "binomial" local-logistic IRLS path.

When od.cv = "visit", graph random-walk candidates may pass OD-level grids inside graph.control: walk.step.grid, affinity.method.grid, affinity.scale.grid, affinity.epsilon.grid, and normalize.grid. Missing affinity.scale values mean the usual data-derived affinity scale.

When od.cv = "visit", chart-based and LPS-family methods may pass chart.dim.grid through .... For "chart_kernel", "local_likelihood_density", "local_likelihood_bernoulli", "lps_count", "lps_logistic_binary", and "ps_lps_count", this grid compares fixed integer chart dimensions with optional "auto" and "local.auto" chart-dimension policies under the same held-out-visit negative-log-occupation score. For LPS-family OD visit CV, each outer candidate is passed to the source smoother as a scalar local model configuration; this avoids nested row-level multi-candidate selection inside each held-out-visit fold.

Examples

X <- matrix(seq(0, 1, length.out = 6), ncol = 1)
fit.subject.od(X, subject.index = c(1L, 3L, 3L, 6L),
               method = "empirical")
#> Probability mass 
#>   Training rows: NA ; evaluation rows: 6 ; responses: 1 
#>   Observed responses: NA ; nonfinite fitted entries: 0 
#>   Output: ok 
#>   Convergence: unavailable (no stored stopping certificate) 
#>   Total mass: 1 ; positive support: 3 
#>   Accounting: mass=1e+00, min.rho=0e+00, max.rho=5e-01, raw.mass=1e+00,
#>     neg.mass=0e+00, clip.mass=0e+00, normalization.constant=1e+00,
#>     mass.tol=1e-08, neg.tol=1e-12 
#>   Prediction scope: mass on the stored support