volnmf_main {vrnmf}

Volume-regularized NMF

Description

volnmf_main enables volume-regularized factorization of a matrix B using the following objective function: F = ||B*Q - C*R||^2 + w.vol*volume(R). Matrix C is required to be non-negative and having either column or row vectors on the simplex. Matrix R can optionally have non-negativity constraint. Matrix Q can optionally be identity matrix or any unitary. The latter option is used to decompose co-occurence matrix vol_P.

Usage

volnmf_main(
  vol,
  B = NULL,
  volnmf = NULL,
  n.comp = 3,
  n.reduce = n.comp,
  do.nmf = TRUE,
  iter.nmf = 100,
  seed = NULL,
  domain = "covariance",
  volf = "logdet",
  wvol = NULL,
  delta = 1e-08,
  n.iter = 500,
  err.cut = 1e-16,
  vol.iter = 20,
  c.iter = 20,
  extrapolate = TRUE,
  accelerate = FALSE,
  acc.C = 4/5,
  acc.R = 3/4,
  C.constraint = "col",
  C.bound = 1,
  R.constraint = "pos",
  R.majorate = FALSE,
  C.init = NULL,
  R.init = NULL,
  Q.init = NULL,
  anchor = NULL,
  Ctrue = NULL,
  verbose = TRUE,
  record = 100,
  verbose.nmf = FALSE,
  record.nmf = NULL,
  mutation.run = FALSE
)

Arguments

vol

An output object of vol_preprocess().

B

A numeric matrix. A matrix to factorize (by default NULL). If not given than matrix B is taken to be a square root decomposition of P = B*t(B).

volnmf

An output object of volnmf.main. An option is useful to re-estimate solution using different parameters (by default NULL).

n.comp

An integer. Number of components to extract (by default 3). Defines number of columns in matrix C.

n.reduce

An integer. Dimensional reduction of matrix B (number of columns) if taken as a square root decomposition of volP (by default equal to n.comp).

do.nmf

A boolean. Estimate standard solution with w.vol=0 as initialization before applying volume regularization (by default TRUE).

iter.nmf

An integer. Number of iterations to get solution with w.vol=0 if the former requested (by default 1,000).

seed

An integer. Fix seed.

domain

A character. Optimize unitary rotation matrix Q ("covariance") or keep it as identity matrix (as in standard NMF). By default "covariance".

volf

A character. Function that approximate volume. Can have values of "logdet" or "det" (by default "logdet").

wvol

A numeric. A weight of volume-regularized term volume(R).

delta

A numeric. Logdet regularization term log(det(R) + delta) (by default 1e-8).

n.iter

An integer. Number of iterations (by default 1,000).

err.cut

A numeric. Relative error in determinant between iterations to stop algorithm (by default 1e-8).

vol.iter

An integer. Number of iterations to update volume-regularized matrix R at each alternating step.

c.iter

An integer. Number of iterations to update simplex matrix C at each alternating step.

extrapolate

A numeric. Do Nesterov extrapolation inside blocks of R and C optimization (by default TRUE).

accelerate

A numeric. Do acceleration each update after R and C blocks estimated via Nesterov-like extrapolation.

acc.C

A numeric. Acceleration parameter of matrix C.

acc.R

A numeric. Acceleration parameter of matrix R.

C.constraint

A character. Constraint either sum of columns ("col") or sum of rows ("row) to be equal to C.bound (By default "col").

C.bound

A numeric. A simplex constraint on matrix C vectors.

R.constraint

A character. Set up non-negativity ("pos") constraint on elements of R (by default "pos", alternative "no").

R.majorate

A boolean. Majorate logdet each iteration of volnmf_logdet() (by default FALSE).

C.init

Numeric matrices. Initialization of matrices C, R, Q (by default NULL).

R.init

Numeric matrices. Initialization of matrices C, R, Q (by default NULL).

Q.init

Numeric matrices. Initialization of matrices C, R, Q (by default NULL).

anchor

An output object of AnchorFree(). Object is used optionally to initialize matrices (by default NULL).

Ctrue

A matrix. Correct matrix C if known. Useful for benchmark.

verbose

A boolean. Print per-iteration information (by default FALSE).

record

A numeric. Record parameters every 'record' iterations (by default NULL).

verbose.nmf

A boolean. Print per-iteration information for standard NMF (by default FALSE).

record.nmf

A numeric. Record parameters every 'record' iterations for standard NMF (by default NULL).

mutation.run

A boolean. Assess goodness of solution using reflection test if mutation.run=TRUE (applicable only to analysis of mutation patterns).

Value

List of objects:

C, R, Q Factorization matrices.

C.init, R.init, Q.init Initialization matrices for volume-regularized optimization.

C.rand, R.rand, Q.rand Random initialization matrices for NMF optimization (w.vol=0).

rec a list of objects that record and store state of matrices each record iterations.