Package 'MOFA2'

Re-exporting the pipe operator See magrittr::%>% for details.

Description

Re-exporting the pipe operator See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

depending on lhs and rhs

Description

Function to add the MOFA latent representation to a Seurat object

Usage

add_mofa_factors_to_seurat(
  mofa_object,
  seurat_object,
  views = "all",
  factors = "all"
)

Arguments

Details

This function calls the CreateDimReducObject function from Seurat to store the MOFA factors.

Value

Returns a Seurat object with the 'reductions' slot filled with the MOFA factors. Also adds, if calculated, the UMAP/TSNE obtained with the MOFA factors.

Examples

# Generate a simulated data set
MOFAexample <- make_example_data()

Description

This function calculates, *for each sample* how much each view contributes to its location in the latent manifold, what we call contribution scores

Usage

calculate_contribution_scores(
  object,
  views = "all",
  groups = "all",
  factors = "all",
  scale = TRUE
)

Arguments

Details

Contribution scores are calculated in three steps:

• Step 1calculate variance explained for each cell i and each view m ($R_{im}$), using all factors

• Step 2(optional) scale values by the total variance explained for each view

• Step 3calculate contribution score ($C_{im}$) for cell i and view m as:

  $C_{im} = \frac{R2_{im}}{\sum_{m} R2_{im}}$

Note that contribution scores can be calculated using any number of data modalities, but it is easier to interpret when you specify two.
Please note that this functionality is still experimental, contact the authors if you have questions.

Value

adds the contribution scores to the metadata slot (samples_metadata(MOFAobject)) and to the MOFAobject@cache slot

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
model <- calculate_contribution_scores(model)

Description

This function takes a trained MOFA model as input and calculates the proportion of variance explained (i.e. the coefficient of determinations (R^2)) by the MOFA factors across the different views.

Usage

calculate_variance_explained(
  object,
  views = "all",
  groups = "all",
  factors = "all"
)

Arguments

Value

a list with matrices with the amount of variation explained per factor and view.

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Calculate variance explained (R2)
r2 <- calculate_variance_explained(model)

# Plot variance explained values (view as x-axis, and factor as y-axis)
plot_variance_explained(model, x="view", y="factor")

# Plot variance explained values (view as x-axis, and group as y-axis)
plot_variance_explained(model, x="view", y="group")

# Plot variance explained values for factors 1 to 3
plot_variance_explained(model, x="view", y="group", factors=1:3)

# Scale R2 values
plot_variance_explained(model, max_r2 = 0.25)

Description

This function takes a trained MOFA model as input and calculates, **for each sample** the proportion of variance explained (i.e. the coefficient of determinations (R^2)) by the MOFA factors across the different views.

Usage

calculate_variance_explained_per_sample(
  object,
  views = "all",
  groups = "all",
  factors = "all"
)

Arguments

Value

a list with matrices with the amount of variation explained per sample and view.

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Calculate variance explained (R2)
r2 <- calculate_variance_explained_per_sample(model)

Description

MOFA factors are continuous in nature but they can be used to predict discrete clusters of samples.
The clustering can be performed in a single factor, which is equivalent to setting a manual threshold. More interestingly, it can be done using multiple factors, where multiple sources of variation are aggregated.
Importantly, this type of clustering is not weighted and does not take into account the different importance of the latent factors.

Usage

cluster_samples(object, k, factors = "all", ...)

Arguments

Details

In some cases, due to model technicalities, samples can have missing values in the latent factor space. In such a case, these samples are currently ignored in the clustering procedure.

Value

output from kmeans function

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Cluster samples in the factor space using factors 1 to 3 and K=2 clusters 
clusters <- cluster_samples(model, k=2, factors=1:3)

Compare different trained MOFA objects in terms of the final value of the ELBO statistics and number of inferred factors

Description

Different objects of MOFA are compared in terms of the final value of the ELBO statistics. For model selection the model with the highest ELBO value is selected.

Usage

compare_elbo(models, log = FALSE, return_data = FALSE)

Arguments

Value

A ggplot object or the underlying data.frame if return_data is TRUE

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model1 <- load_model(file)
model2 <- load_model(file)

# Compare ELBO between models
## Not run: compare_elbo(list(model1,model2))

Description

Different MOFA objects are compared in terms of correlation between their factors.

Usage

compare_factors(models, ...)

Arguments

Details

If assessing model robustness across trials, the output should look like a block diagonal matrix, suggesting that all factors are robustly detected in all model instances.

Value

Plots a heatmap of the Pearson correlation between latent factors across all input models.

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model1 <- load_model(file)
model2 <- load_model(file)

# Compare factors between models
compare_factors(list(model1,model2))

Description

Function to correlate factor values with external covariates.

Usage

correlate_factors_with_covariates(
  object,
  covariates,
  factors = "all",
  groups = "all",
  abs = FALSE,
  plot = c("log_pval", "r"),
  alpha = 0.05,
  return_data = FALSE,
  transpose = FALSE,
  ...
)

Arguments

Value

A corrplot (if plot=="r") or pheatmap (if plot=="log_pval") or the underlying data.frame if return_data is TRUE

Description

covariates_names: set and retrieve covariate names

Usage

covariates_names(object)

covariates_names(object) <- value

## S4 method for signature 'MOFA'
covariates_names(object)

## S4 replacement method for signature 'MOFA,vector'
covariates_names(object) <- value

Arguments

Value

character vector with the covariate names

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "MEFISTO_model.hdf5", package = "MOFA2")
model <- load_model(file)
covariates_names(model)

Description

Method to create a MOFA object. Depending on the input data format, this method calls one of the following functions:

• long data.frame: create_mofa_from_df

• List of matrices: create_mofa_from_matrix

• MultiAssayExperiment: create_mofa_from_MultiAssayExperiment

• Seurat: create_mofa_from_Seurat

• SingleCellExperiment: create_mofa_from_SingleCellExperiment

Please read the documentation of the corresponding function for more details on your specific data format.

Usage

create_mofa(data, groups = NULL, extract_metadata = TRUE, ...)

Arguments

Value

Returns an untrained MOFA object

Examples

# Using an existing simulated data with two groups and two views
file <- system.file("extdata", "test_data.RData", package = "MOFA2")

# Load data (in long data.frame format)
load(file) 
MOFAmodel <- create_mofa(dt)

Description

Method to create a MOFA object from a data.frame object

Usage

create_mofa_from_df(df, extract_metadata = TRUE)

Arguments

Value

Returns an untrained MOFA object

Examples

# Using an existing simulated data with two groups and two views
file <- system.file("extdata", "test_data.RData", package = "MOFA2")

# Load data (in long data.frame format)
load(file) 
MOFAmodel <- create_mofa_from_df(dt)

Description

Method to create a MOFA object from a list of matrices

Usage

create_mofa_from_matrix(data, groups = NULL)

Arguments

Value

Returns an untrained MOFA object

Examples

