MosaiClusteR

An umbrella framework for multi-source & multi-omics clustering in R. One interface, many methods, a complete workflow — from raw modalities to interpretable subgroups.

MosaiClusteR — “MoSaIC” = Multi-Omics Source-Agnostic Integration Clustering in R — treats every data modality (transcriptome, methylome, proteome, fingerprints, targets, imaging, clinical…) as one tile of a larger picture, and assembles those tiles into a single coherent mosaic of sample structure. It unifies a large family of integrative clustering algorithms behind one consistent list‑of‑matrices interface, and wraps them in a complete analysis framework: preprocessing → single‑source baselines → integration across five paradigms → evaluation & interpretation.

No single algorithm is best across all data regimes, so MosaiClusteR gathers many methods on the same footing and gives you the tooling to choose between them: cluster‑number selection, agreement metrics, visual comparison, cluster characterisation, and — for omics — pathway and gene‑set interpretation. It also introduces a data‑nugget feature‑weighting scheme that offers a robust, Big‑Data‑friendly alternative to variance weighting.

Table of contents

• Why MosaiClusteR
• Installation
• 60‑second quick start
• The MoSaIC framework of use
• Method catalogue — every method, and when to use it
• Spotlight: M‑ABC and data nuggets
• Evaluation & comparison toolkit
• Datasets
• Design principles
• Citation
• References

Why MosaiClusteR

Multi‑omics and other multi‑source studies measure the same objects (patients, tumours, compounds, cells) through several heterogeneous lenses. No single modality tells the whole story, and the many integration algorithms in the literature live in scattered packages with incompatible inputs and outputs. MosaiClusteR fixes this:

• One input format. Every method takes a List of matrices over the same shared objects, with objects (samples) in rows and features in columns (n × m) — the same convention across the entire package, including the M‑ABC family. Distance‑matrix inputs (type = "dist") are orientation‑free.
• One output contract. Every method returns at least DistM (a dissimilarity matrix) and Clust (a hierarchical‑clustering object), so results are directly comparable and composable.
• Five paradigms, one roof. Direct, similarity‑based, graph‑based, voting‑based consensus, and hierarchy‑based integration — pick the right tool without leaving the package.
• A full workflow, not just algorithms. Normalisation, distances, partition extraction, agreement metrics (ARI/NMI/Jaccard), and method comparison are built in.

Installation

# install.packages("remotes")
remotes::install_github("lucp12891/MosaiClusteR")

MosaiClusteR ships C++ kernels for the M‑ABC family, so a C/C++ toolchain is needed to build from source (on Windows install Rtools; on macOS the Xcode command‑line tools). Every method has a pure‑R fallback, so the package still runs if a kernel is unavailable. A few methods rely on suggested packages that are only loaded when you call them:

# optional, enables extra methods / distances
install.packages(c("SNFtool", "datanugget", "WCluster", "lsa", "analogue", "FactoMineR"))

60‑second quick start

library(MosaiClusteR)
data(mosaic_toy)                       # two sources, 60 shared objects, 3 planted groups
L     <- mosaic_toy$List               # a list of matrices, objects in rows
truth <- mosaic_toy$truth

## ---- Integrate: every method shares one interface — swap to change paradigm
fit <- SNF(L, type = "data", distmeasure = c("euclidean", "euclidean"),
           normalize = c(FALSE, FALSE), method = list(NULL, NULL))

labels <- mosaic_labels(fit, k = 3)    # pull a flat partition from any fitted result
cluster_agreement(labels, truth)       # ARI / NMI / Jaccard / purity vs ground truth

## ---- Same score, a different paradigm — e.g. a neighbourhood method
cluster_agreement(NEMO(L, k = 3)$cluster, truth)

## ---- Compare two integrations directly
compare_clusterings(fit$DistM,
                    ADC(L, distmeasure = "euclidean", normalize = FALSE)$DistM, NC = 3)

