Compute Local Correlation with Posterior Uncertainty Propagation

Summarizes local-correlation estimates over supplied draws of vertex fields, providing a mean, standard deviation, and interval at each vertex for each feature. The function does not fit or refit a smoother.

Usage

lcor.with.posterior(
  adj.list,
  weight.list,
  y.hat,
  Z.hat.samples,
  lcor.type = c("derivative", "unit", "sign"),
  credible.level = 0.95,
  return.samples = FALSE,
  verbose = TRUE
)

Arguments

adj.list: Adjacency list (1-based R indexing)
weight.list: Edge weight list
y.hat: Finite numeric response vector of positive length n, in graph vertex order. Optional names identify vertices; see Details.
Z.hat.samples: A list of length p whose elements are n by B matrices of finite numeric sampled vertex fields, or one n by B matrix for a single feature. Every feature must have the same positive number B of draws. Optional list names identify features and matrix row names identify vertices.
lcor.type: Type of local correlation weighting: "derivative" (default), "unit", or "sign". See lcor for details.
credible.level: Finite numeric interval level strictly between 0 and 1 (default 0.95).
return.samples: Logical. Return individual lcor samples (default FALSE). Setting TRUE with many features will use substantial memory.
verbose: Logical. Print progress (default TRUE)

Value

A list of class "lcor.posterior" containing:

mean: Matrix (p x n) of posterior mean lcor values
sd: Matrix (p x n) of posterior standard deviations
lower: Matrix (p x n) of lower credible bounds
upper: Matrix (p x n) of upper credible bounds
samples: List of sample matrices (only if return.samples = TRUE)
n.samples: Number of posterior samples used
n.features: Number of features
n.vertices: Number of vertices
lcor.type: Type of lcor weighting used

Details

Each supplied draw is passed to lcor against the fixed response field. This makes the estimand independent of how the draws were generated. The graph and response remain fixed. Quantile intervals are pointwise, not simultaneous; their posterior interpretation depends on the supplied draws and excludes uncertainty not represented in those draws. Archived graph-regression objects can be adapted in gflowx.

All features are validated before any local correlation is computed; unequal draw counts are rejected rather than truncated. With one draw, the mean and both interval endpoints equal its local correlation, and the standard deviation is NA.

Supplied feature names and vertex names must be unique, nonmissing, and nonempty. Vertex names in y.hat and row names in any supplied matrices must agree in order; inputs are never reordered by name. Names do not verify graph alignment: rows must still follow the adjacency list's vertex order. Feature names become row names of the summary matrices and names of the optional samples list. Vertex names become column names of the summaries and row names of sample matrices; draw column names are preserved separately for each feature. Unnamed dimensions remain unnamed, and summary() labels unnamed features Feature1, Feature2, and so on.

Memory

The four feature-by-vertex summary matrices require about 32pn bytes. Processing one feature also materializes an n-by-B double matrix (8nB bytes), even when return.samples = FALSE. Returning samples retains another 8pn*B bytes across features, in addition to input draws and temporaries. Process subsets of features separately when needed; keep the same response, graph, settings and complete draw count, and preserve feature identities when combining summaries. This does not reduce the per-feature draw allocation.

Examples

adj <- list(c(2L), c(1L, 3L), c(2L))
weights <- lapply(adj, function(x) rep(1, length(x)))
draws <- cbind(c(0, 1, 2), c(0.1, 0.9, 2.1), c(-0.1, 1.1, 1.9))
post <- lcor.with.posterior(adj, weights, c(0, 1, 2), draws,
                            verbose = FALSE)