# MosaiClusteR: an umbrella framework for multi-source and multi-omics clustering

# What MosaiClusteR is for

Modern studies rarely describe their samples with a single table. A cohort may be profiled by several assays at once — transcriptomics, proteomics, metabolomics, methylation, microbiome — or a set of objects may be described by several heterogeneous data sources. MosaiClusteR is a framework for discovering the sample structure that these sources agree on: it takes a collection of data matrices measured over the same objects and returns an integrated clustering.

The package is deliberately a catalogue, not a single algorithm. Multi-source clustering can be approached in many ways, and no one method is best across all data regimes, so MosaiClusteR gathers a broad set of methods behind one consistent interface and adds everything you need to choose between them: preprocessing, cluster-number selection, agreement metrics, visual comparison, cluster characterisation, and — for omics — pathway and gene-set interpretation.

The methods are organised into five integration paradigms:

Paradigm | Idea | Examples in this package
--- | --- | ---
Direct | Concatenate the sources, cluster once | `ADC`, `ADEC`
Similarity-based | Combine per-source object similarities | `WeightedClust`, `WonM`, `SNF`, `NEMO`
Graph-based | Partition a graph built from many clusterings | `EnsembleClustering`, `HBGF`, `ClusteringAggregation`
Voting / consensus | Let many partitions vote on co-membership | `CEC`, `CVAA`, `ConsensusClustering`, `EvidenceAccumulation`, `LinkBasedClustering`, the ABC family
Hierarchy-based | Merge per-source hierarchies | `HierarchicalEnsembleClustering`, `EHC`
Factor / low-rank | Cluster a shared latent representation | `intNMF`, `spectral_clustering`, `LUCID`

    library(MosaiClusteR)

# The data model

Every method in MosaiClusteR speaks the same language.

- Input is a `List` of numeric matrices, one per source, all measured over the same objects in the same order. The convention is objects in rows, features in columns (`n` objects x `m_k` features for source `k`). Sources may have different numbers of features; they only need to share the objects.
- Output is a small list with two standard components: `DistM` (an object-by-object dissimilarity, `n x n`) and `Clust` (a fitted hierarchical clustering). Some methods additionally return a `$cluster` label vector.
- Methods that work from a precomputed dissimilarity accept `type = "dist"`; otherwise `type = "data"` (the default) starts from the raw matrices.

Because the interface is uniform, swapping one method for another is a one-line change, and the evaluation / visualisation tools work with any of them.

The package ships a small toy data set — two sources over 60 shared objects with three planted groups — used throughout this vignette.

    data(mosaic_toy)
    L     <- mosaic_toy$List      # a list of two matrices, objects in rows
    truth <- mosaic_toy$truth     # the known group of each object (for illustration)
    S     <- length(L)            # number of sources
    K     <- 3                    # number of groups
    vapply(L, dim, integer(2))    # 60 objects x (120, 150) features
    #>      source1 source2
    #> [1,]      60      60
    #> [2,]     120     150

You can also simulate structured multi-source data with `mosaic_sim()`:

    sim <- mosaic_sim(n = 90, g = 3, seed = 1)   # n objects, g groups
    str(sim$List, max.level = 1)

# A first end-to-end analysis

A typical analysis moves through four layers: preprocess -> baseline -> integrate -> evaluate.

## Layer 1 - Preprocess

Make heterogeneous sources comparable and turn a source into a dissimilarity.

    Xn <- Normalization(L[[1]], method = "Quantile")   # optional per-source scaling
    D1 <- Distance(L[[1]], distmeasure = "euclidean")   # object-by-object distance
    round(as.matrix(D1)[1:4, 1:4], 2)
    #>       obj01 obj02 obj03 obj04
    #> obj01  0.00  0.22  0.21  0.23
    #> obj02  0.22  0.00  0.23  0.22
    #> obj03  0.21  0.23  0.00  0.24
    #> obj04  0.23  0.22  0.24  0.00

`Distance()` supports many measures — `"euclidean"`, `"manhattan"`, `"tanimoto"`/`"jaccard"` (for binary fingerprints), and correlation-based distances among them — and `Normalization()` offers quantile, standardisation and range scaling. Binary sources (e.g. molecular fingerprints, presence/absence) are handled by choosing an appropriate `distmeasure`.

## Layer 2 - Single-source baselines

