mofa-r
MOFA2 — R bindings and plotting for Multi-Omics Factor Analysis. Use to fit MOFA from R (it calls the mofapy2 engine via reticulate/basilisk) and to run the standard downstream methods: get_factors, g
SKILL.mdskills/mofa-r/SKILL.md
GitHubMOFA2: R Bindings and Plotting
Foundation: mofa-framework is the router and holds all shared patterns. Jump directly to:
mofa-framework/references/mofa-architecture.md— Markov blanket, bilinearY ≈ ZW^T, ARD, VI loopmofa-framework/references/view-likelihoods.md— gaussian / bernoulli / poisson per viewmofa-framework/references/variance-explained.md— why per-(view, factor) R² is NOT a partitionmofa-framework/references/geometric-caveats.md— duality absent, no biplot, sign/order ambiguitymofa-framework/references/supplementary-projection-on-z.md— the L1 patch (arrows + level points on Z)mofa-framework/checks/pre-fit-checklist.md— pre-flight beforerun_mofa()
This file covers only the parts that differ for MOFA2 (R bindings + plotting).
When to Use MOFA2 (R)
- R/Bioconductor workflows where the rest of the pipeline (DE, GSEA, annotation) is already in R.
SingleCellExperiment/SummarizedExperiment/MultiAssayExperimentinputs — there are dedicated constructors.- Downstream associations (covariate correlation, ANOVA-style summaries) need to be done in R.
ggplot2/cowplot/patchworkcomposability matters — the returned plot objects are realggplotobjects.- You want the Python engine but prefer to script and orchestrate from R.
Limitations: requires a working Python install (basilisk-managed conda env or user-supplied reticulate env); no biplot; sign and factor order are non-canonical across runs.
Installation
# Core bindings — basilisk will lazily provision a conda env with mofapy2 the
# first time you call run_mofa(). See MOFA2/R/basilisk.R for the env spec.
BiocManager::install("MOFA2")
Manual Python env (skip basilisk):
# Point reticulate at a Python that already has mofapy2 installed.
reticulate::use_python("/opt/conda/envs/mofa/bin/python", required = TRUE)
library(MOFA2)
# Verify
reticulate::py_module_available("mofapy2")
The basilisk env spec lives in MOFA2/R/basilisk.R. The Python engine version is pinned there; if you upgrade mofapy2 in your own env, make sure it matches what MOFA2 expects, or stick to basilisk.
Quick Start
library(MOFA2)
# views_list is a NAMED list of feature x sample matrices, one per view
mofa <- create_mofa(views_list)
data_opts <- get_default_data_options(mofa)
model_opts <- get_default_model_options(mofa)
model_opts$num_factors <- 10
train_opts <- get_default_training_options(mofa)
train_opts$seed <- 42
train_opts$convergence_mode <- "medium"
mofa <- prepare_mofa(
mofa,
data_options = data_opts,
model_options = model_opts,
training_options = train_opts
)
mofa <- run_mofa(mofa, outfile = "mofa_fit.hdf5") # calls Python under the hood
# Downstream
Z <- get_factors(mofa)
r2 <- calculate_variance_explained(mofa)
plot_factors(mofa, factors = 1:2, color_by = "condition")
Verify it worked:
stopifnot(inherits(mofa, "MOFA"))
stopifnot(is.list(Z) || is.matrix(Z)) # Z is a list-per-group or a single matrix
stopifnot(length(get_weights(mofa)) == length(views_list)) # one W per view
Key API surfaces
Constructors:
create_mofa(data)— generic dispatch on a named list of matrices, a long data.frame, aMultiAssayExperiment, or a Seurat object. Returns an untrainedMOFAS4 object. (MOFA2/R/create_mofa.R)create_mofa_from_matrix(data, groups = NULL)— list of feature x sample matrices.create_mofa_from_MultiAssayExperiment(mae)— pulls assays as views.create_mofa_from_df(df)— long format with columnsfeature,view,sample,value(and optionalgroup).
Configuration and fitting:
prepare_mofa(mofa, data_options, model_options, training_options)(MOFA2/R/prepare_mofa.R) — sets the three option blocks; called once beforerun_mofa(). Useget_default_data_options(),get_default_model_options(),get_default_training_options()as starting templates and mutate.run_mofa(mofa, outfile, use_basilisk = TRUE)(MOFA2/R/run_mofa.R) — invokes the Python engine viabasilisk::basiliskRun()(or, ifuse_basilisk = FALSE, directly viareticulate). Writes HDF5 tooutfileand returns the trainedMOFAS4 object.load_model(file)(MOFA2/R/load_model.R) — deserialises an HDF5 produced elsewhere (mofapy2 directly, another R session, or a colleague). Round-trip:run_mofa(...)-> HDF5 ->load_model(HDF5)produces the same downstream interface.
Accessors:
get_factors(model, factors = "all", groups = "all", scale = FALSE, as.data.frame = FALSE)(MOFA2/R/get_methods.R:192-214) — returns Z. Withscale = TRUE, divides Z bymax(abs(Z))(line 209). This scaling is independent of anything done to W.get_weights(model, views = "all", factors = "all", scale = FALSE, as.data.frame = FALSE)(MOFA2/R/get_methods.R:248-272) — returns W as a list over views; each element is aD_m x Kmatrix. Withscale = TRUE, divides each view's W bymax(abs(W))(line 266). Independent of Z scaling.get_expectations(model, variable, ...)(MOFA2/R/get_methods.R:494+) — generic accessor over the node graph (Z, W, Tau, Alpha, ...).samples_metadata(mofa) <- df— attach sample metadata used by every plot/correlate function downstream. The row order ofdfmust matchsamples_names(mofa).
Plotting
What MOFA2 ships (R/plot_*.R, 25 plot_* man pages). Each returns a ggplot object you can + onto.
plot_factors(model, factors = c(1, 2), color_by = NULL, shape_by = NULL)(MOFA2/R/plot_factors.R:290-379) — sample scatter onF_alpha x F_beta. Categorical metadata enters ascolor_by/shape_byaesthetics (lines 322-323, 356) — not as a coordinate. Levels do not get points on the map.plot_factor(model, factor, color_by = NULL, ...)— single-factor beeswarm of Z values.plot_weights_scatter(model, view, factors = c(1, 2))(MOFA2/R/plot_weights.R:97-191) — feature scatter of W onF_alpha x F_beta. Different axes fromplot_factors; axes are scaled independently (lines 147-150). The two are not in a shared metric — see Foundation/geometric-caveats.plot_weights(model, view, factor, ...)(MOFA2/R/plot_weights.R:249+) — single-factor loading vector as a horizontal bar chart.plot_top_weights(model, view, factor, nfeatures = 10)(MOFA2/R/plot_weights.R:456+) — top-N features by|W|on one factor.plot_data_heatmap(model, factor, view, features)/plot_data_scatter(model, factor, view, features)— show the raw data behind a factor.plot_factor_cor(model)— correlation matrix of Z columns. Docs atMOFA2/R/plot_factors.R:471warn that "the model encourages the factors to be uncorrelated, so this function usually yields a diagonal correlation matrix" — usually, not exactly. Always run this once after a fit.plot_variance_explained(model)— heatmap of the R² returned bycalculate_variance_explained().
No biplot. ls MOFA2/man/ | grep -i biplot returns empty; grep -rn "biplot" MOFA2/ returns empty. There is no MOFA2 function that co-projects Z and W on shared axes — the architecture does not support it (no shared singular values). When you need a biplot-style co-plot, follow the L1 supplementary-projection patch documented in mofa-framework/references/supplementary-projection-on-z.md; the numeric machinery (correlate_factors_with_covariates, summarise_factors) already exists.
Associations and downstream
correlate_factors_with_covariates(model, covariates, plot = "log_pval", ...)(MOFA2/R/correlate_covariates.R:23-95) — Pearson correlation of each Z column against each metadata column; renders as acorrplotheatmap (line 78) or BH-adjusted-log10(p)heatmap (line 89). This is the Benzécri supplementary-continuous-variable formulag_alpha = cor(v, F_alpha)— the data plumbing exists, the geometric overlay does not.summarise_factors(model, group_by)(MOFA2/R/correlate_covariates.R:114-171) — per-level median of Z within each level of a discrete grouping; renders as ageom_tileheatmap (line 150). This is the Benzécri level-barycenter computation — same amputation as above (right number, wrong rendering).calculate_variance_explained(model, factors = "all", groups = "all", views = "all")(MOFA2/R/calculate_variance_explained.R:31-107) — returns a(group x view x factor)array of1 - SSE/SSTper cell. NOT a partition. Seemofa-framework/references/variance-explained.mdfor the four reasons (denominator is full Y, no orthogonality enforced, factors ordered post-hoc by total R², nocos²/ctrsemantics). Themax(0, .)floor at lines 73-76, 94-97 is the tell.predict(model, views = "all", factors = "all")(MOFA2/R/predict.R:29-78) — reconstructsY_hat = Z W^T + intercept(lines 61, 68). Useful for missing-value imputation; not for inertia accounting.
Common Issues
| Issue | Cause | Fix |
|---|---|---|
Error: mofapy2 not found on run_mofa() |
basilisk env not provisioned, or reticulate is pointed at a Python without mofapy2 |
Either let basilisk handle it (run_mofa(use_basilisk = TRUE), first call is slow), or set reticulate::use_python(...) to a Python where mofapy2 is installed before library(MOFA2). |
"Likelihood mismatch" warning at prepare_mofa() |
The auto-detector inferred the wrong likelihood (e.g. log-counts looked Gaussian but you wanted Poisson on raw counts) | Set model_opts$likelihoods <- c(rna = "gaussian", atac = "bernoulli", counts = "poisson") explicitly. See mofa-framework/references/view-likelihoods.md. |
plot_factors and plot_weights_scatter produce mismatched scales |
Expected. Z and W are scaled independently (get_methods.R:209 vs get_methods.R:266) and have no shared singular value |
Don't overlay them directly. Use the L1 patch from mofa-framework/references/supplementary-projection-on-z.md. |
| Sign or factor-order flips between runs | Expected. Bilinear Y ≈ ZW^T is sign-flip equivariant per factor; save_model.py:115-119 sorts factors by total R² but does not fix sign |
If cross-run comparison matters, impose a canonical sign downstream (e.g. flip so the largest absolute loading is positive). |
samples_metadata(mofa) <- df complains about row order, or aesthetics map to the wrong cells |
df must be in the same order as samples_names(mofa) (concatenation of per-group sample names) |
df <- df[match(samples_names(mofa), df$sample), ] before assignment. |
Σ_k r2[m, k] does not equal r2_total[m] |
Expected. Per-factor R² is computed against the full Y, not against the residual after k-1 factors (calculate_variance_explained.R:80-84) |
Use R² as a per-factor diagnostic, not as a budget. See mofa-framework/references/variance-explained.md. |
First run_mofa() is very slow / appears to hang |
basilisk is provisioning the conda env in the background; one-time cost | Wait it out, or pre-provision: BiocManager::install("MOFA2") followed by MOFA2:::.MOFA2_dependencies setup, or supply your own Python via reticulate::use_python() and run_mofa(use_basilisk = FALSE). |
Resources
- MOFA2 Bioconductor: https://bioconductor.org/packages/release/bioc/html/MOFA2.html
- GitHub: https://github.com/bioFAM/MOFA2
- Vignettes (in-source):
vignettes/getting_started_R.Rmd,vignettes/downstream_analysis.Rmd,vignettes/MEFISTO_temporal.Rmd - Website: https://biofam.github.io/MOFA2/
- MOFA+ paper: https://genomebiology.biomedcentral.com/articles/10.1186/s13059-020-02015-1
When not to use
- Do not use without a working Python install. MOFA2 R calls mofapy2 under the hood via reticulate/basilisk; the conda env is required.
- Do not expect a biplot. MOFA2 has 25
plot_*man pages and none of them co-projects Z and W; use the L1 supplementary-projection patch from mofa-framework/references/supplementary-projection-on-z.md. - Do not pass
get_factors(scale=TRUE)andget_weights(scale=TRUE)outputs into the same coordinate system; the two scalers are independentmax(|.|)normalisations, not the two halves of a shared SVD.
See also
mofa-frameworkmofa-cellularmuon-multimodal-analysis