m <- make_example_data()
create_mofa_from_matrix(m$data)

Description

Method to create a MOFA object from a MultiAssayExperiment object

Usage

create_mofa_from_MultiAssayExperiment(
  mae,
  groups = NULL,
  extract_metadata = FALSE
)

Arguments

Value

Returns an untrained MOFA object

Description

Method to create a MOFA object from a Seurat object

Usage

create_mofa_from_Seurat(
  seurat,
  groups = NULL,
  assays = NULL,
  slot = "scale.data",
  features = NULL,
  extract_metadata = FALSE
)

Arguments

Value

Returns an untrained MOFA object

Description

Method to create a MOFA object from a SingleCellExperiment object

Usage

create_mofa_from_SingleCellExperiment(
  sce,
  groups = NULL,
  assay = "logcounts",
  extract_metadata = FALSE
)

Arguments

Value

Returns an untrained MOFA object

Description

factors_names: set and retrieve factor names

Usage

factors_names(object)

factors_names(object) <- value

## S4 method for signature 'MOFA'
factors_names(object)

## S4 replacement method for signature 'MOFA,vector'
factors_names(object) <- value

Arguments

Value

character vector with the factor names

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
factors_names(model)

Description

features_metadata: set and retrieve feature metadata

Usage

features_metadata(object)

features_metadata(object) <- value

## S4 method for signature 'MOFA'
features_metadata(object)

## S4 replacement method for signature 'MOFA,data.frame'
features_metadata(object) <- value

Arguments

Value

a data frame with sample metadata

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
features_metadata(model)

Description

features_names: set and retrieve feature names

Usage

features_names(object)

features_names(object) <- value

## S4 method for signature 'MOFA'
features_names(object)

## S4 replacement method for signature 'MOFA,list'
features_names(object) <- value

Arguments

Value

list of character vectors with the feature names for each view

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
features_names(model)

Description

Function to extract the covariates from a MOFA object using MEFISTO.

Usage

get_covariates(
  object,
  covariates = "all",
  as.data.frame = FALSE,
  warped = FALSE
)

Arguments

Value

a matrix with dimensions (samples,covariates). If as.data.frame is TRUE, a long-formatted data frame with columns (sample,factor,value)

Examples

# Using an existing trained model
file <- system.file("extdata", "MEFISTO_model.hdf5", package = "MOFA2")
model <- load_model(file)
covariates <- get_covariates(model)

Description

Fetch the input data

Usage

get_data(
  object,
  views = "all",
  groups = "all",
  features = "all",
  as.data.frame = FALSE,
  add_intercept = TRUE,
  denoise = FALSE,
  na.rm = TRUE
)

Arguments

Details

By default this function returns a list where each element is a data matrix with dimensionality (D,N) where D is the number of features and N is the number of samples.
Alternatively, if as.data.frame is TRUE, the function returns a long-formatted data frame with columns (view,feature,sample,value). Missing values are not included in the the long data.frame format by default. To include them use the argument na.rm=FALSE.

Value

A list of data matrices with dimensionality (D,N) or a data.frame (if as.data.frame is TRUE)

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Fetch data
data <- get_data(model)

# Fetch a specific view
data <- get_data(model, views = "view_0")

# Fetch data in data.frame format instead of matrix format
data <- get_data(model, as.data.frame = TRUE)

# Fetch centered data (do not add the feature intercepts)
data <- get_data(model, as.data.frame = FALSE)

# Fetch denoised data (do not add the feature intercepts)
data <- get_data(model, denoise = TRUE)

Description

Function to obtain the default data options.

Usage

get_default_data_options(object)

Arguments

Details

This function provides a default set of data options that can be modified and passed to the MOFA object in the prepare_mofa step (see example), i.e. after creating a MOFA object (using create_mofa) and before starting the training (using run_mofa) The data options are the following:

• scale_views: logical indicating whether to scale views to have the same unit variance. As long as the scale differences between the views is not too high, this is not required. Default is FALSE.

• scale_groups: logical indicating whether to scale groups to have the same unit variance. As long as the scale differences between the groups is not too high, this is not required. Default is FALSE.

• use_float32: logical indicating whether use float32 instead of float64 arrays to increase speed and memory usage. Default is FALSE.

Value

Returns a list with the default data options.

Examples

# Using an existing simulated data with two groups and two views
file <- system.file("extdata", "test_data.RData", package = "MOFA2")

# Load data dt (in data.frame format)
load(file) 

# Create the MOFA object
MOFAmodel <- create_mofa(dt)

# Load default data options
data_opts <- get_default_data_options(MOFAmodel)

# Edit some of the data options
data_opts$scale_views <- TRUE

# Prepare the MOFA object
MOFAmodel <- prepare_mofa(MOFAmodel, data_options = data_opts)

Description

Function to obtain the default options for the usage of MEFISTO covariates with MEFISTO

Usage

get_default_mefisto_options(object)

Arguments

Details

The options are the following:

• scale_cov: logical: Scale covariates?

• start_opt: integer: First iteration to start the optimisation of GP hyperparameters

• n_grid: integer: Number of points for the grid search in the optimisation of GP hyperparameters

• opt_freq: integer: Frequency of optimisation of GP hyperparameters

• sparseGP: logical: Use sparse GPs to speed up the optimisation of the GP parameters?

• frac_inducing: numeric between 0 and 1: Fraction of samples to use as inducing points (only relevant if sparseGP is TRUE)

• warping: logical: Activate warping functionality to align covariates between groups (requires a multi-group design)

• warping_freq: numeric: frequency of the warping (only relevant if warping is TRUE)

• warping_ref: A character specifying the reference group for warping (only relevant if warping is TRUE)

• warping_open_begin: logical: Warping: Allow for open beginning? (only relevant warping is TRUE)

• warping_open_end: logical: Warping: Allow for open end? (only relevant warping is TRUE)

• warping_groups: Assignment of groups to classes used for alignment (advanced option). Needs to be a vector of length number of samples, e.g. a column of samples_metadata, which needs to have the same value within each group. By default groups are used specified in 'create_mofa'.

• model_groups: logical: Model covariance structure across groups (for more than one group, otherwise FALSE)? If FALSE, we assume the same patterns in all groups.

• new_values: Values for which to predict the factor values (for interpolation / extrapolation). This should be numeric matrix in the same format with covariate(s) in rows and new values in columns. Default is NULL, leading to no interpolation.

Value

Returns a list with default options for the MEFISTO covariate(s) functionality.

Examples

# generate example data
dd <- make_example_data(sample_cov = seq(0,1,length.out = 200), n_samples = 200,
n_factors = 4, n_features = 200, n_views = 4, lscales = c(0.5, 0.2, 0, 0))
# input data
data <- dd$data
# covariate matrix with samples in columns
time <- dd$sample_cov
rownames(time) <- "time"

# create mofa and set covariates
sm <- create_mofa(data = dd$data)
sm <- set_covariates(sm, covariates = time)

