Package {VCMoE}

VCMoE: Varying-Coefficient Mixture-of-Experts Models

Description

Fit and evaluate single-response Gaussian, Binomial, and Negative-Binomial varying-coefficient mixture-of-experts models.

Author(s)

Maintainer: Qicheng Zhao 790471666@qq.com

See Also

Useful links:

• https://qc-zhao.github.io/VCMoE/

• https://github.com/qc-zhao/VCMoE

• Report bugs at https://github.com/qc-zhao/VCMoE/issues

Extract VCMoE coefficients

Description

Extracts expert coefficients, gating coefficients, Gaussian variance intercepts, Gaussian log-sigma local-linear slopes, Negative-Binomial theta, or all fitted coefficient blocks from a VCMoE fit.

Usage

## S3 method for class 'vcmoe'
coef(object, type = c("all", "expert", "gating", "sigma", "sigma_slope", "theta"), ...)

Arguments

Details

For Gaussian fits, coef(fit, "sigma") returns the component-specific standard deviation function at each u_grid point, and coef(fit, "sigma_slope") returns the scaled local-linear slope of log(sigma) on the (u - u0) / h basis.

For Binomial fits, expert coefficients are on the logit success-probability scale and coef(fit, "sigma") returns NULL. For Negative-Binomial fits, expert coefficients are on the log mean count scale, coef(fit, "theta") returns the component-specific size parameter, and coef(fit, "sigma") returns NULL.

Value

A list or array of fitted coefficient functions.

Bootstrap confidence intervals for VCMoE coefficients

Description

Summarizes pointwise or simultaneous bootstrap intervals for expert or gating coefficient functions.

Usage

## S3 method for class 'vcmoe_bootstrap'
confint(
  object,
  parm = c("expert", "gating"),
  level = 0.95,
  type = c("pointwise", "simultaneous"),
  ...
)

Arguments

Details

Pointwise intervals are percentile intervals at each grid point. Simultaneous bands compute bootstrap standard errors and use the empirical quantile of the maximum standardized absolute deviation over the u_grid. Near-zero standard errors are floored internally to avoid division by zero.

Value

A tidy data frame with columns coefficient_set, term, component, u, estimate, se, lower, upper, type, level, and n_successful.

Plot fitted coefficient functions

Description

Plots fitted expert or gating coefficient functions over the VCMoE grid.

Usage

plot_coefficients(object, type = c("expert", "gating"))

Arguments

Value

A ggplot object.

Plot VCMoE fit diagnostics

Description

Plots convergence, posterior entropy, component proportions, effective local sample size, and label ambiguity flags over the coefficient grid.

Usage

plot_diagnostics(object)

Arguments

Details

This plot is intended as a first real-data sanity check before interpreting coefficient functions. Ambiguity or non-convergence at many grid points should be treated as evidence that the fitted component labels or coefficient paths need closer review.

Value

A ggplot object.

Plot bootstrap inference intervals

Description

Plots fitted coefficient functions with bootstrap pointwise intervals or simultaneous bands.

Usage

plot_inference(
  object,
  coefficient_set = "expert",
  type = c("pointwise", "simultaneous"),
  level = 0.95
)

Arguments

Value

A ggplot object.

Plot fitted posterior summaries

Description

Plots mean posterior probabilities for each component over the coefficient grid.

Usage

plot_posterior(object)

Arguments

Value

A ggplot object.

Predict from a VCMoE fit

Description

Returns fitted means, component-specific means, posterior probabilities, or gating probabilities.

Usage

## S3 method for class 'vcmoe'
predict(object, newdata = NULL, u = NULL,
  type = c("mean", "posterior", "component", "prior"), ...)

Arguments

Details

For Gaussian fits, type = "component" returns component-specific means and type = "mean" returns the posterior-weighted fitted mean. For Binomial fits, type = "component" returns component-specific success probabilities and type = "mean" returns the marginal success probability. For Negative-Binomial fits, type = "component" returns component-specific mean counts and type = "mean" returns the marginal mean count.

Value

A vector or matrix depending on type.

Simulate Binomial VCMoE data

Description

Generates Binomial VCMoE simulations for Bernoulli and grouped-count examples and tests.

Usage

