Skip to contents

Combine several relatedness matrices into one consensus matrix

Source: R/precise_fusion.R
precise_fusion.Rd

Reduces two or more relatedness matrices of one declared type to a single fused matrix per requested method, each typed "distance" or "similarity".

Usage

precise_fusion(
  data,
  methods = "mean",
  type = NULL,
  params = list(),
  verbose = TRUE
)

Arguments

data

A tibble from precise_dist(), precise_transform(), precise_fusion(), precise_graph(), or precise_stability(), with every row of one type. A named list of matrices also works when you declare type=, and dist objects in that list are coerced. Unnamed list elements are labelled matrix_1, matrix_2, and so on.

methods

A character vector of unique method names, or "all" on its own to run every method that suits the input type and whose backend is installed. One row is returned per method. Under "all", weighted_mean uses equal weights unless you supply them in params.

type

Only for bare-list input. "distance" or "similarity", applying to every element. Must be omitted when data is a tibble, whose type column is authoritative.

params

A named list of per-method parameter lists keyed by method name, for example list(snf = list(K = 20), weighted_mean = list(weights = w)). Unknown method keys, unknown parameter names, and out-of-range values are all errors.

verbose

TRUE or FALSE. Report each method as it starts and finishes.

Value

A tibble with one row per method and the columns method, matrix (the fused matrix, square, symmetric, and named), type, time_taken_seconds, parameters (what was actually used, including defaults), meta (backend extras such as the distatis alpha weights, and an empty list otherwise), and inputs (the names of the matrices that went in).

Details

All inputs must share one type. A mix of distances and similarities is an error. Each method also declares the input type it accepts, and an incompatible request fails before any fusion runs.

Methods

These accept either input type and return the same type:

  • mean and median reduce cell by cell.

  • weighted_mean requires weights, one non-negative value per input matrix, normalized internally so only relative magnitudes matter.

  • trimmed_mean takes trim in [0, 0.5) and reduces cell by cell.

  • rank_mean averages the ascending rank of the off-diagonal values. The output is on the rank scale rather than the input scale, and ranking is monotone so pair ordering is preserved. The diagonal is 0 for a distance and the maximum rank for a similarity.

These take distance input and require an optional backend package:

  • analogue_fuse returns a distance. It is analogue::fuse, the mean of the max-scaled inputs. Optional weights give a weighted mean of the max-scaled inputs.

  • snf returns a similarity. It is SNFtool::affinityMatrix on each input followed by SNFtool::SNF. Parameters are K (whole number, default round(sqrt(n))), sigma (default 0.5), and t (whole number, default 20).

  • distatis returns a distance. It is the DistatisR::distatis compromise, converted from the scalar-product matrix by d_ij = sqrt(S_ii + S_jj - 2 * S_ij). The per-input alpha weights are returned in meta.

A missing backend package errors before any fusion runs, naming both the required package and the base R reducers that remain available.

Output guarantees

A fused "distance" is non-negative with a zero diagonal. The triangle inequality holds only where the arithmetic provides it, namely mean and weighted_mean of metrics, analogue_fuse, and distatis. The median, trimmed_mean, and rank_mean outputs can violate it.

A fusion producing non-finite values is an error.

References

Wang B, Mezlini AM, Demir F, et al. (2014). Similarity network fusion for aggregating data types on a genomic scale. Nature Methods, 11, 333–337. doi:10.1038/nmeth.2810 .

Abdi H, Williams LJ, Valentin D, Bennani-Dosse M (2012). STATIS and DISTATIS: optimum multitable principal component analysis and three way metric multidimensional scaling. WIREs Computational Statistics, 4(2), 124–167. doi:10.1002/wics.198 .

Simpson GL (2007). Analogue methods in palaeoecology: using the analogue package. Journal of Statistical Software, 22(2), 1–29. doi:10.18637/jss.v022.i02 .

See also

precise_transform() for coercion to one type, precise_stability() for sensitivity of the fused result to its inputs, and precise_graph().

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", "canberra"),
  verbose = FALSE
)

fused <- precise_fusion(
  distances,
  methods = "mean",
  verbose = FALSE
)

fused[, c("method", "type", "time_taken_seconds")]
#> # A tibble: 1 × 3
#>   method type     time_taken_seconds
#>   <chr>  <chr>                 <dbl>
#> 1 mean   distance                  0
fused$matrix[[1]][1:3, 1:3]
#>          G1_1     G1_2     G1_3
#> G1_1  0.00000 18.72875 19.60753
#> G1_2 18.72875  0.00000 21.75156
#> G1_3 19.60753 21.75156  0.00000