MEFISTO_opt <- get_default_mefisto_options(sm)

Description

Function to obtain the default model options.

Usage

get_default_model_options(object)

Arguments

Details

This function provides a default set of model options that can be modified and passed to the MOFA object in the prepare_mofa step (see example), i.e. after creating a MOFA object (using create_mofa) and before starting the training (using run_mofa) The model options are the following:

• likelihoods: character vector with data likelihoods per view: 'gaussian' for continuous data (Default for all views), 'bernoulli' for binary data and 'poisson' for count data.

• num_factors: numeric value indicating the (initial) number of factors. Default is 15.

• spikeslab_factors: logical indicating whether to use spike and slab sparsity on the factors (Default is FALSE)

• spikeslab_weights: logical indicating whether to use spike and slab sparsity on the weights (Default is TRUE)

• ard_factors: logical indicating whether to use ARD sparsity on the factors (Default is TRUE only if using multiple groups)

• ard_weights: logical indicating whether to use ARD sparsity on the weights (Default is TRUE)

Value

Returns a list with the default model options.

Examples

# Using an existing simulated data with two groups and two views
file <- system.file("extdata", "test_data.RData", package = "MOFA2")

# Load data dt (in data.frame format)
load(file) 

# Create the MOFA object
MOFAmodel <- create_mofa(dt)

# Load default model options
model_opts <- get_default_model_options(MOFAmodel)

# Edit some of the model options
model_opts$num_factors <- 10
model_opts$spikeslab_weights <- FALSE

# Prepare the MOFA object
MOFAmodel <- prepare_mofa(MOFAmodel, model_options = model_opts)

Description

Function to obtain the default options for stochastic variational inference.

Usage

get_default_stochastic_options(object)

Arguments

Details

This function provides a default set of stochastic inference options that can be modified and passed to the MOFA object in the prepare_mofa step), i.e. after creating a MOFA object (using create_mofa) and before starting the training (using run_mofa) These options are only relevant when activating stochastic inference in training_options (see example). The stochastic inference options are the following:

• batch_size: numeric value indicating the batch size (as a fraction). Default is 0.5 (half of the data set).

• learning_rate: numeric value indicating the learning rate. Default is 1.0

• forgetting_rate: numeric indicating the forgetting rate. Default is 0.5

• start_stochastic: integer indicating the first iteration to start stochastic inference Default is 1

Value

Returns a list with default options

Examples

# Using an existing simulated data with two groups and two views
file <- system.file("extdata", "test_data.RData", package = "MOFA2")

# Load data dt (in data.frame format)
load(file) 

# Create the MOFA object
MOFAmodel <- create_mofa(dt)

# activate stochastic inference in training options
train_opts <- get_default_training_options(MOFAmodel)
train_opts$stochastic <- TRUE

# Load default stochastic options
stochastic_opts <- get_default_stochastic_options(MOFAmodel)

# Edit some of the stochastic options
stochastic_opts$learning_rate <- 0.75
stochastic_opts$batch_size <- 0.25

# Prepare the MOFA object
MOFAmodel <- prepare_mofa(MOFAmodel, 
  training_options = train_opts,
  stochastic_options = stochastic_opts
)

Description

Function to obtain the default training options.

Usage

get_default_training_options(object)

Arguments

Details

This function provides a default set of training options that can be modified and passed to the MOFA object in the prepare_mofa step (see example), i.e. after creating a MOFA object (using create_mofa) and before starting the training (using run_mofa) The training options are the following:

• maxiter: numeric value indicating the maximum number of iterations. Default is 1000. Convergence is assessed using the ELBO statistic.

• drop_factor_threshold: numeric indicating the threshold on fraction of variance explained to consider a factor inactive and drop it from the model. For example, a value of 0.01 implies that factors explaining less than 1% of variance (in each view) will be dropped. Default is -1 (no dropping of factors)

• convergence_mode: character indicating the convergence criteria, either "fast", "medium" or "slow", corresponding to 0.0005%, 0.00005% or 0.000005% deltaELBO change.

• verbose: logical indicating whether to generate a verbose output.

• startELBO: integer indicating the first iteration to compute the ELBO (default is 1).

• freqELBO: integer indicating the first iteration to compute the ELBO (default is 1).

• stochastic: logical indicating whether to use stochastic variational inference (only required for very big data sets, default is FALSE).

• gpu_mode: logical indicating whether to use GPUs (see details).

• gpu_device: integer indicating which GPU to use.

• seed: numeric indicating the seed for reproducibility (default is 42).

Value

Returns a list with default training options

Examples

# Using an existing simulated data with two groups and two views
file <- system.file("extdata", "test_data.RData", package = "MOFA2")

# Load data dt (in data.frame format)
load(file) 

# Create the MOFA object
MOFAmodel <- create_mofa(dt)

# Load default training options
train_opts <- get_default_training_options(MOFAmodel)

# Edit some of the training options
train_opts$convergence_mode <- "medium"
train_opts$startELBO <- 100
train_opts$seed <- 42

# Prepare the MOFA object
MOFAmodel <- prepare_mofa(MOFAmodel, training_options = train_opts)

Description

Extract dimensionalities from the model.

Usage

get_dimensions(object)

Arguments

Details

K indicates the number of factors, M indicates the number of views, D indicates the number of features (per view), N indicates the number of samples (per group) and C indicates the number of covariates.

Value

list containing the dimensionalities of the model

Examples

# Using an existing trained model
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
dims <- get_dimensions(model)

Description

Extract the value of the ELBO statistics after model training. This can be useful for model selection.

Usage

get_elbo(object)

Arguments

Details

This can be useful for model selection.

Value

Value of the ELBO

Examples

# Using an existing trained model
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
elbo <- get_elbo(model)

Description

Function to extract the expectations from the (variational) posterior distributions of a trained MOFA object.

Usage

get_expectations(object, variable, as.data.frame = FALSE)

Arguments

Details

Technical note: MOFA is a Bayesian model where each variable has a prior distribution and a posterior distribution. In particular, to achieve scalability we used the variational inference framework, thus true posterior distributions are replaced by approximated variational distributions. This function extracts the expectations of the variational distributions, which can be used as final point estimates to analyse the results of the model.
The priors and variational distributions of each variable are extensively described in the supplementary methods of the original paper.

Value

the output varies depending on the variable of interest:

• "Z"a matrix with dimensions (samples,factors). If as.data.frame is TRUE, a long-formatted data frame with columns (sample,factor,value)

• "W"a list of length (views) where each element is a matrix with dimensions (features,factors). If as.data.frame is TRUE, a long-formatted data frame with columns (view,feature,factor,value)

Examples

# Using an existing trained model
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
factors <- get_expectations(model, "Z")
weights <- get_expectations(model, "W")

Description

Extract the latent factors from the model.

Usage

get_factors(
  object,
  groups = "all",
  factors = "all",
  scale = FALSE,
  as.data.frame = FALSE
)

