# MOFA2: training a model in R

Ricard Argelaguet1* and Britta Velten2**

1European Bioinformatics Institute, Cambridge, UK
2German Cancer Research Center, Heidelberg, Germany

* ricard@ebi.ac.uk
** b.velten@dkfz-heidelberg.de

#### 2021-10-26

This vignette contains a detailed tutorial on how to train a MOFA model using R. A concise template script can be found here. Many more examples on application of MOFA to various multi-omics data sets can be found here.

# 1 Load libraries

    library(data.table)
    library(MOFA2)

# 2 Is MOFA the right method for my data?

MOFA (and factor analysis models in general) are useful to uncover variation in complex data sets that contain multiple sources of heterogeneity. This requires a relatively large sample size (at least ~15 samples). In addition, MOFA needs the multi-modal measurements to be derived from the same samples. It is fine if you have samples that are missing some data modality, but there has to be a significant degree of matched measurements.

# 3 Preprocessing the data

## 3.1 Normalisation

Proper normalisation of the data is critical. The model can handle three types of data: continuous (modelled with a gaussian likelihood), small counts (modelled with a Poisson likelihood) and binary measurements (modelled with a bernoulli likelihood). Non-gaussian likelihoods give non-optimal results, we recommend the user to apply data transformations to obtain continuous measurements. For example, for count-based data such as RNA-seq or ATAC-seq we recommend size factor normalisation + variance stabilisation (i.e. a log transformation).

## 3.2 Feature selection

It is strongly recommended that you select highly variable features (HVGs) per assay before fitting the model. This ensures a faster training and a more robust inference procedure. Also, for data modalities that have very different dimensionalities we suggest a stronger feature selection fort he bigger views, with the aim of reducing the feature imbalance between data modalities.

# 4 Create the MOFA object

To create a MOFA object you need to specify three dimensions: samples, features and view(s). Optionally, a group can also be specified for each sample (no group structure by default). MOFA objects can be created from a wide range of input formats, including:

- a list of matrices: this is recommended for relatively simple data.
- a long data.frame: this is recommended for complex data sets with multiple views and/or groups.
- MultiAssayExperiment: to connect with Bioconductor objects.
- Seurat: for single-cell genomics users. See this vignette

## 4.1 List of matrices

A list of matrices, where each entry corresponds to one view. Samples are stored in columns and features in rows.

Let’s simulate some data to start with

    data <- make_example_data(
      n_views = 2,
      n_samples = 200,
      n_features = 1000,
      n_factors = 10
    )[[1]]

    lapply(data,dim)

    ## $view_1
    ## [1] 1000  200
    ##
    ## $view_2
    ## [1] 1000  200

Create the MOFA object:

    MOFAobject <- create_mofa(data)

Plot the data overview

    plot_data_overview(MOFAobject)

In case you are using the multi-group functionality, the groups can be specified using the `groups` argument as a vector with the group ID for each sample. Keep in mind that the multi-group functionality is a rather advanced option that we discourage for beginners. For more details on how the multi-group inference works, read the FAQ section and check this vignette.

    N = ncol(data[[1]])
    groups = c(rep("A",N/2), rep("B",N/2))

    MOFAobject <- create_mofa(data, groups=groups)

Plot the data overview

    plot_data_overview(MOFAobject)

## 4.2 Long data.frame

A long data.frame with columns `sample`, `feature`, `view`, `group` (optional), `value` might be the best format for complex data sets with multiple omics and potentially multiple groups of data. Also, there is no need to add rows that correspond to missing data:

    filepath <- system.file("extdata", "test_data.RData", package = "MOFA2")
    load(filepath)

    head(dt)

    ##              sample          feature   view value
    ## 1: sample_0_group_1 feature_0_view_0 view_0  2.08
    ## 2: sample_1_group_1 feature_0_view_0 view_0  0.01
    ## 3: sample_2_group_1 feature_0_view_0 view_0 -0.11
    ## 4: sample_3_group_1 feature_0_view_0 view_0 -0.82
    ## 5: sample_4_group_1 feature_0_view_0 view_0 -1.13
    ## 6: sample_5_group_1 feature_0_view_0 view_0 -0.25

Create the MOFA object

    MOFAobject <- create_mofa(dt)

    ## Creating MOFA object from a data.frame...

    print(MOFAobject)

    ## Untrained MOFA model with the following characteristics:
    ##  Number of views: 2
    ##  Views names: view_0 view_1
    ##  Number of features (per view): 1000 1000
    ##  Number of groups: 1
    ##  Groups names: single_group
    ##  Number of samples (per group): 100
    ##

Plot data overview

    plot_data_overview(MOFAobject)

# 5 Define options

## 5.1 Define data options