That is the whole loop: integrate → extract → evaluate → compare — and the same three lines work for any of the methods below.

The MoSaIC framework of use

MosaiClusteR is organised as a four‑layer pipeline. You can enter at any layer, and every layer speaks the same List → {DistM, Clust} language.

            ┌─────────────────────────────────────────────────────────────┐
  LAYER 1   │  PREPROCESSING                                               │
  prepare   │  Normalization()  ·  Distance()                             │
            │  heterogeneous, differently-scaled modalities → comparable  │
            └─────────────────────────────────────────────────────────────┘
                              │  List of matrices (features × objects)
                              ▼
            ┌─────────────────────────────────────────────────────────────┐
  LAYER 2   │  SINGLE-SOURCE BASELINES                                     │
  explore   │  cluster each tile alone → see what each modality recovers  │
            │  motivates integration: agreements vs. modality-specific    │
            └─────────────────────────────────────────────────────────────┘
                              │
                              ▼
            ┌─────────────────────────────────────────────────────────────┐
  LAYER 3   │  INTEGRATION ENGINE  (five paradigms)                        │
  integrate │  Direct · Similarity · Graph · Voting-consensus · Hierarchy │
            │  M_ABCpp · M_ABCdist · WeightedClust · SNF · CEC · HEC · …   │
            └─────────────────────────────────────────────────────────────┘
                              │  {DistM, Clust}
                              ▼
            ┌─────────────────────────────────────────────────────────────┐
  LAYER 4   │  EVALUATION & INTERPRETATION                                 │
  conclude  │  mosaic_labels() · cluster_agreement() · compare_clusterings│
            │  ARI / NMI / Jaccard · cross-method consensus               │
            └─────────────────────────────────────────────────────────────┘

Choosing a layer‑3 method (decision shortcut):

• Want a fast, transparent baseline? → Direct (ADC) or Weighted (WeightedClust).
• Sources are noisy and complementary, genomic scale? → Similarity (SNF).
• Want stability under resampling / a novel robust ensemble? → Voting consensus (M_ABCpp, CEC, EvidenceAccumulation).
• Care about the hierarchy / dendrogram structure itself? → Hierarchy (HEC).
• Have very large N or heavy‑tailed data? → use weighting = "nugget" inside the M‑ABC family.

Method catalogue

Legend — a named function is implemented in this package · † requires an external graph‑partitioning executable (METIS) or MATLAB, not bundled · “—” marks methods interoperable with, or on the roadmap via, a reference package. All methods share the List → {DistM, Clust} contract and take the same objects‑in‑rows input.

1 · Direct clustering — combine first, then cluster

2 · Similarity‑based — fuse object‑by‑object similarity

3 · Graph‑based — partition an ensemble (hyper)graph

4 · Voting‑based consensus — let partitions vote

5 · Hierarchy‑based — consense the trees themselves

6 · Model‑based & factor integration

‡ LUCID wraps the LUCIDus package (a Suggests dependency).

Data reduction & weighting

Spotlight: M‑ABC and data nuggets

M‑ABC generalises the single‑source Aggregating Bundles of Clusters algorithm (Amaratunga et al. 2008) to many heterogeneous sources. For each source it repeats, numsim times: bootstrap the samples, draw a weighted subsample of features, cluster, and record co‑clustering. Per‑source evidence is accumulated into one consensus dissimilarity, then clustered.

The feature subsample is the heart of the method, and how features are weighted matters:

Why data nuggets? A data nugget summarises a group of observations by a centre, a weight (how many observations it represents) and a scale (its internal spread). Building nuggets over the samples and asking “which features separate the nugget centres?” yields a feature‑importance score that rewards real between‑group signal while discounting within‑nugget noise — and it scales to very large N because it works on M ≪ N representatives.

# Inspect the nugget compression and the weights it induces
dn <- create_data_nuggets(t(L[[1]]), max_nuggets = 25)
dn                                   # 60 obs -> 25 nuggets (reduction reported)
w  <- nugget_feature_weights(dn, type = "between")   # robust feature weights