Arguments

Value

By default it returns the latent factor matrix of dimensionality (N,K), where N is number of samples and K is number of factors.
Alternatively, if as.data.frame is TRUE, returns a long-formatted data frame with columns (sample,factor,value).

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Fetch factors in matrix format (a list, one matrix per group)
factors <- get_factors(model)

# Concatenate groups
factors <- do.call("rbind",factors)

# Fetch factors in data.frame format instead of matrix format
factors <- get_factors(model, as.data.frame = TRUE)

Description

Extract the inferred group-group covariance matrix per factor

Usage

get_group_kernel(object)

Arguments

Details

This can be used only if covariates are passed to the MOFAobject upon creation and GP_factors is set to True.

Value

A list of group-group correlation matrices per factor

Description

Function to get the imputed data. It requires the previous use of the impute method.

Usage

get_imputed_data(
  object,
  views = "all",
  groups = "all",
  features = "all",
  as.data.frame = FALSE
)

Arguments

Details

Data is imputed from the generative model of MOFA.

Value

A list containing the imputed valued or a data.frame if as.data.frame is TRUE

Examples

# Using an existing trained model
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
model <- impute(model)
imputed <- get_imputed_data(model)

Description

Extract the interpolated factor values

Usage

get_interpolated_factors(object, as.data.frame = FALSE, only_mean = FALSE)

Arguments

Details

This can be used only if covariates are passed to the object upon creation, GP_factors is set to True and new covariates were passed for interpolation.

Value

By default, a nested list containing for each group a list with a matrix with the interpolated factor values ("mean"), their variance ("variance") and the values of the covariate at which interpolation took place ("new_values"). Alternatively, if as.data.frame is TRUE, returns a long-formatted data frame with columns containing the covariates and (factor, group, mean and variance).

Description

Extract the inferred lengthscale for each factor after model training.

Usage

get_lengthscales(object)

Arguments

Details

This can be used only if covariates are passed to the MOFAobject upon creation and GP_factors is set to True.

Value

A numeric vector containing the lengthscale for each factor.

Examples

# Using an existing trained model
file <- system.file("extdata", "MEFISTO_model.hdf5", package = "MOFA2")
model <- load_model(file)
ls <- get_lengthscales(model)

Description

Extract the inferred scale for each factor after model training.

Usage

get_scales(object)

Arguments

Details

This can be used only if covariates are passed to the MOFAobject upon creation and GP_factors is set to True.

Value

A numeric vector containing the scale for each factor.

Examples

# Using an existing trained model
file <- system.file("extdata", "MEFISTO_model.hdf5", package = "MOFA2")
model <- load_model(file)
s <- get_scales(model)

Description

Extract the latent factors from the model.

Usage

get_variance_explained(
  object,
  groups = "all",
  views = "all",
  factors = "all",
  as.data.frame = FALSE
)

Arguments

Value

A list of data matrices with variance explained per group or a data.frame (if as.data.frame is TRUE)

Examples

# Using an existing trained model
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Fetch variance explained values (in matrix format)
r2 <- get_variance_explained(model)

# Fetch variance explained values (in data.frame format)
r2 <- get_variance_explained(model, as.data.frame = TRUE)

Description

Extract the weights from the model.

Usage

get_weights(
  object,
  views = "all",
  factors = "all",
  abs = FALSE,
  scale = FALSE,
  as.data.frame = FALSE
)

Arguments

Value

By default it returns a list where each element is a loading matrix with dimensionality (D,K), where D is the number of features and K is the number of factors.
Alternatively, if as.data.frame is TRUE, returns a long-formatted data frame with columns (view,feature,factor,value).

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Fetch weights in matrix format (a list, one matrix per view)
weights <- get_weights(model)

# Fetch weights for factor 1 and 2 and view 1
weights <- get_weights(model, views = 1, factors = c(1,2))

# Fetch weights in data.frame format
weights <- get_weights(model, as.data.frame = TRUE)

Description

groups_names: set and retrieve group names

Usage

groups_names(object)

groups_names(object) <- value

## S4 method for signature 'MOFA'
groups_names(object)

## S4 replacement method for signature 'MOFA,character'
groups_names(object) <- value

Arguments

Value

character vector with the names for each sample group

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
groups_names(model)
groups_names(model) <- c("my_group")

Description

This function uses the latent factors and the loadings to impute missing values.

Usage

impute(
  object,
  views = "all",
  groups = "all",
  factors = "all",
  add_intercept = TRUE
)

Arguments

Details

MOFA generates a denoised and condensed low-dimensional representation of the data that captures the main sources of heterogeneity of the data. This representation can be used to reconstruct the data, simply using the equation Y = WX. For more details read the supplementary methods of the manuscript.
Note that with impute you can only generate the point estimates (the means of the posterior distributions). If you want to add uncertainity estimates (the variance) you need to set impute=TRUE in the training options. See get_default_training_options.

Value

This method fills the imputed_data slot by replacing the missing values in the input data with the model predictions.

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Impute missing values in all data modalities
imputed_data <- impute(model, views = "all")

# Impute missing values in all data modalities using factors 1:3
imputed_data <- impute(model, views = "all", factors = 1:3)

Description

Function to interpolate factors in MEFISTO based on new covariate values.

Usage

interpolate_factors(object, new_values)

Arguments

Details

This function requires the functional MEFISTO framework to be used in training. Use set_covariates and specify mefisto_options when preparing the training using prepare_mofa. Currenlty, only the mean of the interpolation is provided from R.

Value

Returns the MOFA with interpolated factor values filled in the corresponding slot (interpolatedZ)

Examples

# Using an existing trained model
file <- system.file("extdata", "MEFISTO_model.hdf5", package = "MOFA2")
model <- load_model(file)
model <- interpolate_factors(model, new_values = seq(0,1.1,0.01))

Description

Method to load a trained MOFA
The training of mofa is done using a Python framework, and the model output is saved as an .hdf5 file, which has to be loaded in the R package.

Usage

load_model(
  file,
  sort_factors = TRUE,
  on_disk = FALSE,
  load_data = TRUE,
  remove_outliers = FALSE,
  remove_inactive_factors = TRUE,
  verbose = FALSE,
  load_interpol_Z = FALSE
)

Arguments

Value

a MOFA model

Examples

#' # Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

Description

Function to simulate an example multi-view multi-group data set according to the generative model of MOFA2.

Usage

make_example_data(
  n_views = 3,
  n_features = 100,
  n_samples = 50,
  n_groups = 1,
  n_factors = 5,
  likelihood = "gaussian",
  lscales = 1,
  sample_cov = NULL,
  as.data.frame = FALSE
)

Arguments

Value

Returns a list containing the simulated data and simulation parameters.

Examples

# Generate a simulated data set
MOFAexample <- make_example_data()

Description

The MOFA is an S4 class used to store all relevant data to analyse a MOFA model

Slots

data

The input data