- scale_groups: if groups have different ranges/variances, it is good practice to scale each group to unit variance. Default is `FALSE`
- scale_views: if views have different ranges/variances, it is good practice to scale each view to unit variance. Default is `FALSE`

    data_opts <- get_default_data_options(MOFAobject)
    head(data_opts)

    ## $scale_views
    ## [1] FALSE
    ##
    ## $scale_groups
    ## [1] FALSE
    ##
    ## $center_groups
    ## [1] TRUE
    ##
    ## $use_float32
    ## [1] FALSE
    ##
    ## $views
    ## [1] "view_0" "view_1"
    ##
    ## $groups
    ## [1] "single_group"

## 5.2 Define model options

- num_factors: number of factors
- likelihoods: likelihood per view (options are “gaussian”, “poisson”, “bernoulli”). Default is “gaussian”.
- spikeslab_factors: use spike-slab sparsity prior in the factors? Default is `FALSE`.
- spikeslab_weights: use spike-slab sparsity prior in the weights? Default is `TRUE`.
- ard_factors: use ARD prior in the factors? Default is `TRUE` if using multiple groups.
- ard_weights: use ARD prior in the weights? Default is `TRUE` if using multiple views.

Only change the default model options if you are familiar with the underlying mathematical model.

    model_opts <- get_default_model_options(MOFAobject)
    model_opts$num_factors <- 10
    head(model_opts)

    ## $likelihoods
    ##     view_0     view_1
    ## "gaussian" "gaussian"
    ##
    ## $num_factors
    ## [1] 10
    ##
    ## $spikeslab_factors
    ## [1] FALSE
    ##
    ## $spikeslab_weights
    ## [1] TRUE
    ##
    ## $ard_factors
    ## [1] FALSE
    ##
    ## $ard_weights
    ## [1] TRUE

## 5.3 Define training options

- maxiter: number of iterations. Default is 1000.
- convergence_mode: “fast” (default), “medium”, “slow”. For exploration, the fast mode is sufficient. For a final model, consider using medium" or even “slow”, but hopefully results should not change much.
- gpu_mode: use GPU mode? (needs cupy installed and a functional GPU).
- verbose: verbose mode?

    train_opts <- get_default_training_options(MOFAobject)
    head(train_opts)

    ## $maxiter
    ## [1] 1000
    ##
    ## $convergence_mode
    ## [1] "fast"
    ##
    ## $drop_factor_threshold
    ## [1] -1
    ##
    ## $verbose
    ## [1] FALSE
    ##
    ## $startELBO
    ## [1] 1
    ##
    ## $freqELBO
    ## [1] 5

# 6 Build and train the MOFA object

Prepare the MOFA object

    MOFAobject <- prepare_mofa(
      object = MOFAobject,
      data_options = data_opts,
      model_options = model_opts,
      training_options = train_opts
    )

Train the MOFA model. Remember that in this step the `MOFA2` R package connets with the `mofapy2` Python package using `reticulate`. This is the source of most problems when running MOFA. See our FAQ section if you have issues. The output is saved in the file specified as `outfile`. If none is specified, the output is saved in a temporary location.

    outfile = file.path(tempdir(),"model.hdf5")
    MOFAobject.trained <- run_mofa(MOFAobject, outfile)

    ## Warning: Output file /tmp/RtmpjrS6VY/model.hdf5 already exists, it will be replaced

    ## Connecting to the mofapy2 python package using reticulate (use_basilisk = FALSE)...
    ##     Please make sure to manually specify the right python binary when loading R with reticulate::use_python(..., force=TRUE) or the right conda environment with reticulate::use_condaenv(..., force=TRUE)
    ##     If you prefer to let us automatically install a conda environment with 'mofapy2' installed using the 'basilisk' package, please use the argument 'use_basilisk = TRUE'

    ## Warning in run_mofa(MOFAobject, outfile): The latest mofapy2 version is 0.6.4,
    ## you are using 0.6.3. Please upgrade with 'pip install mofapy2'

    ## Warning in run_mofa(MOFAobject, outfile): mofapy2_0.6.4 is not detected in the
    ## specified python binary, see reticulate::py_config(). Setting use_basilisk =
    ## TRUE...

    ## Connecting to the mofapy2 package using basilisk.
    ##     Set 'use_basilisk' to FALSE if you prefer to manually set the python binary using 'reticulate'.

