Skip to contents

Project typed relatedness matrices into graph matrices

Source: R/precise_graph.R
precise_graph.Rd

precise_graph() turns explicit distance or similarity matrices into graph-derived similarity matrices. It does not infer type from values: distance inputs keep the smallest off-diagonal values, similarity inputs keep the largest off-diagonal values, and every output row records the source type.

Usage

precise_graph(
  data,
  methods = "knn",
  type = NULL,
  params = list(),
  parallel = FALSE,
  verbose = TRUE
)

Arguments

data

A typed PreciseDist tibble with distance/matrix/type, a typed fusion tibble with method/matrix/type, or a list of matrices with type= declared. A bare matrix is rejected; raw feature data should enter through precise_dist.

methods

Character vector of graph method names. One output row is produced per input matrix per method.

type

Only for bare-list input: "distance" or "similarity". Must be omitted for typed tibble input.

params

Named list of per-method parameter lists, e.g. list(knn = list(k = 5), threshold = list(threshold = 0.2)).

parallel

TRUE or FALSE. Should the input-method loop use %dopar%? These deterministic set-selection methods are usually cheap; parallelism matters mostly for many large matrices.

verbose

TRUE or FALSE. Should the function report progress?

Value

A tibble with one row per input matrix per method: distance is the composite key <input>__<method>, matrix is the graph-derived similarity matrix, type is always "similarity", and meta records undirected edge count plus connected-component count. Backend methods may add extra meta fields.

Details

The output keeps the distance/matrix/type triple used by precise_fusion, so graph output can be fused directly. Fusing multiple knn rows with precise_fusion(methods = "mean") gives a co-neighbour consensus matrix: each cell is the fraction of input matrices in which that pair is adjacent.

Available methods:

  • knn: connect each object to its k closest neighbours, then symmetrize by union. Default k = round(sqrt(n)).

  • weighted_knn: connect each object to its k closest neighbours, symmetrize by union, and keep standardized edge-strength weights instead of replacing every retained edge with 1. Distance input is range-inverted before masking; similarity input is range-scaled.

  • mutual_knn: keep only reciprocal k-nearest-neighbour edges.

  • threshold: keep pairs with d <= threshold for distance input, or s >= threshold for similarity input. The cut is inclusive.

  • quantile_threshold: keep the strongest round(prop * choose(n, 2)) undirected pairs.

  • laplacian: normalize a non-negative similarity/adjacency matrix as D^(-1/2) W D^(-1/2). This is a weighted graph normalization and accepts similarity input only.

  • chua: compute Chua-style neighbourhood-overlap normalization from the nonzero support of a similarity/adjacency matrix. This is a weighted graph normalization and accepts similarity input only.

  • graphical_lasso: use glasso::glasso on positive-semidefinite covariance/correlation-like similarity input, then keep nonzero off-diagonal precision entries as graph edges. parameters are rho (positive, default 0.1), edge_tol (default 1e-8), thr, maxit, and penalize_diagonal.

graphical_lasso requires the optional glasso package and intentionally accepts similarity input only. It is a sparse conditional-dependence graph constructor, not a generic distance-to-graph conversion.

Ties are broken deterministically by ascending object index, and retained graph matrices are always symmetric, non-negative, zero-diagonal, and type = "similarity". Constructor methods return binary 0/1 adjacency matrices; normalization methods may return weighted graph similarities.

Author

Brian Muchmore

Examples

x <- replicate(4, rnorm(20))

dists <- x %>%
  precise_dist(c("euclidean", "manhattan"), verbose = FALSE) %>%
  precise_transform(to = "distance")

graphs <- precise_graph(
  dists,
  methods = c("knn", "quantile_threshold"),
  params = list(knn = list(k = 2), quantile_threshold = list(prop = 0.25)),
  verbose = FALSE
)

precise_fusion(graphs, methods = "mean", verbose = FALSE)
#> # A tibble: 1 × 7
#>   method matrix          type       time_taken_seconds parameters meta   inputs
#>   <chr>  <list>          <chr>                   <dbl> <list>     <list> <list>
#> 1 mean   <dbl [20 × 20]> similarity                  0 <list [0]> <list> <chr>