intercepts

Feature intercepts

samples_metadata

Samples metadata

features_metadata

Features metadata.

imputed_data

The imputed data.

expectations

expected values of the factors and the loadings.

dim_red

non-linear dimensionality reduction manifolds.

training_stats

model training statistics.

data_options

Data processing options.

training_options

Model training options.

stochastic_options

Stochastic variational inference options.

model_options

Model options.

mefisto_options

Options for the use of MEFISO

dimensions

Dimensionalities of the model: M for the number of views, G for the number of groups, N for the number of samples (per group), C for the number of covariates per sample, D for the number of features (per view), K for the number of factors.

on_disk

Logical indicating whether data is loaded from disk.

cache

Cache.

status

Auxiliary variable indicating whether the model has been trained.

covariates

optional slot to store sample covariate for training in MEFISTO

covariates_warped

optional slot to store warped sample covariate for training in MEFISTO

interpolated_Z

optional slot to store interpolated factor values (used only with MEFISTO)

Description

Function to plot the alignment learnt by MEFISTO for the covariate values between different groups

Usage

plot_alignment(object)

Arguments

Details

This function requires the functional MEFISTO framework to be used in training. Use set_covariates and specify mefisto_options when preparing the training using prepare_mofa.

Value

ggplot object showing the alignment

Description

A Fancy printing method

Usage

plot_ascii_data(object, nonzero = FALSE)

Arguments

Details

This function is helpful to get an overview of the structure of the data as a text output

Value

None

Examples

# Using an existing trained model
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
plot_ascii_data(model)

Description

Function to plot a heatmap of the data for relevant features, typically the ones with high weights.

Usage

plot_data_heatmap(
  object,
  factor,
  view = 1,
  groups = "all",
  features = 50,
  annotation_features = NULL,
  annotation_samples = NULL,
  transpose = FALSE,
  imputed = FALSE,
  denoise = FALSE,
  max.value = NULL,
  min.value = NULL,
  ...
)

Arguments

Details

One of the first steps for the annotation of a given factor is to visualise the corresponding weights, using for example plot_weights or plot_top_weights.
However, one might also be interested in visualising the direct relationship between features and factors, rather than looking at "abstract" weights.
This function generates a heatmap for selected features, which should reveal the underlying pattern that is captured by the latent factor.
A similar function for doing scatterplots rather than heatmaps is plot_data_scatter.

Value

A pheatmap object

Examples

# Using an existing trained model
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
plot_data_heatmap(model, factor = 1, show_rownames = FALSE, show_colnames = FALSE)

Description

Function to do a tile plot showing the missing value structure of the input data

Usage

plot_data_overview(
  object,
  covariate = 1,
  colors = NULL,
  show_covariate = FALSE,
  show_dimensions = TRUE
)

Arguments

Details

This function is helpful to get an overview of the structure of the data. It shows the model dimensionalities (number of samples, groups, views and features) and it indicates which measurements are missing.

Value

A ggplot object

Examples

# Using an existing trained model
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
plot_data_overview(model)

Description

Function to do a scatterplot of features against factor values.

Usage

plot_data_scatter(
  object,
  factor = 1,
  view = 1,
  groups = "all",
  features = 10,
  sign = "all",
  color_by = "group",
  legend = TRUE,
  alpha = 1,
  shape_by = NULL,
  stroke = NULL,
  dot_size = 2.5,
  text_size = NULL,
  add_lm = TRUE,
  lm_per_group = TRUE,
  imputed = FALSE
)

Arguments

Details

One of the first steps for the annotation of factors is to visualise the weights using plot_weights or plot_top_weights. However, one might also be interested in visualising the direct relationship between features and factors, rather than looking at "abstract" weights.
A similar function for doing heatmaps rather than scatterplots is plot_data_heatmap.

Value

A ggplot object

Examples

# Using an existing trained model
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
plot_data_scatter(model)

Description

Function to do a scatterplot of features against sample covariate values.

Usage

plot_data_vs_cov(
  object,
  covariate = 1,
  warped = TRUE,
  factor = 1,
  view = 1,
  groups = "all",
  features = 10,
  sign = "all",
  color_by = "group",
  legend = TRUE,
  alpha = 1,
  shape_by = NULL,
  stroke = NULL,
  dot_size = 2.5,
  text_size = NULL,
  add_lm = FALSE,
  lm_per_group = FALSE,
  imputed = FALSE,
  return_data = FALSE
)

Arguments

Details

One of the first steps for the annotation of factors is to visualise the weights using plot_weights or plot_top_weights and inspect the relationshio of the factor to the covariate(s) using plot_factors_vs_cov. However, one might also be interested in visualising the direct relationship between features and covariate(s), rather than looking at "abstract" weights and possibly look at the interpolated and extrapolated values by setting imputed to True.

Value

Returns a ggplot2 object or the underlying dataframe if return_data is set to TRUE.

Examples

# Using an existing trained model
file <- system.file("extdata", "MEFISTO_model.hdf5", package = "MOFA2")
model <- load_model(file)
plot_data_vs_cov(model, factor = 3, features = 2)

Description

Plot dimensionality reduction based on MOFA factors

Usage

plot_dimred(
  object,
  method = c("UMAP", "TSNE"),
  groups = "all",
  show_missing = TRUE,
  color_by = NULL,
  shape_by = NULL,
  color_name = NULL,
  shape_name = NULL,
  label = FALSE,
  dot_size = 1.5,
  stroke = NULL,
  alpha_missing = 1,
  legend = TRUE,
  rasterize = FALSE,
  return_data = FALSE,
  ...
)

Arguments

Details

This function plots dimensionality reduction projections that are stored in the dim_red slot. Typically this contains UMAP or t-SNE projections computed using run_tsne or run_umap, respectively.

Value

Returns a ggplot2 object or a long data.frame (if return_data is TRUE)

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Run UMAP
model <- run_umap(model)

# Plot UMAP
plot_dimred(model, method = "UMAP")

# Plot UMAP, colour by Factor 1 values
plot_dimred(model, method = "UMAP", color_by = "Factor1")

# Plot UMAP, colour by the values of a specific feature
plot_dimred(model, method = "UMAP", color_by = "feature_0_view_0")

Description

Method to plot the results of the gene set Enrichment Analyisis

Usage

plot_enrichment(
  enrichment.results,
  factor,
  alpha = 0.1,
  max.pathways = 25,
  text_size = 1,
  dot_size = 5
)

Arguments

Details

it requires run_enrichment to be run beforehand.

Value

a ggplot2 object

Description

Method to plot a detailed output of the Feature Set Enrichment Analyisis (FSEA).
Each row corresponds to a significant pathway, sorted by statistical significance, and each dot corresponds to a gene.
For each pathway, we display the top genes of the pathway sorted by the corresponding feature statistic (by default, the absolute value of the weight) The top genes with the highest statistic (max.genes argument) are displayed and labeled in black. The remaining genes are colored in grey.