Cluster each source on its own to see what it recovers in isolation. Weak or disagreeing baselines are exactly what motivates integration.

    b1 <- Cluster(L[[1]], distmeasure = "euclidean", normalize = FALSE, nrclusters = 3)
    b2 <- Cluster(L[[2]], distmeasure = "euclidean", normalize = FALSE, nrclusters = 3)
    c(source1 = cluster_agreement(mosaic_labels(b1, 3), truth)[["ARI"]],
      source2 = cluster_agreement(mosaic_labels(b2, 3), truth)[["ARI"]])
    #> source1 source2
    #>       1       1

## Layer 3 - Integrate, and Layer 4 - Evaluate

The whole point of the uniform interface is that you can run many integration methods with almost identical calls and score them the same way. Here we run one method from each paradigm and compare how well each recovers the planted groups with the Adjusted Rand Index (`cluster_agreement()` also returns NMI, Jaccard and purity). `mosaic_labels(fit, k)` cuts any fitted result into `k` clusters.

    DM <- rep("euclidean", S); NM <- rep(FALSE, S); ME <- rep(list(NULL), S)

    methods <- list(
      "ADC (direct)"           = function() mosaic_labels(
          ADC(L, distmeasure = "euclidean", normalize = FALSE), K),
      "WeightedClust (simil.)" = function() mosaic_labels(
          WeightedClust(L, type = "data", distmeasure = DM, normalize = NM,
                        method = ME, weight = seq(1, 0, -0.25)), K),
      "WonM (similarity)"      = function() mosaic_labels(
          WonM(L, type = "data", distmeasure = DM, normalize = NM, method = ME,
               nrclusters = rep(list(2:6), S), linkage = rep("ward", S)), K),
      "SNF (graph fusion)"     = function() mosaic_labels(
          SNF(L, type = "data", distmeasure = DM, normalize = NM, method = ME,
              NN = 20, T = 20), K),
      "NEMO (neighbourhood)"   = function() NEMO(L, k = K, NN = 20)$cluster,
      "CEC (consensus)"        = function() mosaic_labels(
          CEC(L, distmeasure = DM, normalize = NM, method = ME,
              r = vapply(L, ncol, 1L) %/% 2L, nrclusters = as.list(rep(K, S)),
              linkage = rep("ward", S)), K),
      "intNMF (factor)"        = function() intNMF(L, k = K, nstart = 4)$cluster,
      "Data nuggets"           = function() nugget_cluster(
          do.call(cbind, L), k = K, max_nuggets = 40)$cluster,
      "ABC (voting)"           = function() mosaic_labels(
          M_ABCpp(L, numsim = 60, NC = K), K)
    )

    ari <- vapply(methods, function(f)
      tryCatch(round(cluster_agreement(f(), truth)[["ARI"]], 2),
               error = function(e) NA_real_), numeric(1))
    sort(ari, decreasing = TRUE)
    #>           ADC (direct) WeightedClust (simil.)      WonM (similarity)
    #>                      1                      1                      1
    #>     SNF (graph fusion)   NEMO (neighbourhood)        CEC (consensus)
    #>                      1                      1                      1
    #>        intNMF (factor)           Data nuggets           ABC (voting)
    #>                      1                      1                      1

On this toy set most methods recover the planted structure; on real data they diverge, which is why running several and comparing them is the recommended workflow rather than trusting a single algorithm.

# The method catalogue

This section describes each integration method, grouped by paradigm. All take the same `List` input; the calls below are complete and ready to adapt.

## Direct integration

The sources are combined into one representation and clustered once.

- `ADC` — Aggregated Data Clustering: concatenate the sources (after optional per-source normalisation), form a single distance and one hierarchy.
- `ADEC` — Aggregated Data Ensemble Clustering: repeatedly subsample / reduce the concatenated data and aggregate the resulting partitions.

    ADC(L, distmeasure = "euclidean", normalize = FALSE)
    ADEC(L, distmeasure = DM, normalize = NM, method = ME, nrclusters = 3, t = 10)

## Similarity-based integration

Each source contributes an object-by-object similarity; the similarities are combined before clustering.

- `WeightedClust` — convex (weighted) combination of per-source distances over a grid of weights; good when you want to control each source’s influence.
- `WonM` — Weighting on Membership: consensus co-membership accumulated over many cut heights, so no single `k` has to be fixed up front.
- `SNF` — Similarity Network Fusion: iteratively cross-diffuses per-source similarity networks into a single fused network (needs `SNFtool`).
- `NEMO` — NEighborhood based Multi-Omics clustering: averages neighbourhood affinities across sources and tolerates partially missing samples.

    WeightedClust(L, type = "data", distmeasure = DM, normalize = NM, method = ME,
                  weight = seq(1, 0, -0.25))
    WonM(L, type = "data", distmeasure = DM, normalize = NM, method = ME,
         nrclusters = rep(list(2:6), S), linkage = rep("ward", S))
    SNF(L, type = "data", distmeasure = DM, normalize = NM, method = ME, NN = 20, T = 20)
    NEMO(L, k = K, NN = 20)$cluster

