Estimate Prior Covariance Matrices using Extreme Deconvolution

Perform extreme deconvolution (ED) to estimate data-driven prior covariance matrices.

pois_cov_ed(
  data,
  subset,
  Ulist,
  ulist,
  ulist.dd,
  ruv = FALSE,
  Fuv,
  update.mu = TRUE,
  verbose = FALSE,
  init = list(),
  control = list()
)

pois_cov_ed_control_default()

Arguments

data: “pois.mash” data object, typically created by calling pois_mash_set_data.
subset: The indices of features to be used. Defaults to using all features.
Ulist: A list of H full-rank covariance matrices (e.g., initialized by pois_cov_init).
ulist: A list of G numeric vectors each of which defines a rank-1 covariance matrix.
ulist.dd: Logical vector of length G denoting whether each element in ulist is data-driven (TRUE) or canonical (FALSE). Defaults to data-driven for all elements. For canonical covariances, the spanned space is not updated.
ruv: Logical scalar indicating whether to account for unwanted variation. If ruv = TRUE, Fuv must be provided.
Fuv: J x D matrix of latent factors causing unwanted variation, with features as rows and latent factors as columns.
update.mu: A logical scalar indicating whether to update gene-specific means mu. If update.mu = FALSE, initial mu must be provided in init.
verbose: Logical scalar indicating whether to print ELBO at each iteration.
init: Optional list of initial values for model parameters (e.g., returned by pois_mash_ruv_prefit).
control: A list of control parameters with the following elements: “maxiter”, maximum number of ED iterations; “maxiter.q”, maximum number of inner loop iterations to update variational parameters at each ED iteration; “maxpsi2”, maximum for the gene-specific dispersion parameter psi2; “maxbias”, maximum for the gene-specific range of bias caused by unwanted variation; “tol.stop”, tolerance for assessing convergence of ED, as measured by absolute change in ELBO; “tol.q”, relative tolerance for assessing convergence of variational parameters at each ED iteration; and “tol.rho”tolerance for assessing convergence of effects corresponding to unwanted variation. Any named components will override the default optimization algorithm settings (as they are defined by pois_cov_ed_control_default).

Value

A list including the following elements:

Ulist: List of H full-rank covariance matrices.
ulist: List of G numeric vectors each of which forms a rank-1 covariance matrix.
pi: Numeric vector of length H + G containing the mixture proportions for Ulist and ulist.