Usage

plot_enrichment_detailed(
  enrichment.results,
  factor,
  alpha = 0.1,
  max.genes = 5,
  max.pathways = 10,
  text_size = 3
)

Arguments

Value

a ggplot2 object

Description

This method generates a heatmap with the adjusted p.values that result from the the feature set enrichment analysis. Rows are feature sets and columns are factors.

Usage

plot_enrichment_heatmap(
  enrichment.results,
  alpha = 0.1,
  cap = 1e-50,
  log_scale = TRUE,
  ...
)

Arguments

Value

produces a heatmap

Description

Beeswarm plot of the latent factor values.

Usage

plot_factor(
  object,
  factors = 1,
  groups = "all",
  group_by = "group",
  color_by = "group",
  shape_by = NULL,
  add_dots = TRUE,
  dot_size = 2,
  dot_alpha = 1,
  add_violin = FALSE,
  violin_alpha = 0.5,
  color_violin = TRUE,
  add_boxplot = FALSE,
  boxplot_alpha = 0.5,
  color_boxplot = TRUE,
  show_missing = TRUE,
  scale = FALSE,
  dodge = FALSE,
  color_name = "",
  shape_name = "",
  stroke = NULL,
  legend = TRUE,
  rasterize = FALSE
)

Arguments

Details

One of the main steps for the annotation of factors is to visualise and color them using known covariates or phenotypic data.
This function generates a Beeswarm plot of the sample values in a given latent factor.
Similar functions are plot_factors for doing scatter plots.

Value

Returns a ggplot2

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Plot Factors 1 and 2 and colour by "group"
plot_factor(model, factors = c(1,2), color_by="group")

# Plot Factor 3 and colour by the value of a specific feature
plot_factor(model, factors = 3, color_by="feature_981_view_1")

# Add violin plots
plot_factor(model, factors = c(1,2), color_by="group", add_violin = TRUE)

# Scale factor values from -1 to 1
plot_factor(model, factors = c(1,2), scale = TRUE)

Description

Function to plot the correlation matrix between the latent factors.

Usage

plot_factor_cor(object, method = "pearson", ...)

Arguments

Details

This method plots the correlation matrix between the latent factors.
The model encourages the factors to be uncorrelated, so this function usually yields a diagonal correlation matrix.
However, it is not a hard constraint such as in Principal Component Analysis and correlations between factors can occur, particularly with large number factors.
Generally, correlated factors are redundant and should be avoided, as they make interpretation harder. Therefore, if you have too many correlated factors we suggest you try reducing the number of factors.

Value

Returns a symmetric matrix with the correlation coefficient between every pair of factors.

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Plot correlation between all factors
plot_factor_cor(model)

Description

Scatterplot of the values of two latent factors.

Usage

plot_factors(
  object,
  factors = c(1, 2),
  groups = "all",
  show_missing = TRUE,
  scale = FALSE,
  color_by = NULL,
  shape_by = NULL,
  color_name = NULL,
  shape_name = NULL,
  dot_size = 2,
  alpha = 1,
  legend = TRUE,
  stroke = NULL,
  return_data = FALSE
)

Arguments

Details

One of the first steps for the annotation of factors is to visualise and group/color them using known covariates such as phenotypic or clinical data. This method generates a single scatterplot for the combination of two latent factors. TO-FINISH... plot_factors for doing Beeswarm plots for factors.

Value

Returns a ggplot2 object

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Scatterplot of factors 1 and 2
plot_factors(model, factors = c(1,2))

# Shape dots by a column in the metadata
plot_factors(model, factors = c(1,2), shape_by="group")

# Scale factor values from -1 to 1
plot_factors(model, factors = c(1,2), scale = TRUE)

Description

Scatterplots of a factor's values againt the sample covariates

Usage

plot_factors_vs_cov(
  object,
  factors = "all",
  covariates = NULL,
  warped = TRUE,
  show_missing = TRUE,
  scale = FALSE,
  color_by = NULL,
  shape_by = NULL,
  color_name = NULL,
  shape_name = NULL,
  dot_size = 1.5,
  alpha = 1,
  stroke = NULL,
  legend = TRUE,
  rotate_x = FALSE,
  rotate_y = FALSE,
  return_data = FALSE,
  show_variance = FALSE
)

Arguments

Details

To investigate the factors pattern along the covariates (such as time or a spatial coordinate) this function an be used to plot a scatterplot of the factor againt the values of each covariate

Value

Returns a ggplot2 object

Examples

# Using an existing trained model
file <- system.file("extdata", "MEFISTO_model.hdf5", package = "MOFA2")
model <- load_model(file)
plot_factors_vs_cov(model)

Description

Heatmap plot showing the group-group correlations inferred by the model per factor

Usage

plot_group_kernel(object, factors = "all", groups = "all", ...)

Arguments

Details

The heatmap gives insight into the clustering of the patterns that factors display along the covariate in each group. A correlation of 1 indicates that the module caputred by a factor shows identical patterns across groups, a correlation of zero that it shows distinct patterns, a negative correlation that the patterns go in opposite directions.

Value

Returns a ggplot,gg object containing the heatmaps

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "MEFISTO_model.hdf5", package = "MOFA2")
model <- load_model(file)
plot_group_kernel(model)

Description

make a plot of interpolated covariates versus covariate

Usage

plot_interpolation_vs_covariate(
  object,
  covariate = 1,
  factors = "all",
  only_mean = TRUE,
  show_observed = TRUE
)

Arguments

Details

to be filled

Value

Returns a ggplot2 object

Examples

# Using an existing trained model
file <- system.file("extdata", "MEFISTO_model.hdf5", package = "MOFA2")
model <- load_model(file)
model <- interpolate_factors(model, new_values = seq(0,1.1,0.1))
plot_interpolation_vs_covariate(model, covariate = "time", factors = 1)

Description

Barplot indicating a sharedness score (between 0 (non-shared) and 1 (shared)) per factor

Usage

plot_sharedness(object, factors = "all", color = "#B8CF87")

Arguments

Details

The sharedness score is calculated as the distance of the learnt group correlation matrix to the identity matrix in terms of the mean absolute distance on the off-diagonal elements.

Value

Returns a ggplot2 object

Description

Barplot indicating a smoothness score (between 0 (non-smooth) and 1 (smooth)) per factor

Usage

plot_smoothness(object, factors = "all", color = "cadetblue")

Arguments

Details

The smoothness score is given by the scale parameter for the underlying Gaussian process of each factor.

Value

Returns a ggplot2 object

Examples

# Using an existing trained model
file <- system.file("extdata", "MEFISTO_model.hdf5", package = "MOFA2")
model <- load_model(file)
smoothness_bars <- plot_smoothness(model)

Description

Plot top weights for a given factor and view.

Usage

plot_top_weights(
  object,
  view = 1,
  factors = 1,
  nfeatures = 10,
  abs = TRUE,
  scale = TRUE,
  sign = "all"
)