## Graph-based integration

Many base clusterings are encoded as a graph (of objects and/or clusters) that is then partitioned.

- `EnsembleClustering` — CSPA / HGPA / MCLA hyper-graph consensus.
- `HBGF` — Hybrid Bipartite Graph Formulation over objects and clusters.
- `ClusteringAggregation` — aggregate many partitions by a distance between clusterings.

    HBGF(L, type = "data", distmeasure = DM, normalize = NM, method = ME, nrclusters = 3)
    ClusteringAggregation(L, type = "data", distmeasure = DM, normalize = NM,
                          method = ME, nrclusters = 3)
    # EnsembleClustering() / EHC() call an external graph-partitioning executable
    # (e.g. METIS); install it and pass its path via 'executable' to use them.

## Voting / consensus integration

Many partitions “vote” on whether each pair of objects belongs together; a consensus co-membership is then clustered.

- `CEC` — (Consensus) Ensemble Clustering by incidence accumulation across sources and cut points; weight-aware.
- `CVAA` — Cumulative Voting Adjusted Aggregation, aligning partitions to a reference before merging.
- `ConsensusClustering` — iterative (probabilistic) voting consensus.
- `EvidenceAccumulation` — co-association matrix across partitions.
- `LinkBasedClustering` — refines the co-association with link-based similarity (CTS / SRS / ASRS).
- The ABC family — `M_ABCpp`, `M_ABCdist` and the deep-learning variant `M_ABCdeep` build a consensus by repeatedly bootstrapping objects and feature bundles per source; `M_ABCdist.WC` fuses per-source distances with an optimally weighted combination.

    CEC(L, distmeasure = DM, normalize = NM, method = ME,
        r = vapply(L, ncol, 1L) %/% 2L, nrclusters = as.list(rep(K, S)),
        linkage = rep("ward", S))
    ConsensusClustering(L, type = "data", distmeasure = DM, normalize = NM,
                        method = ME, nrclusters = 3)
    EvidenceAccumulation(L, type = "data", distmeasure = DM, normalize = NM,
                         method = ME, nrclusters = 3)
    LinkBasedClustering(L, type = "data", distmeasure = DM, normalize = NM,
                        method = ME, nrclusters = 3, linkBasedMethod = "SRS")
    M_ABCpp(L, numsim = 200, NC = 3)                 # co-clustering consensus
    M_ABCdist(L, numsim = 200, NC = 3)               # distance-accumulating variant
    M_ABCdeep(L, numsim = 200, NC = 3, ae_epochs = 60)   # autoencoder embedding

## Hierarchy-based integration

Per-source hierarchies are merged into a single dendrogram.

- `HierarchicalEnsembleClustering` — combine per-source hierarchical clusterings into a consensus hierarchy.
- `EHC` — Ensemble Hierarchical Clustering (uses an external partitioner).

    HierarchicalEnsembleClustering(L, type = "data", distmeasure = DM,
                                   normalize = NM, method = ME)

## Factor, low-rank and spectral methods

Cluster a shared latent representation of the sources.

- `intNMF` — integrative non-negative matrix factorisation: a shared basis plus per-source coefficients; cluster the shared factors.
- `spectral_clustering` — spectral clustering of an affinity matrix (build one from a fused similarity, e.g. via `SimilarityMeasure()` or `SNF()`).
- `LUCID` — a wrapper for latent-cluster models that use an outcome (supervised integration); supply exposures `G`, omics `Z` and outcome `Y`.

    intNMF(L, k = K, nstart = 8)$cluster
    spectral_clustering(affinity = as.matrix(exp(-as.matrix(D1))), k = K)
    LUCID(G = exposures, Z = L, Y = outcome, K = 3)   # supervised; needs 'LUCIDus'

# Feature weighting and data nuggets