# Drop straight into M-ABC
M_ABCpp(L, weighting = c("nugget", "nugget"),
      nugget_args = list(max_nuggets = 25, seed = 1))

If the reference datanugget package is installed you can swap in its engine with create_data_nuggets(x, engine = "datanugget"); otherwise the built‑in native engine is used (no extra dependency).

Evaluation & comparison toolkit

mosaic_labels(fit, k = 3)                 # extract a partition from any result
cluster_agreement(a, b)                   # ARI, NMI, pairwise Jaccard
compare_clusterings(D1, D2, NC = 3)       # cluster two dissimilarities & compare

cluster_agreement() rule of thumb (ARI): >0.90 excellent · 0.75–0.90 good · 0.50–0.75 moderate · <0.50 weak.

Downstream analysis & visualisation

The package also ships a full downstream analysis suite (Layer 4). These guard their heavier dependencies via Suggests and raise an informative error if one is missing.

Datasets

• mosaic_toy — a bundled two‑source example (60 shared samples, 3 planted groups) for instant experimentation and the test suite.
• mosaic_sim() — generate your own multi‑source data with controllable group structure, informative‑feature counts and effect size.

The methods are designed for, and have been evaluated on, multi‑omics benchmarks in the spirit of the LUCIDus simulated‑HELIX data, TCGA subtype cohorts, and the MCF7 compound–fingerprint–transcriptome panel used in the companion manuscript.

Design principles

1. Source‑agnostic. Methods do not care whether a tile is RNA, methylation, fingerprints or clinical scores.
2. Composable. A uniform {DistM, Clust} return makes any two methods comparable and any result re‑usable.
3. Honest dependencies. The core is pure R; heavyweight methods degrade gracefully when an optional package is absent.
4. Tested. A testthat suite covers the data‑nugget engine, every weighting scheme, the M‑ABC family, distances and metrics.

Citation

@Manual{MosaiClusteR2026,
  title  = {MosaiClusteR: An Umbrella Framework for Multi-Source and
            Multi-Omics Clustering},
  author = {Osang'ir, Bernard Isekah and Van Moerbeke, Marijke and
            Claesen, Jürgen and Gupta, Surya and Cabrera, Javier and
            Amaratunga, Dhammika and Shkedy, Ziv},
  year   = {2026},
  note   = {R package version 0.1.0},
  url    = {https://github.com/lucp12891/MosaiClusteR}
}

References

• Amaratunga, Cabrera & Shkedy (2008). Exploration and Analysis of DNA Microarray and Other High‑Dimensional Data. Wiley.
• Cherasia, Cabrera, Fernholz & Fernholz (2023). Data Nuggets in Supervised Learning. In Robust and Multivariate Statistical Methods, Springer, 429–449.
• Wang et al. (2014). Similarity Network Fusion… Nature Methods 11:333–337.
• Perualila‑Tan et al. (2016). Weighted similarity‑based clustering…
• Fodeh, Punch & Tan (2013). On unifying multi‑source information… Proteins.
• Zheng, Chen & Zheng (2014). A novel approach for hierarchical ensemble clustering. IEEE TPAMI.
• Strehl & Ghosh (2002); Fern & Brodley (2004); Gionis et al. (2007); Nguyen & Caruana (2007); Fred & Jain (2005); Iam‑On et al. (2010); Saeed et al. (2012/2014); Hossain et al. (2012).
• Zhang, Zhou, Xu & Liu (2022). Integrative clustering methods for multi‑omics data. WIREs Comput Stat 14:e1553. (SNF, NEMO, iCluster family, ab‑SNF, CIMLR review.)
• Zhao, Jia, Goodrich & Conti (2024). LUCIDus… The R Journal 16(2).

MosaiClusteR is an open, extensible framework — contributions of new integration methods, distances, and evaluation tools are very welcome.