% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build_graph_from_consensus.R
\name{build_graph_from_consensus}
\alias{build_graph_from_consensus}
\title{Build a consensus graph object from multiple adjacency matrices}
\usage{
build_graph_from_consensus(
  adj_list,
  method = c("rank_fusion", "intersection", "weighted_average", "majority_vote"),
  rank_fusion_algorithm = c("borda", "rra", "rrf"),
  threshold = NULL,
  binarize = c("none", "threshold", "topk"),
  binarize_threshold = 0,
  binarize_topk = NULL,
  weights = NULL,
  min_methods = NULL,
  rrf_k = 60,
  node_handling = c("intersect", "union"),
  module.method = c("Fast_greedy", "Walktrap", "Edge_betweenness", "Spinglass"),
  node_annotation = NULL,
  top_modules = 15,
  seed = 1115
)
}
\arguments{
\item{adj_list}{Named or unnamed list of at least two square numeric
adjacency matrices. All matrices must have row and column names
identifying features; matrices need not share identical feature
sets (see `node_handling`). Pre-thresholded inputs (zeros for
non-significant pairs) are supported and recommended.}

\item{method}{Character. Top-level consensus strategy. One of
`"rank_fusion"` (default), `"intersection"`, `"weighted_average"`,
`"majority_vote"`. See \strong{Method details}.}

\item{rank_fusion_algorithm}{Character. Only used when `method =
"rank_fusion"`. One of `"borda"` (default), `"rra"`, `"rrf"`.
See \strong{Rank fusion algorithms}.}

\item{threshold}{Numeric or `NULL` (default). Optional final
absolute-weight cutoff applied to the consensus matrix; entries
with `abs(w) < threshold` are zeroed out.}

\item{binarize}{Character. Only used by `"intersection"` and
`"majority_vote"`. One of `"none"` (default; treat any non-zero
entry as an edge), `"threshold"` (apply `binarize_threshold`),
`"topk"` (keep the global top-`binarize_topk` strongest edges per
matrix).}

\item{binarize_threshold}{Numeric (default `0`). Per-method
`|w| >= binarize_threshold` edge cut-off when `binarize =
"threshold"`.}

\item{binarize_topk}{Integer or `NULL`. Per-method top-K cut-off
when `binarize = "topk"`.}

\item{weights}{Numeric vector or `NULL` (default). Per-method
weights for `"weighted_average"`. Length must match `length(
adj_list)`; values are renormalised to sum to 1. `NULL` uses
uniform weights.}

\item{min_methods}{Integer or `NULL` (default). Minimum number of
methods that must support an edge for `"majority_vote"`. `NULL`
defaults to a strict majority (`floor(M/2) + 1` where `M` is the
number of methods).}

\item{rrf_k}{Numeric (default `60`). Smoothing constant for
reciprocal rank fusion (`method = "rank_fusion",
rank_fusion_algorithm = "rrf"`).}

\item{node_handling}{Character. How to align features that are not
present in every input matrix. `"intersect"` (default) keeps only
features common to all inputs; `"union"` keeps every feature
appearing in any input and treats missing entries as zero.}

\item{module.method}{Character. Module detection method passed
through to [build_graph_from_adj_mat()] when constructing the
final `tbl_graph`. One of `"Fast_greedy"`, `"Walktrap"`,
`"Edge_betweenness"`, `"Spinglass"`.}

\item{node_annotation}{Optional data frame attached as vertex
metadata; first column must match feature names of the consensus
matrix.}

\item{top_modules}{Integer (default `15`). Number of top-ranked
modules to retain in the final `tbl_graph`; smaller modules are
collapsed into `"Others"`.}

\item{seed}{Integer (default `1115`). Random seed.}
}
\value{
A `tbl_graph` object whose schema matches the rest of the
  `build_graph_from_*()` family (vertex columns `name`,
  `modularity`, `modularity2`, `modularity3`, `Modularity`,
  `Degree`, `Strength`; edge columns `weight`, `correlation`,
  `corr_direction`). Plug straight into [ggNetView()] for
  visualisation.
}
\description{
Aggregates two or more adjacency matrices -- typically produced by
different network inference methods (e.g. SparCC, SpiecEasi, WGCNA,
Hmisc, plain correlation) on the same set of features -- into a single
consensus network and returns a `tbl_graph` consistent with the rest
of the `build_graph_from_*()` family. Combining multiple methods is a
standard strategy for reducing method-specific bias in biological
network inference; see Aghayeva et al. (2024, CMiNet) and Chowdhury
et al. (2024, hybrid Bayesian / ML / network framework) for related
approaches.
}
\details{
Four consensus strategies are supported through `method`. Three of
them (`"intersection"`, `"weighted_average"`, `"majority_vote"`)
operate directly on the input weights; the fourth (`"rank_fusion"`)
converts each method's adjacency to ranks first, which makes the
aggregation invariant to the very different weight scales produced
by different inference algorithms (correlation in [-1, 1], partial
correlation, TOM in [0, 1], ...). When `method = "rank_fusion"`,
three classical rank-aggregation algorithms are available via
`rank_fusion_algorithm`: Borda count (mean rank), Robust Rank
Aggregation (RRA, Kolde et al. 2012), and Reciprocal Rank Fusion
(RRF, Cormack et al. 2009).
}
\section{Method details}{

\describe{
  \item{`"intersection"`}{An edge survives in the consensus iff it
    is non-zero (after `binarize`) in **every** input matrix.
    Consensus weight is the mean of the input weights for surviving
    edges. Strictest of the four strategies.}
  \item{`"weighted_average"`}{Each input matrix is min-max
    normalised to [0, 1] in absolute value (sign preserved), then
    combined as a weighted sum using `weights` (default uniform).
    Consensus weight is in [-1, 1] and inherits the sign of the
    methods that dominate the average.}
  \item{`"majority_vote"`}{Each input matrix is binarised, edges are
    summed, and an edge survives in the consensus iff the count is
    at least `min_methods`. Consensus weight is the mean of the
    input weights restricted to the methods that voted yes.}
  \item{`"rank_fusion"`}{Each input matrix's pairs are ranked by
    `|w|` (descending). Ranks are aggregated according to
    `rank_fusion_algorithm`, then min-max normalised to [-1, 1]
    (sign taken from the mean of the input weights). Most robust to
    across-method scale differences.}
}
}