Arguments

Details

An important step to annotate factors is to visualise the corresponding feature weights.
This function displays the top features with highest loading whereas the function plot_top_weights plots all weights for a given latent factor and view.
Importantly, the weights of the features within a view have relative values and they should not be interpreted in an absolute scale. Therefore, for interpretability purposes we always recommend to scale the weights with scale=TRUE.

Value

Returns a ggplot2 object

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Plot top weights for Factors 1 and 2 and View 1
plot_top_weights(model, view = 1, factors = c(1,2))

# Do not take absolute value
plot_weights(model, abs = FALSE)

Description

plots the variance explained by the MOFA factors across different views and groups, as specified by the user. Consider using cowplot::plot_grid(plotlist = ...) to combine the multiple plots that this function generates.

Usage

plot_variance_explained(
  object,
  x = "view",
  y = "factor",
  split_by = NA,
  plot_total = FALSE,
  factors = "all",
  min_r2 = 0,
  max_r2 = NULL,
  legend = TRUE,
  use_cache = TRUE,
  ...
)

Arguments

Value

A list of ggplot objects (if plot_total is TRUE) or a single ggplot object

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Calculate variance explained (R2)
r2 <- calculate_variance_explained(model)

# Plot variance explained values (view as x-axis, and factor as y-axis)
plot_variance_explained(model, x="view", y="factor")

# Plot variance explained values (view as x-axis, and group as y-axis)
plot_variance_explained(model, x="view", y="group")

# Plot variance explained values for factors 1 to 3
plot_variance_explained(model, x="view", y="group", factors=1:3)

# Scale R2 values
plot_variance_explained(model, max_r2=0.25)

Description

This function plots the variance explained by the smooth components (Gaussian processes) underlying the factors in MEFISTO across different views and groups, as specified by the user.

Usage

plot_variance_explained_by_covariates(
  object,
  factors = "all",
  x = "view",
  y = "factor",
  split_by = NA,
  min_r2 = 0,
  max_r2 = NULL,
  compare_total = FALSE,
  legend = TRUE
)

Arguments

Details

Note that this function requires the use of MEFISTO. To activate the functional MEFISTO framework, specify mefisto_options when preparing the training using prepare_mofa

Value

A list of ggplot objects (if compare_total is TRUE) or a single ggplot object. Consider using cowplot::plot_grid(plotlist = ...) to combine the multiple plots that this function generates.

Examples

# load_model
file <- system.file("extdata", "MEFISTO_model.hdf5", package = "MOFA2")
model <- load_model(file)
plot_variance_explained_by_covariates(model)

# compare to toal variance explained
plist <- plot_variance_explained_by_covariates(model, compare_total = TRUE)
cowplot::plot_grid(plotlist = plist)

Description

Plot variance explained by the model for a set of features

Returns a tile plot with a group on the X axis and a feature along the Y axis

Usage

plot_variance_explained_per_feature(
  object,
  view,
  features = 10,
  split_by_factor = FALSE,
  group_features_by = NULL,
  groups = "all",
  factors = "all",
  min_r2 = 0,
  max_r2 = NULL,
  legend = TRUE,
  return_data = FALSE,
  ...
)

Arguments

Value

ggplot object

Examples

# Using an existing trained model
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
plot_variance_explained_per_feature(model, view = 1)

Description

An important step to annotate factors is to visualise the corresponding feature weights.
This function plots all weights for a given latent factor and view, labeling the top ones.
In contrast, the function plot_top_weights displays only the top features with highest loading.

Usage

plot_weights(
  object,
  view = 1,
  factors = 1,
  nfeatures = 10,
  color_by = NULL,
  shape_by = NULL,
  abs = FALSE,
  manual = NULL,
  color_manual = NULL,
  scale = TRUE,
  dot_size = 1,
  text_size = 5,
  legend = TRUE,
  return_data = FALSE
)

Arguments

Value

A ggplot object or a data.frame if return_data is TRUE

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Plot distribution of weights for Factor 1 and View 1
plot_weights(model, view = 1, factors = 1)

# Plot distribution of weights for Factors 1 to 3 and View 1
plot_weights(model, view = 1, factors = 1:3)

# Take the absolute value and highlight the top 10 features
plot_weights(model, view = 1, factors = 1, nfeatures = 10, abs = TRUE)

# Change size of dots and text
plot_weights(model, view = 1, factors = 1, text_size = 5, dot_size = 1)

Description

Function to visualize the weights for a given set of factors in a given view.
This is useful to visualize the overall pattern of the weights but not to individually characterise the factors.
To inspect the weights of individual factors, use the functions plot_weights and plot_top_weights

Usage

plot_weights_heatmap(
  object,
  view = 1,
  features = "all",
  factors = "all",
  threshold = 0,
  ...
)

Arguments

Value

A pheatmap object

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
plot_weights_heatmap(model)

Description

Scatterplot of the weights values for two factors

Usage

plot_weights_scatter(
  object,
  factors,
  view = 1,
  color_by = NULL,
  shape_by = NULL,
  dot_size = 1,
  name_color = "",
  name_shape = "",
  show_missing = TRUE,
  abs = FALSE,
  scale = TRUE,
  legend = TRUE
)

Arguments

Details

One of the first steps for the annotation of factors is to visualise and group/color them using known covariates such as phenotypic or clinical data. This method generates a single scatterplot for the combination of two latent factors.

Value

Returns a ggplot2 object

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
plot_weights_scatter(model, factors = 1:2)

Description

This function uses the latent factors and the weights to do data predictions.

Usage

predict(
  object,
  views = "all",
  groups = "all",
  factors = "all",
  add_intercept = TRUE
)

Arguments

Details

MOFA generates a denoised and condensed low-dimensional representation of the data that captures the main sources of heterogeneity of the data. This representation can be used to reconstruct a denoised representation of the data, simply using the equation Y = WX. For more mathematical details read the supplementary methods of the manuscript.

Value

Returns a list with the data reconstructed by the model predictions.

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Predict observations for all data modalities
predictions <- predict(model)

Description

Function to prepare a MOFA object for training. It requires defining data, model and training options.

Usage

prepare_mofa(
  object,
  data_options = NULL,
  model_options = NULL,
  training_options = NULL,
  stochastic_options = NULL,
  mefisto_options = NULL
)

Arguments

Details

This function is called after creating a MOFA object (using create_mofa) and before starting the training (using run_mofa). Here, we can specify different options for the data (data_options), the model (model_options) and the trainig (training_options, stochastic_options). Take a look at the individual default options for an overview using the get_default_XXX_options functions above.

Value

Returns an untrained MOFA with specified options filled in the corresponding slots

Examples

# Using an existing simulated data with two groups and two views
file <- system.file("extdata", "test_data.RData", package = "MOFA2")

# Load data dt (in data.frame format)
load(file) 

# Create the MOFA object
MOFAmodel <- create_mofa(dt)