Not all features are equally informative. Several methods can weight features by their importance, and MosaiClusteR provides a robust, big-data-friendly weighting based on data nuggets — a compression of the objects into weighted representatives that resists outliers and scales to large `n`.

    dn <- create_data_nuggets(L[[1]], max_nuggets = 25)   # compress objects
    dn
    #> <data_nugget>
    #>   engine     : native
    #>   observations: 60 compressed into 25 nuggets
    #>   reduction  : 58.3%
    #>   weight range: 1 - 5 (obs per nugget)
    w  <- nugget_feature_weights(dn, type = "between")    # feature importance
    head(sort(w, decreasing = TRUE))
    #> src1_f008 src1_f004 src1_f012 src1_f006 src1_f019 src1_f003
    #>  2.449098  2.352650  2.284118  2.165043  2.103505  2.007162

Data nuggets can also be clustered directly, and used as the feature weighting in the ABC family (`weighting = "nugget"`):

    nugget_cluster(do.call(cbind, L), k = K, max_nuggets = 40)$cluster  # cluster nuggets
    Wkmeans(dn, k = K); Whclust(dn, k = K)                              # weighted k-means / hclust
    M_ABCpp(L, numsim = 200, NC = 3, weighting = c("nugget", "nugget")) # nugget-weighted

# Choosing the number of clusters

`SelectnrClusters()` scores a range of `k` (silhouette / gap-style criteria) so you do not have to guess. `ChooseCluster()` helps pick a cut of a fitted tree.

    sel <- SelectnrClusters(L, type = "data", distmeasure = DM, normalize = NM,
                            method = ME, nrclusters = 2:6)
    sel$Optimal_Nr_of_CLusters
    #>            Nr Clusters for Data 1 Nr Clusters for Data 2 Optimal nr of clusters
    #> NrClusters                      3                      3                      3

# Evaluating and comparing clusterings

Function | Purpose
--- | ---
`cluster_agreement(a, b)` | ARI, NMI, Jaccard, purity between two labellings
`compare_clusterings(D1, D2, NC)` | agreement between two integrated results
`mosaic_labels(fit, k)` | cut any fitted result into `k` labels
`CompareSilCluster`, `CompareSvsM` | silhouette-based comparison of solutions
`DetermineWeight_SilClust`, `DetermineWeight_SimClust` | data-driven source weights

    fit_a <- ADC(L, distmeasure = "euclidean", normalize = FALSE)
    fit_b <- SNF(L, type = "data", distmeasure = DM, normalize = NM, method = ME)
    compare_clusterings(fit_a$DistM, fit_b$DistM, NC = 3)$ARI
    #> NC = 3, linkage = ward.D2, n = 60
    #> Adjusted Rand Index : 1.0000
    #> Normalized Mut. Info: 1.0000
    #> Pair-Jaccard (same) : 1.0000
    #>       D2_c1 D2_c2 D2_c3
    #> D1_c1    20     0     0
    #> D1_c2     0    20     0
    #> D1_c3     0     0    20
    #> ARI
    #>   1
    cluster_agreement(mosaic_labels(fit_b, 3), truth)
    #>     ARI     NMI Jaccard
    #>       1       1       1

# Visualising results

MosaiClusteR includes a plotting suite for inspecting and comparing solutions. A fitted result carries a hierarchy you can draw directly:

    fit <- SNF(L, type = "data", distmeasure = DM, normalize = NM, method = ME)
    hc  <- stats::as.hclust(fit$Clust)
    plot(hc, labels = FALSE, main = "SNF consensus", xlab = "", sub = "")
    stats::rect.hclust(hc, k = 3, border = 2:4)

Other visualisations (all take fitted results or label vectors):

Function | Shows
--- | ---
`ComparePlot` | several solutions aligned side-by-side (needs `circlize`, `plotrix`)
`ClusterPlot`, `Cyclogram` | a single solution as a coloured tree / cyclogram
`SimilarityHeatmap`, `HeatmapPlot` | object-by-object similarity / feature heatmaps
`ProfilePlot`, `ContFeaturesPlot`, `BinFeaturesPlot_*` | per-cluster feature profiles
`BoxPlotDistance` | within- vs between-cluster distances
`ColorPalette`, `ColorsNames`, `ClusterCols`, `LabelCols` | consistent colour helpers

    ComparePlot(list("ADC" = fit_a, "SNF" = fit_b), nrclusters = 3)
    SimilarityHeatmap(fit_b$DistM)
    ProfilePlot(L[[1]], mosaic_labels(fit_b, 3))

# Characterising and tracking clusters

Once you have clusters, describe why they differ and follow them across solutions.