\section{Rank fusion algorithms}{

\describe{
  \item{`"borda"`}{Mean rank across methods. Lower mean rank = more
    supported edge. Simple, no assumptions, good baseline.}
  \item{`"rra"`}{Robust Rank Aggregation (Kolde et al. 2012,
    Bioinformatics). Computes a rho-score for each pair under the
    null hypothesis of uniformly distributed ranks; edges with very
    small rho consistently outrank random expectation. Uses the
    `RobustRankAggreg` package when available; otherwise falls back
    to an inline Beta-order-statistic implementation. Output score
    is `-log10(rho)` so larger = more confident.}
  \item{`"rrf"`}{Reciprocal Rank Fusion (Cormack et al. 2009).
    Per-edge score is `sum_m 1 / (k + rank_m)` where `k = rrf_k`
    (default 60, the information-retrieval convention). Robust to
    extreme rank values, no parameter tuning required.}
}
}

\examples{
\donttest{
set.seed(1)
n <- 30
nm <- paste0("g", seq_len(n))

# Three "methods": shared signal + per-method noise.
core <- matrix(0, n, n, dimnames = list(nm, nm))
for (i in 1:6) for (j in (i + 1):8) core[i, j] <- core[j, i] <- 0.8
jitter <- function() core + matrix(stats::rnorm(n * n, sd = 0.05), n, n,
                                   dimnames = list(nm, nm))

adj_list <- list(method_A = jitter(), method_B = jitter(), method_C = jitter())

# Borda rank fusion with a final |w| >= 0.3 cutoff:
obj <- build_graph_from_consensus(
  adj_list = adj_list,
  method = "rank_fusion",
  rank_fusion_algorithm = "borda",
  threshold = 0.3
)
obj
}
}
\references{
Kolde, R., Laur, S., Adler, P., & Vilo, J. (2012). Robust rank
aggregation for gene list integration and meta-analysis.
*Bioinformatics*, 28(4), 573-580.

Cormack, G. V., Clarke, C. L. A., & Buettcher, S. (2009). Reciprocal
rank fusion outperforms Condorcet and individual rank learning
methods. *Proceedings of the 32nd International ACM SIGIR
Conference*, 758-759.

Aghayeva, R., et al. (2024). CMiNet: An R package and user-friendly
Shiny App for constructing consensus microbiome networks.

Chowdhury, S., et al. (2024). A hybrid framework for disease
biomarker discovery in microbiome research combining Bayesian
networks, machine learning, and network-based methods.
}