If everything is successful, you should observe an output analogous to the following:

    ######################################
    ## Training the model with seed 1 ##
    ######################################

    Iteration 1: time=0.03, ELBO=-52650.68, deltaELBO=837116.802 (94.082647669%), Factors=10

    (...)

    Iteration 9: time=0.04, ELBO=-50114.43, deltaELBO=23.907 (0.002686924%), Factors=10

    #######################
    ## Training finished ##
    #######################

    Saving model in `/var/folders/.../model.hdf5.../tmp/RtmpjrS6VY/model.hdf5.

# 7 Downstream analysis

This finishes the tutorial on how to train a MOFA object from R. To continue with the downstream analysis, follow this tutorial

Session Info

    sessionInfo()

    ## R version 4.1.1 (2021-08-10)
    ## Platform: x86_64-pc-linux-gnu (64-bit)
    ## Running under: Ubuntu 20.04.3 LTS
    ##
    ## Matrix products: default
    ## BLAS:   /home/biocbuild/bbs-3.14-bioc/R/lib/libRblas.so
    ## LAPACK: /home/biocbuild/bbs-3.14-bioc/R/lib/libRlapack.so
    ##
    ## locale:
    ##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    ##  [3] LC_TIME=en_GB              LC_COLLATE=C
    ##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    ##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    ##  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    ## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ##  [1] data.table_1.14.2 pheatmap_1.0.12   forcats_0.5.1     stringr_1.4.0
    ##  [5] dplyr_1.0.7       purrr_0.3.4       readr_2.0.2       tidyr_1.1.4
    ##  [9] tibble_3.1.5      ggplot2_3.3.5     tidyverse_1.3.1   MOFA2_1.4.0
    ## [13] BiocStyle_2.22.0
    ##
    ## loaded via a namespace (and not attached):
    ##   [1] Rtsne_0.15           colorspace_2.0-2     ggsignif_0.6.3
    ##   [4] ellipsis_0.3.2       rio_0.5.27           rprojroot_2.0.2
    ##   [7] fs_1.5.0             rstudioapi_0.13      ggpubr_0.4.0
    ##  [10] farver_2.1.0         ggrepel_0.9.1        RSpectra_0.16-0
    ##  [13] fansi_0.5.0          mvtnorm_1.1-3        lubridate_1.8.0
    ##  [16] xml2_1.3.2           codetools_0.2-18     splines_4.1.1
    ##  [19] knitr_1.36           jsonlite_1.7.2       broom_0.7.9
    ##  [22] dbplyr_2.1.1         png_0.1-7            uwot_0.1.10
    ##  [25] HDF5Array_1.22.0     BiocManager_1.30.16  compiler_4.1.1
    ##  [28] httr_1.4.2           basilisk_1.6.0       backports_1.2.1
    ##  [31] assertthat_0.2.1     Matrix_1.3-4         fastmap_1.1.0
    ##  [34] cli_3.0.1            htmltools_0.5.2      tools_4.1.1
    ##  [37] gtable_0.3.0         glue_1.4.2           reshape2_1.4.4
    ##  [40] rappdirs_0.3.3       Rcpp_1.0.7           carData_3.0-4
    ##  [43] cellranger_1.1.0     jquerylib_0.1.4      vctrs_0.3.8
    ##  [46] rhdf5filters_1.6.0   nlme_3.1-153         xfun_0.27
    ##  [49] openxlsx_4.2.4       rvest_1.0.2          lifecycle_1.0.1
    ##  [52] rstatix_0.7.0        scales_1.1.1         basilisk.utils_1.6.0
    ##  [55] hms_1.1.1            MatrixGenerics_1.6.0 parallel_4.1.1
    ##  [58] rhdf5_2.38.0         RColorBrewer_1.1-2   yaml_2.2.1
    ##  [61] curl_4.3.2           reticulate_1.22      sass_0.4.0
    ##  [64] reshape_0.8.8        stringi_1.7.5        highr_0.9
    ##  [67] S4Vectors_0.32.0     corrplot_0.90        BiocGenerics_0.40.0
    ##  [70] filelock_1.0.2       zip_2.2.0            rlang_0.4.12
    ##  [73] pkgconfig_2.0.3      matrixStats_0.61.0   evaluate_0.14
    ##  [76] lattice_0.20-45      Rhdf5lib_1.16.0      labeling_0.4.2
    ##  [79] cowplot_1.1.1        tidyselect_1.1.1     RcppAnnoy_0.0.19
    ##  [82] here_1.0.1           GGally_2.1.2         plyr_1.8.6
    ##  [85] magrittr_2.0.1       bookdown_0.24        R6_2.5.1
    ##  [88] IRanges_2.28.0       magick_2.7.3         generics_0.1.1
    ##  [91] DelayedArray_0.20.0  DBI_1.1.1            mgcv_1.8-38
    ##  [94] pillar_1.6.4         haven_2.4.3          foreign_0.8-81
    ##  [97] withr_2.4.2          abind_1.4-5          dir.expiry_1.2.0
    ## [100] modelr_0.1.8         crayon_1.4.1         car_3.0-11
    ## [103] utf8_1.2.2           tzdb_0.1.2           rmarkdown_2.11
    ## [106] grid_4.1.1           readxl_1.3.1         reprex_2.0.1
    ## [109] digest_0.6.28        stats4_4.1.1         munsell_0.5.0
    ## [112] bslib_0.3.1