Function | Purpose
--- | ---
`CharacteristicFeatures`, `FeatSelection` | features that define each cluster
`FeaturesOfCluster` | the driving features of one cluster
`FindCluster`, `FindElement` | locate a cluster / object in a result
`TrackCluster` | follow a cluster across several solutions
`ReorderToReference` | align labels of one solution to a reference (Gale-Shapley)
`SharedComps`, `SimilarityMeasure` | shared members / similarity between solutions

    CharacteristicFeatures(L, mosaic_labels(fit_b, 3))
    ReorderToReference(reference = truth, tocompare = mosaic_labels(fit_a, 3))

# Biological interpretation (omics)

For omics data, MosaiClusteR connects clusters to genes and pathways. These functions rely on Bioconductor packages (`limma`, `MLP`, `biomaRt`, `org.Hs.eg.db`, …), declared under Suggests; install them to enable this layer. All examples here are illustrative.

Function | Purpose
--- | ---
`DiffGenes`, `DiffGenesSelection`, `FindGenes` | differential features per cluster
`PathwayAnalysis`, `Pathways`, `PathwaysIter`, `PathwaysSelection` | pathway enrichment per cluster
`PreparePathway`, `PlotPathways` | prepare / visualise pathway results
`Geneset.intersect`, `SharedGenesPathsFeat`, `SharedSelection*` | shared genes / pathways across solutions

    dg <- DiffGenes(L, mosaic_labels(fit_b, 3), geneexpr = L[[1]])
    pa <- PathwayAnalysis(L, mosaic_labels(fit_b, 3), geneexpr = L[[1]])
    PlotPathways(pa)

# Putting it together

A complete, reproducible analysis is short because every step shares the interface:

    L    <- my_sources                                   # list of matrices, objects in rows
    k    <- SelectnrClusters(L, type = "data", distmeasure = rep("euclidean", length(L)),
                             normalize = rep(FALSE, length(L)),
                             method = rep(list(NULL), length(L)),
                             nrclusters = 2:8)$Optimal_Nr_of_CLusters
    fit  <- SNF(L, type = "data", distmeasure = rep("euclidean", length(L)),
                normalize = rep(FALSE, length(L)), method = rep(list(NULL), length(L)))
    lab  <- mosaic_labels(fit, k)
    CharacteristicFeatures(L, lab)                        # what defines the clusters

Swap `SNF` for any other method above to compare paradigms on your own data.

    #> R version 4.6.0 (2026-04-24 ucrt)
    #> Platform: x86_64-w64-mingw32/x64
    #> Running under: Windows 11 x64 (build 26200)
    #>
    #> Matrix products: default
    #>   LAPACK version 3.12.1
    #>
    #> locale:
    #> [1] LC_COLLATE=C
    #> [2] LC_CTYPE=English_United Kingdom.utf8
    #> [3] LC_MONETARY=English_United Kingdom.utf8
    #> [4] LC_NUMERIC=C
    #> [5] LC_TIME=English_United Kingdom.utf8
    #>
    #> time zone: Europe/Paris
    #> tzcode source: internal
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] MosaiClusteR_0.1.1
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] ade4_1.7-24        Matrix_1.7-5       jsonlite_2.0.0     vegan_2.7-5
    #>  [5] compiler_4.6.0     gtools_3.9.5       Rcpp_1.1.1-1.1     alluvial_0.1-2
    #>  [9] parallel_4.6.0     cluster_2.1.8.2    jquerylib_0.1.4    splines_4.6.0
    #> [13] SNFtool_2.3.1      yaml_2.3.12        fastmap_1.2.0      lattice_0.22-9
    #> [17] R6_2.6.1           geometry_0.5.2     ExPosition_2.11.0  knitr_1.51
    #> [21] prettyGraphs_2.2.0 rbibutils_2.4.1    MASS_7.3-65        magic_1.6-1
    #> [25] bslib_0.11.0       rlang_1.2.0        cachem_1.1.0       xfun_0.57
    #> [29] sass_0.4.10        otel_0.2.0         cli_3.6.6          mgcv_1.9-4
    #> [33] Rdpack_2.6.6       digest_0.6.39      grid_4.6.0         permute_0.9-10
    #> [37] fastcluster_1.3.0  lifecycle_1.0.5    nlme_3.1-169       FD_1.0-12.5
    #> [41] evaluate_1.0.5     abind_1.4-8        ape_5.8-1          rmarkdown_2.31
    #> [45] matrixStats_1.5.0  tools_4.6.0        htmltools_0.5.9