mgcca

Generalized Canonical Correlation Analysis with missing individuals, computed out-of-core on HDF5 through BigDataStatMeth.

mgcca integrates several data tables into a small set of shared latent components, even when the tables describe overlapping but not identical sets of individuals — the setting of multi-omics integration, where a subject may be measured in some layers and not others. Missing individuals are handled analytically (van de Velden & Bijmolt, 2006), so every individual in the union is represented without imputation and without dropping incomplete cases.

The numerical core runs entirely in C++ on HDF5 files via the BigDataStatMeth API, so a single call, mgcca(), scales from small tables to full-omics data (hundreds of thousands of features) without ever loading a whole table into memory and without forming any variable-by-variable matrix.

How it works

flowchart TD
    A["Input tables<br/>(overlapping individuals)"] --> B["mgcca()<br/>import + scale in HDF5"]
    B -->|"p &lt; n"| C["Covariance route"]
    B -->|"p &ge; n"| D["Gram / dual route<br/>(p &gt;&gt; n)"]
    C --> E["Shared components Y<br/>+ scores, correlations, AVE"]
    D --> E
    E --> F[("HDF5 results + provenance<br/>reload via mgccaLoad()")]

    classDef input fill:#DCE6F1,stroke:#4C78A8,color:#22384f;
    classDef proc  fill:#DEEDDA,stroke:#54A24B,color:#2c4a25;
    classDef route fill:#FBE7D2,stroke:#E08A3C,color:#7a4410;
    classDef out   fill:#ECDDE8,stroke:#B279A2,color:#553049;
    class A input;
    class B proc;
    class C,D route;
    class E,F out;

Missing individuals are encoded per table, so a subject absent from a table simply does not contribute to it. Wide tables (p >= n, e.g. methylation) take the Gram route and never form a p x p matrix; results and the provenance needed to reload them are written back to the HDF5 file.

Installation

Install mgcca from Bioconductor:

if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("mgcca")

This pulls in every dependency automatically: the out-of-core engine BigDataStatMeth (CRAN) and the Bioconductor packages Rhdf5lib, SummarizedExperiment and impute. An HDF5 toolchain is required (provided by Rhdf5lib) together with a C++17 compiler.

Development version

The in-development sources live at https://github.com/isglobal-brge/mgcca; released versions are installed with the command above.

Quick start

library(mgcca)

# a shipped 3-table simulated cardiovascular example with missing individuals
data(cardiovascular)
X <- list(methylation = as.matrix(X1),
          clinical    = as.matrix(X2),
          other       = as.matrix(X3))
X <- lapply(X, function(m) { storage.mode(m) <- "double"; m })

# fit: import -> scale in-file -> compute shared components (all on HDF5)
fit <- mgcca(X, filename = tempfile(fileext = ".h5"),
             method = "solve", scores = TRUE)

fit                    # compact overview
summary(fit, top = 4)  # variance explained + top variables per component
plotIndividuals(fit)   # individuals on the two shared components (a ggplot)

Results are written to the HDF5 file together with a self-describing provenance manifest, so a finished analysis can be reopened later from the file alone:

fit <- mgccaLoad("analysis.h5")   # no R session or .rds needed

Features

Documentation

Method

mgcca implements Generalized Canonical Correlation Analysis with missing individuals: given tables X_j (individuals × variables) and per-table presence indicators K_j, it estimates shared components Y as the leading eigenvectors of a whitened sum of per-table projection operators. See the vignette and the references below for the formulation.

References

Citation

citation("mgcca")

License

MIT © Institute for Global Health (ISGlobal), Bioinformatics Research Group in Epidemiology (BRGE). See LICENSE.