mfa: Fit a MFA object

View source: R/mfa.R

mfaR Documentation

Fit a MFA object

Description

Perform Gibbs sampling inference for a hierarchical Bayesian mixture of factor analysers to identify bifurcations in single-cell expression data.

Usage

mfa(y, iter = 2000, thin = 1, burn = iter/2, b = 2,
  zero_inflation = FALSE, pc_initialise = 1, prop_collapse = 0,
  scale_input = !zero_inflation, lambda = NULL, eta_tilde = NULL,
  alpha = 0.1, beta = 0.1, theta_tilde = 0, tau_eta = 1,
  tau_theta = 1, tau_c = 1, alpha_chi = 0.01, beta_chi = 0.01,
  w_alpha = 1/b, clamp_pseudotimes = FALSE)

Arguments

y

A cell-by-gene single-cell expression matrix or an ExpressionSet object

iter

Number of MCMC iterations

thin

MCMC samples to thin

burn

Number of MCMC samples to throw away

b

Number of branches to model

zero_inflation

Logical, should zero inflation be enabled?

pc_initialise

Which principal component to initialise pseudotimes to

prop_collapse

Proportion of Gibbs samples which should marginalise over c

scale_input

Logical. If true, input is scaled to have mean 0 variance 1

lambda

The dropout parameter - by default estimated using the function empirical_lambda

eta_tilde

Hyperparameter

alpha

Hyperparameter

beta

Hyperparameter

theta_tilde

Hyperparameter

tau_eta

Hyperparameter

tau_theta

Hyperparameter

tau_c

Hyperparameter

alpha_chi

Hyperparameter

beta_chi

Hyperparameter

w_alpha

Hyperparameter

clamp_pseudotimes

This clamps the pseudotimes to their initial values and doesn't perform sampling. Should be FALSE except for diagnostics.

Details

The column names of Y are used as feature (gene/transcript) names while the row names are used as cell names. If either of these is undefined then the corresponding names are set to cell_x or feature_y.

It is recommended the form of Y is analogous to log-expression to mitigate the impact of outliers.

In the absence of prior information, three valid local maxima in the posterior likelihood exist (see manuscript). Setting the initial values to a principal component typically fixes sampling to one of them, analogous to specifying a root cell in similar methods.

The hyper-parameter eta_tilde represents the expected expression in the absence of any actual expression measurements. While a Bayesian purist might reason this based on knowledge of the measurement technology, simply taking the mean of the input matrix in an Empirical Bayes style seems reasonable.

The degree of shrinkage of the factor loading matrices to a common value is given by the gamma prior on chi. The mean of this is alpha_chi / beta_chi while the variance alpha_chi / beta_chi^2. Therefore, to obtain higher levels of shrinkage increase alpha_chi with respect to beta_chi.

The collapsed Gibbs sampling option given by collapse involves marginalising out c (the factor loading intercepts) when updating the branch assignment parameters gamma which tends to soften the branch assignments.

If zero inflation is enabled using the zero_inflation parameter then scaling should *not* be enabled.

Value

An S3 structure with the following entries:

  • traces A list of iteration-by-dim trace matrices for several important variables

  • iter Number of iterations

  • thin Thinning applied

  • burn Burn period at the start of MCMC

  • b Number of branches modelled

  • prop_collapse Proportion of updates for gamma that are collapsed

  • N Number of cells

  • G Number of features (genes/transcripts)

  • feature_names Names of features

  • cell_names Names of cells

Examples

synth <- create_synthetic(C = 20, G = 5)
m <- mfa(synth$X)

kieranrcampbell/mfa documentation built on March 27, 2022, 5:20 a.m.