simulate_vcmoe_binomial(n = 300L, k = 2L, seed = NULL,
  separation = 1, u = NULL, scenario = "well_separated", trials = 1L)

Arguments

Value

A list with data and truth. Expert truth is on the logit scale. The truth entry includes component coefficients, gating logits, component probabilities, component-specific success probabilities, sampled class labels, and success/failure counts.

Simulate Gaussian VCMoE data

Description

Generates a small Gaussian no-offset VCMoE simulation for tutorials and tests.

Usage

simulate_vcmoe_gaussian(n = 300L, k = 2L, seed = NULL,
  separation = 1, u = NULL, scenario = "well_separated")

Arguments

Value

A list with data and truth. The truth entry includes component coefficients, gating logits, probabilities, means, standard deviations, and sampled class labels.

Simulate Negative-Binomial VCMoE count data

Description

Generates Negative-Binomial VCMoE simulations for gene-expression count examples and tests.

Usage

simulate_vcmoe_negbin(n = 300L, k = 2L, seed = NULL,
  separation = 1, u = NULL, scenario = "well_separated",
  size_factor = NULL, mean_count = 5)

Arguments

Value

A list with data and truth. Expert truth is on the log mean count scale. The data include size_factor and log_size_factor for use with offset(log_size_factor).

Parametric bootstrap inference for a VCMoE fit

Description

Parametric bootstrap inference for a VCMoE fit

Usage

vcmoe_bootstrap(
  fit,
  data,
  u = NULL,
  B = 200L,
  coefficient_set = c("expert", "gating"),
  seed = NULL,
  control = list(),
  min_successful = max(20L, ceiling(0.5 * B)),
  keep_fits = FALSE,
  verbose = FALSE
)

Arguments

Details

Bootstrap refits preserve the reference fitting engine. A joint-path reference is therefore refitted with vcmoe_fit(..., engine = "joint_path_em") rather than silently falling back to local-grid EM.

Value

An object of class vcmoe_bootstrap.

Analytic-style confidence bands for a VCMoE fit

Description

Analytic-style confidence bands for a VCMoE fit

Usage

vcmoe_confband(
  fit,
  data = NULL,
  level = 0.95,
  type = c("pointwise", "simultaneous"),
  coefficient_set = c("expert", "gating", "sigma", "theta"),
  strict = TRUE,
  control = list()
)

Arguments

Details

For engine = "joint_path_em", the covariance follows the JASA observed local-likelihood asymptotic sandwich plug-in. It does not include shared-path, label-selection, or finite-grid cross-grid responsibility uncertainty. Joint-path convergence and the returned score-imbalance diagnostics should therefore be inspected. The returned metadata identifies the covariance target, estimator/covariance match, omitted uncertainty, and coverage-theory scope; no bias or boundary correction is applied.

Value

A vcmoe_confband object with interval and diagnostic data frames.

Summarize VCMoE fit diagnostics

Description

Returns a compact diagnostic table for reviewing whether a fitted VCMoE model is reliable enough to interpret.

Usage

vcmoe_diagnostics(object)

Arguments

Details

The table includes convergence status, iterations, local log-likelihood, local-weighted posterior entropy, label ambiguity flags, alignment margin, effective local sample size, local-weighted component posterior proportions, and Binomial expert optimizer diagnostics when available.

Posterior entropy and component proportions use the same local kernel weights as the fitted grid point when the fit retains training data. If the fit was created with control$keep_data = FALSE, component proportions fall back to unweighted posterior means and effective local sample size is NA.

Value

A data frame with one row per coefficient grid point.

Fit a varying-coefficient mixture-of-experts model

Description

Fit a varying-coefficient mixture-of-experts model

Usage

vcmoe_fit(
  formula,
  data,
  u,
  k = 2L,
  family = "gaussian",
  bandwidth = NULL,
  u_grid = NULL,
  control = list(),
  label = "align",
  parameterization = "a1_epanechnikov_scaled",
  u_scale = c("unit", "none"),
  engine = c("local_grid_em", "joint_path_em"),
  progress = NULL
)

Arguments

Details

Rows with missing or non-finite response, covariates, or u are removed consistently before fitting, with a warning. For single-trial Bernoulli responses, the default gating ridge is strengthened to control$ridge = 1 unless the user explicitly supplies control$ridge; grouped Binomial and other families keep the global default. Joint-path traces record the sample-level nearest-grid log-likelihood as a diagnostic criterion. The label-consistent updates do not guarantee that this diagnostic is monotone; convergence is based on posterior and parameter deltas instead.

