Turn relatedness matrices into graph matrices

Projects each input matrix into a graph-derived similarity matrix, one row per input matrix per method. The declared type decides which values count as strong links: for a distance the smallest off-diagonal values, for a similarity the largest. Values are never inspected to infer type.

Usage

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

Arguments

data: A tibble from precise_dist(), precise_transform(), precise_fusion(), precise_stability(), or an earlier precise_graph() call, or a list of matrices with type= declared. A bare matrix is refused, and raw feature data should go through precise_dist() first.
methods: A character vector of graph method names. One row is produced per input matrix per method.
type: Only for bare-list input. "distance" or "similarity". Must be omitted for tibble input.
params: A named list of per-method parameter lists, for example list(knn = list(k = 5), threshold = list(threshold = 0.2)).
parallel: TRUE or FALSE. Run the input-by-method loop with \%dopar\% on a registered foreach backend.
verbose: TRUE or FALSE. Report each projection as it runs.

Value

A tibble with one row per input matrix per method and the columns distance (the composite key <input>__<method>), matrix, type (always "similarity"), graph_method, input, input_type, parameters, meta, and time_taken_seconds. meta always holds the undirected edge count and the number of connected components, and individual methods add their own fields.

Details

The methods fall into two groups. Constructors accept either input type and decide which pairs become edges. Similarity-only methods operate on declared similarity matrices. Requesting an incompatible method is an error before any projection runs.

Constructors

knn connects each object to its k closest neighbours and symmetrizes by union.
weighted_knn keeps the same edges as knn but retains a scaled edge strength instead of 1. Distance input is range-inverted before masking, similarity input is range-scaled.
mutual_knn keeps an edge only when both objects selected each other.
threshold keeps pairs with d <= threshold for distance input or s >= threshold for similarity input. The cut is inclusive.
quantile_threshold keeps the strongest round(prop * choose(n, 2)) pairs.

All three kNN constructors take k, which defaults to round(sqrt(n)) and must satisfy 1 <= k < n. threshold requires a finite numeric threshold and quantile_threshold requires prop in (0, 1]. Neither has a default, so both must be supplied through params.

Similarity-only methods

These accept similarity input. laplacian and chua additionally require non-negative values:

laplacian returns the symmetrically normalized adjacency D^(-1/2) W D^(-1/2). meta reports the number of zero-degree nodes.
chua returns a neighbourhood-overlap weight computed from the nonzero support of the graph.
graphical_lasso estimates a sparse precision matrix with glasso::glasso and keeps the nonzero off-diagonal entries as edges. It requires the optional glasso package and covariance-like or correlation-like input with a positive diagonal. Parameters are rho (positive, default 0.1), edge_tol (default 1e-8), thr, maxit, and penalize_diagonal.

Output guarantees

Ties are broken by ascending object index, so a given input always yields the same graph. Every returned matrix is symmetric, non-negative, zero-diagonal, and typed "similarity". knn, mutual_knn, threshold, quantile_threshold, and graphical_lasso return 0/1 adjacency matrices; weighted_knn, laplacian, and chua return weighted similarities.

References

Chua HN, Sung WK, Wong L (2006). Exploiting indirect neighbours and topological weight to predict protein function from protein-protein interactions. Bioinformatics, 22(13), 1623–1630. doi:10.1093/bioinformatics/btl145 .

Friedman J, Hastie T, Tibshirani R (2008). Sparse inverse covariance estimation with the graphical lasso. Biostatistics, 9(3), 432–441. doi:10.1093/biostatistics/kxm045 .

Author

Brian Muchmore

Examples

data(data_cell_cycle, package = "PreciseDist")

cells <- c(1:4, 60:63, 118:121)
cell_cycle <- as.matrix(data_cell_cycle[cells, 2:41])
rownames(cell_cycle) <- paste0(data_cell_cycle$Cell_cycle[cells], "_", cells)

distances <- precise_dist(
  cell_cycle,
  dists = c("euclidean", "manhattan"),
  verbose = FALSE
)

graphs <- precise_graph(
  distances,
  methods = "knn",
  params = list(knn = list(k = 3)),
  verbose = FALSE
)

graphs[, c("distance", "graph_method", "input", "input_type", "type")]
#> # A tibble: 2 × 5
#>   distance       graph_method input     input_type type      
#>   <chr>          <chr>        <chr>     <chr>      <chr>     
#> 1 euclidean__knn knn          euclidean distance   similarity
#> 2 manhattan__knn knn          manhattan distance   similarity
graphs$meta[[1]]
#> $edges
#> [1] 26
#> 
#> $components
#> [1] 1
#>