# Prepare MOFA object using default options
MOFAmodel <- prepare_mofa(MOFAmodel)

# Prepare MOFA object changing some of the default model options values
model_opts <- get_default_model_options(MOFAmodel)
model_opts$num_factors <- 10
MOFAmodel <- prepare_mofa(MOFAmodel, model_options = model_opts)

Description

Method to perform feature set enrichment analysis. Here we use a slightly modified version of the pcgse function.

Usage

run_enrichment(
  object,
  view,
  feature.sets,
  factors = "all",
  set.statistic = c("mean.diff", "rank.sum"),
  statistical.test = c("parametric", "cor.adj.parametric", "permutation"),
  sign = c("all", "positive", "negative"),
  min.size = 10,
  nperm = 1000,
  p.adj.method = "BH",
  alpha = 0.1,
  verbose = TRUE
)

Arguments

Details

The aim of this function is to relate each factor to pre-defined biological pathways by performing a gene set enrichment analysis on the feature weights.
This function is particularly useful when a factor is difficult to characterise based only on the genes with the highest weight.
We provide a few pre-built gene set matrices in the MOFAdata package. See https://github.com/bioFAM/MOFAdata for details.
The function we implemented is based on the pcgse function with some modifications. Please read this paper https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4543476 for details on the math.

Value

a list with five elements:

Description

Function to train an untrained MOFA object.

Usage

run_mofa(object, outfile = NULL, save_data = TRUE, use_basilisk = FALSE)

Arguments

Details

This function is called once a MOFA object has been prepared (using prepare_mofa) In this step the R package calls the mofapy2 Python package, where model training is performed.
The interface with Python is done with the reticulate package. If you have several versions of Python installed and R is not detecting the correct one, you can change it using reticulate::use_python when loading the R session. Alternatively, you can let us install mofapy2 for you using basilisk if you set use_basilisk to TRUE

Value

a trained MOFA object

Examples

# Load data (in data.frame format)
file <- system.file("extdata", "test_data.RData", package = "MOFA2")
load(file) 

# Create the MOFA object
MOFAmodel <- create_mofa(dt)

# Prepare the MOFA object with default options
MOFAmodel <- prepare_mofa(MOFAmodel)

# Run the MOFA model
## Not run:  MOFAmodel <- run_mofa(MOFAmodel, use_basilisk = TRUE)

Description

Run t-SNE on the MOFA factors

Usage

run_tsne(object, factors = "all", groups = "all", ...)

Arguments

Details

This function calls Rtsne to calculate a TSNE representation from the MOFA factors. Subsequently, you can plot the TSNE representation with plot_dimred or fetch the coordinates using plot_dimred(..., method="TSNE", return_data=TRUE). Remember to use set.seed before the function call to get reproducible results.

Value

Returns a MOFA object with the MOFAobject@dim_red slot filled with the t-SNE output

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Run
## Not run:  model <- run_tsne(model, perplexity = 15) 

# Plot
## Not run:  model <- plot_dimred(model, method="TSNE") 

# Fetch data
## Not run:  tsne.df <- plot_dimred(model, method="TSNE", return_data=TRUE)

Description

Run UMAP on the MOFA factors

Usage

run_umap(
  object,
  factors = "all",
  groups = "all",
  n_neighbors = 30,
  min_dist = 0.3,
  metric = "cosine",
  ...
)

Arguments

Details

This function calls umap to calculate a UMAP representation from the MOFA factors For details on the hyperparameters of UMAP see the documentation of umap. Subsequently, you can plot the UMAP representation with plot_dimred or fetch the coordinates using plot_dimred(..., method="UMAP", return_data=TRUE). Remember to use set.seed before the function call to get reproducible results.

Value

Returns a MOFA object with the MOFAobject@dim_red slot filled with the UMAP output

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Change hyperparameters passed to umap
## Not run:  model <- run_umap(model, min_dist = 0.01, n_neighbors = 10) 
# Plot
## Not run:  model <- plot_dimred(model, method="UMAP") 

# Fetch data
## Not run:  umap.df <- plot_dimred(model, method="UMAP", return_data=TRUE)

Description

samples_metadata: retrieve sample metadata

Usage

samples_metadata(object)

samples_metadata(object) <- value

## S4 method for signature 'MOFA'
samples_metadata(object)

## S4 replacement method for signature 'MOFA,data.frame'
samples_metadata(object) <- value

Arguments

Value

a data frame with sample metadata

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
samples_metadata(model)

Description

samples_names: set and retrieve sample names

Usage

samples_names(object)

samples_names(object) <- value

## S4 method for signature 'MOFA'
samples_names(object)

## S4 replacement method for signature 'MOFA,list'
samples_names(object) <- value

Arguments

Value

list of character vectors with the sample names for each group

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)
samples_names(model)

Select a model from a list of trained MOFA objects based on the best ELBO value

Description

Different objects of MOFA are compared in terms of the final value of the ELBO statistics and the model with the highest ELBO value is selected.

Usage

select_model(models, plot = FALSE)

Arguments

Value

A MOFA object

Description

Function to add continuous covariate(s) to a MOFA object for training with MEFISTO

Usage

set_covariates(object, covariates)

Arguments

Details

To activate the functional MEFISTO framework, specify mefisto_options when preparing the training using prepare_mofa

Value

Returns an untrained MOFA with covariates filled in the corresponding slots

Examples

#' # Simulate data
dd <- make_example_data(sample_cov = seq(0,1,length.out = 100), n_samples = 100, n_factors = 4)

# Create MOFA object
sm <- create_mofa(data = dd$data)

# Add a covariate
sm <- set_covariates(sm, covariates = dd$sample_cov)
sm

Description

Method to subset (or sort) factors

Usage

subset_factors(object, factors, recalculate_variance_explained = TRUE)

Arguments

Value

A MOFA object

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Subset factors 1 to 3
model <- subset_factors(model, factors = 1:3)

Description

Method to subset (or sort) features

Usage

subset_features(object, view, features)

Arguments

Value

A MOFA object

Description

Method to subset (or sort) groups

Usage

subset_groups(object, groups)

Arguments

Value

A MOFA object

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Subset the first group
model <- subset_groups(model, groups = 1)

Description

Method to subset (or sort) samples

Usage

subset_samples(object, samples)

Arguments

Value

A MOFA object

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# (TO-DO) Remove a specific sample from the model (an outlier)

Description

Method to subset (or sort) views

Usage

subset_views(object, views)

Arguments

Value

A MOFA object

Examples

# Using an existing trained model on simulated data
file <- system.file("extdata", "model.hdf5", package = "MOFA2")
model <- load_model(file)

# Subset the first view
model <- subset_views(model, views = 1)

Description

Function to summarise factor values using a discrete grouping of samples.

Usage

summarise_factors(
  object,
  df,
  factors = "all",
  groups = "all",
  abs = FALSE,
  return_data = FALSE
)

Arguments