Value

An object of class vcmoe.

Fit a block-constant reduced VCMoE model

Description

Refits a VCMoE object under a block-constant coefficient constraint. A local-grid reference uses the established constrained BFGS optimizer; a joint-path reference uses a paper-inspired sample-weighted grid projection and applies the selected constraint after every M-step. This projection is not a generic constrained optimizer, and its diagnostic likelihood need not be monotone.

Usage

vcmoe_fit_reduced(
  fit,
  constrain = c("gating_constant", "expert_constant", "all_constant"),
  control = list()
)

Arguments

Value

A reduced object of class vcmoe with recomputed posterior and likelihood caches.

Report Identifiable VCMoE Gating Contrasts

Description

Report identifiable gating contrasts.

Usage

vcmoe_gating_contrasts(object, baseline = NULL, scaled = FALSE)

Arguments

Details

VCMoE stores gating coefficients as centered logits, so the absolute level of all component logits is not identifiable. Interpretable gating effects are component contrasts such as component 1 versus component 2 for k = 2, or component 1 and component 2 versus component 3 for k = 3 comparisons when baseline = 3.

Value

A data frame with one row per grid point, contrast, term, and block.

Generalized likelihood-ratio test for VCMoE coefficient variation

Description

Generalized likelihood-ratio test for VCMoE coefficient variation

Usage

vcmoe_glrt(
  fit,
  data,
  test = c("coefficient", "constant_block", "constant_all"),
  coefficient_set = c("expert", "gating", "sigma", "theta"),
  component = NULL,
  term = NULL,
  calibration = c("none", "bootstrap", "analytic_epanechnikov", "both",
    "parametric_bootstrap"),
  B = 200L,
  seed = NULL,
  control = list(),
  refit_control = list(),
  verbose = FALSE
)

Arguments

Details

Local-grid fits retain the 0.1.0 constrained BFGS null optimizer. Joint-path fits use a paper-inspired sample-weighted grid-projected null: after every M-step, each constrained coefficient path is replaced by its mean weighted by the number of observations assigned to each nearest grid point, and constrained local slopes are set to zero. Its statistic compares sample-level likelihood contributions evaluated at each observation's nearest grid point. The projected update is not a generic constrained optimizer and its diagnostic likelihood trace need not be monotone. Bootstrap calibration preserves both the full-fit engine and its matching null engine.

Value

A vcmoe_glrt object.

Inspect VCMoE Parameterization Metadata

Description

Inspect VCMoE parameterization metadata.

Usage

vcmoe_parameterization(object)

Arguments

Details

The package default is "a1_epanechnikov_scaled": Epanechnikov density weights 0.75 * (1 - t^2)_+ / h with t = (u - u0) / h, scaled local-linear slope storage, and centered gating logits. This helper reports those conventions for reproducible model summaries.

Value

A named list describing the estimator convention used by the fit, including kernel weights, local-linear basis scale, gating-logit storage, dispersion block, label-alignment method, and optimization controls.

Inspect VCMoE Local-Linear Slopes On The Scaled Basis

Description

Inspect VCMoE local-linear slopes on the scaled basis.

Usage

vcmoe_scaled_slopes(object, type = c("expert", "gating"), bandwidth = NULL)

Arguments

Details

VCMoE stores slopes on the scaled local-linear basis (u - u0) / h. This helper returns the stored scaled-basis slope block.

Value

An array with the same dimensions as the stored slope block.

Select a VCMoE bandwidth by K-fold cross-validation

Description

Select a VCMoE bandwidth by K-fold cross-validation

Usage

vcmoe_select_bandwidth(
  formula,
  data,
  u,
  k = 2L,
  family = "gaussian",
  bandwidth_grid = NULL,
  folds = 5L,
  u_grid = NULL,
  control = list(),
  label = "align",
  parameterization = "a1_epanechnikov_scaled",
  u_scale = c("unit", "none"),
  seed = NULL,
  refit = TRUE,
  engine = c("local_grid_em", "joint_path_em")
)

Arguments

Value

An object of class vcmoe_bandwidth_selection.