Non-negative Matrix Factorization

These functions perform Non-negative Matrix Factorization on data stored in a TreeSummarizedExperiment object.

getNMF(x, ...)

addNMF(x, ...)

# S4 method for class 'SummarizedExperiment'
getNMF(x, k = 2, assay.type = "counts", eval.metric = "evar", ...)

# S4 method for class 'SummarizedExperiment'
addNMF(
  x,
  k = 2,
  assay.type = "counts",
  eval.metric = "evar",
  name = "NMF",
  ...
)

Arguments

x: a TreeSummarizedExperiment object.
...: optional arguments passed to nmf::NMF.
k: numeric vector. A number of latent vectors/topics. (Default: 2)
assay.type: Character scalar. Specifies which assay to use for NMF ordination. (Default: "counts")
eval.metric: Character scalar. Specifies the evaluation metric that will be used to select the model with the best fit. Must be one of the following options: "evar" (explained variance; maximized), "sparseness.basis" (degree of sparsity in the basis matrix; maximized), "sparseness.coef" (degree of sparsity in the coefficient matrix; maximized), "rss" (residual sum of squares; minimized), "silhouette.coef" (quality of clustering based on the coefficient matrix; maximized), "silhouette.basis" (quality of clustering based on the basis matrix; maximized), "cophenetic" (correlation between cophenetic distances and original distances; maximized), "dispersion" (spread of data points within clusters; minimized). (Default: "evar")
name: Character scalar. The name to be used to store the result in the reducedDims of the output. (Default: "NMF")

Value

For getNMF, the ordination matrix with feature loadings matrix as attribute "loadings".

For addNMF, a TreeSummarizedExperiment object is returned containing the ordination matrix in reducedDims(x, name) with the following attributes:

"loadings" which is a matrix containing the feature loadings
"NMF_output" which is the output of function nmf::NMF
"best_fit" which is the result of the best fit if k is a vector of integers

Details

The functions getNMF and addNMF internally use nmf::NMF compute the ordination matrix and feature loadings.

If k is a vector of integers, NMF output is calculated for all the rank values contained in k, and the best fit is selected based on eval.metric value.

Examples

data(GlobalPatterns)
tse <- GlobalPatterns

# Reduce the number of features
tse <- agglomerateByPrevalence(tse, rank = "Phylum")

# Run NMF and add the result to reducedDim(tse, "NMF").
tse <- addNMF(tse, k = 2, name = "NMF")
#> Loading required package: registry
#> Loading required package: rngtools
#> Loading required package: cluster
#> NMF - BioConductor layer [OK] | Shared memory capabilities [NO: bigmemory] | Cores 2/2
#>   To enable shared memory capabilities, try: install.extras('
#> NMF
#> ')
#> 
#> Attaching package: ‘NMF’
#> The following object is masked from ‘package:S4Vectors’:
#> 
#>     nrun
#> The following object is masked from ‘package:generics’:
#> 
#>     fit

# Extract feature loadings
loadings_NMF <- attr(reducedDim(tse, "NMF"), "loadings")
head(loadings_NMF)
#>                         [,1]         [,2]
#> AD3             1.714391e-07 7.365061e-04
#> Acidobacteria   1.670851e-05 2.732731e-02
#> Actinobacteria  3.144155e-02 8.178415e-02
#> Armatimonadetes 2.220446e-16 3.967567e-04
#> BRC1            9.243747e-08 5.324555e-05
#> Bacteroidetes   2.372217e-01 7.232386e-02

# Estimate models with number of topics from 2 to 4. Perform 2 runs.
tse <- addNMF(tse, k = c(2, 3, 4), name = "NMF_4", nrun = 2)
#> NMF - BioConductor layer [OK] | Shared memory capabilities [NO: bigmemory] | Cores 2/2
#>   To enable shared memory capabilities, try: install.extras('
#> NMF
#> ')
#> 
#> Attaching package: ‘NMF’
#> The following object is masked from ‘package:S4Vectors’:
#> 
#>     nrun
#> The following object is masked from ‘package:generics’:
#> 
#>     fit

# Extract feature loadings
loadings_NMF_4 <- attr(reducedDim(tse, "NMF_4"), "loadings")
head(loadings_NMF_4)
#>                         [,1]         [,2]         [,3]         [,4]
#> AD3             2.220446e-16 6.341564e-04 2.220446e-16 9.968665e-08
#> Acidobacteria   2.841165e-06 2.172085e-02 2.045301e-03 1.071032e-08
#> Actinobacteria  1.506671e-02 7.076351e-02 1.042351e-02 2.220446e-16
#> Armatimonadetes 2.220446e-16 2.198478e-04 1.371072e-04 2.220446e-16
#> BRC1            2.220446e-16 3.739734e-05 9.538384e-06 4.902067e-08
#> Bacteroidetes   1.598147e-02 1.561523e-02 9.194580e-03 2.473480e-01