Build iKNN Graphs and Select a Neighborhood Size

Builds an iKNN graph sequence and selects k from structural edit-distance stability, label-mixing stability, or both.

Usage

build.iknn.graphs.and.selectk(
  X,
  k.values,
  method = c("both", "edit", "mixing", "none"),
  pca.dim = 100,
  variance.explained = 0.99,
  trim.disconnected = TRUE,
  edit.min.lcc.frac = 1,
  edit.eps = 0.05,
  labels = NULL,
  perm.blocks = NULL,
  mixing.metric = c("homophily.effect", "homophily.z", "homophily.adjusted",
    "assortativity.effect", "assortativity.z", "homophily", "assortativity",
    "conductance.median", "conductance.wmean"),
  mixing.min.lcc.frac = 0.98,
  mixing.eps = 0.05,
  mixing.require.local.extremum = TRUE,
  mixing.window = 1L,
  n.perm = 200L,
  use.edge.weights = TRUE,
  weights.are.edge.lengths = FALSE,
  affinity.method = c("exp", "inv"),
  affinity.sigma = NULL,
  affinity.sigma.from = c("k.cc.mixing", "k.max.lcc", "k.trim"),
  affinity.eps = 1e-08,
  simplify.multiple = TRUE,
  seed = 1L,
  verbose = TRUE,
  ...
)

Arguments

X

Numeric observation-by-feature matrix.

k.values

Strictly increasing integer vector of neighborhood sizes, each between 1 and n - 1.

method

Selection criterion.

pca.dim, variance.explained

PCA controls forwarded to create.iknn.graphs().

trim.disconnected

Logical; trim to a largest connected component when the requested connectivity tail is absent.

edit.min.lcc.frac, edit.eps

Connectivity and tolerance controls for edit-distance selection.

labels, perm.blocks

Optional labels and permutation blocks for mixing selection.

mixing.metric, mixing.min.lcc.frac, mixing.eps

Mixing criterion, connectivity threshold, and tolerance.

mixing.require.local.extremum, mixing.window

Local-extremum controls for the mixing curve.

n.perm

Number of label permutations.

use.edge.weights, weights.are.edge.lengths

Edge-weight interpretation.

affinity.method, affinity.sigma, affinity.sigma.from, affinity.eps

Controls for converting edge lengths to affinities.

simplify.multiple

Logical; simplify loops and multiple edges.

seed

Random seed.

verbose

Logical; report progress.

...

Additional arguments forwarded to create.iknn.graphs().

Value

An object of class "build_iknn_graphs_and_selectk" containing the graph sequence, connectivity diagnostics, selection curves, selected neighborhood sizes, trimming metadata, and call parameters.

Examples

set.seed(1)
x <- matrix(rnorm(60), ncol = 2)
selected <- build.iknn.graphs.and.selectk(x, k.values = seq.int(2, 4),
    method = "edit",
    verbose = FALSE)
selected$k.opt.edit
#> [1] 3