basis-coef-methods: Accessing NMF Factors

In renozao/NMF: Algorithms and Framework for Nonnegative Matrix Factorization (NMF)

Description

basis and basis<- are S4 generic functions which respectively extract and set the matrix of basis components of an NMF model (i.e. the first matrix factor).

The methods .basis, .coef and their replacement versions are implemented as pure virtual methods for the interface class NMF, meaning that concrete NMF models must provide a definition for their corresponding class (i.e. sub-classes of class NMF). See NMF for more details.

The method loadings is identical to basis, but do not accept any extra argument.

coef and coef<- respectively extract and set the coefficient matrix of an NMF model (i.e. the second matrix factor). For example, in the case of the standard NMF model V ~ W H, the method coef will return the matrix H.

Methods coefficients and coefficients<- are simple aliases for methods coef and coef<- respectively.

scoef is similar to coef, but returns the mixture coefficient matrix of an NMF model, with the columns scaled so that they sum up to a given value (1 by default).

Usage

basis(object, ...)

## S4 method for signature 'ANY'
basis(object, ...)

## S4 method for signature 'NMF'
basis(object, ..., all = TRUE)

.basis(object, ...)

basis(object, ...) <- value

## S4 replacement method for signature 'NMF'
basis(object, ..., use.dimnames = TRUE) <- value

.basis(object, ...) <- value

## S4 method for signature 'NMF'
loadings(x)

coef(object, ...)

## S4 method for signature 'NMF'
coef(object, ..., all = TRUE)

.coef(object, ...)

coef(object, ...) <- value

## S4 replacement method for signature 'NMF'
coef(object, ..., use.dimnames = TRUE) <- value

.coef(object, ...) <- value

coefficients(object, ...)

## S4 method for signature 'NMF'
coefficients(object, ..., all = TRUE)

scoef(object, ...)

## S4 method for signature 'matrix'
scoef(object, scale = 1)

## S4 method for signature 'NMFfitXn'
coef(object, ...)

## S4 method for signature 'NMFfitXn'
basis(object, ...)

Arguments

object	an object from which to extract the factor matrices, typically an object of class NMF.
...	extra arguments to allow extension and passed to the low-level access functions .coef and .basis. Note that these throw an error if used in replacement functions .
all	a logical that indicates whether the complete matrix factor should be returned (TRUE) or only the non-fixed part. This is relevant only for formula-based NMF models that include fixed basis or coefficient terms.
value	replacement value
use.dimnames	logical that indicates if the object's dim names should be set using those from the new value, or left unchanged – after truncating them to fit new dimensions if necessary. This is useful to only set the entries of a factor.
x	an object of class NMF
scale	scaling factor, which indicates to the value the columns of the coefficient matrix should sum up to.

Details

For example, in the case of the standard NMF model V ~ W H, the method basis will return the matrix W.

basis and basis<- are defined for the top virtual class NMF only, and rely internally on the low-level S4 generics .basis and .basis<- respectively that effectively extract/set the coefficient data. These data are post/pre-processed, e.g., to extract/set only their non-fixed terms or check dimension compatibility.

The method loadings is provided to standardise the NMF interface against the one defined in the stats package, and emphasises the similarities between NMF and PCA or factorial analysis (see loadings).

coef and coef<- are S4 methods defined for the corresponding generic functions from package stats (See stats::coef). Similarly to basis and basis<-, they are defined for the top virtual class NMF only, and rely internally on the S4 generics .coef and .coef<- respectively that effectively extract/set the coefficient data. These data are post/pre-processed, e.g., to extract/set only their non-fixed terms or check dimension compatibility.

Methods (by generic)

.basis:

• .basis(object = NMF): Pure virtual method for objects of class NMF, that should be overloaded by sub-classes, and throws an error if called.

• .basis(object = NMFstd): Get the basis matrix in standard NMF models

  This function returns slot W of object.

• .basis(object = NMFfit): Returns the basis matrix from an NMF model fitted with function nmf.

  It is a shortcut for .basis(fit(object), ...), dispatching the call to the .basis method of the actual NMF model.

.basis<-:

• .basis<-(object = NMF,value = mMatrix): Pure virtual method for objects of class NMF, that should be overloaded by sub-classes, and throws an error if called.

• .basis<-(object = NMFstd,value = array): Set the basis matrix in standard NMF models

  This function sets slot W of object.

• .basis<-(object = NMFstd,value = mMatrix): Replaces a slice of the basis array.

• .basis<-(object = NMFfit,value = matrix): Sets the the basis matrix of an NMF model fitted with function nmf.

  It is a shortcut for .basis(fit(object)) <- value, dispatching the call to the .basis<- method of the actual NMF model. It is not meant to be used by the user, except when developing NMF algorithms, to update the basis matrix of the seed object before returning it.

.coef:

• .coef(object = NMF): Pure virtual method for objects of class NMF, that should be overloaded by sub-classes, and throws an error if called.

• .coef(object = NMFstd): Get the mixture coefficient matrix in standard NMF models, which is stored in slot H of object.

• .coef(object = NMFfit): Returns the the coefficient matrix from an NMF model fitted with function nmf.

  It is a shortcut for .coef(fit(object), ...), dispatching the call to the .coef method of the actual NMF model.

.coef<-:

• .coef<-(object = NMF,value = mMatrix): Pure virtual method for objects of class NMF, that should be overloaded by sub-classes, and throws an error if called.

• .coef<-(object = NMFstd,value = array): Set the mixture coefficient matrix in standard NMF models

  This function sets slot H of object.

• .coef<-(object = NMFstd,value = mMatrix): Replaces a slice of the coefficent array.

• .coef<-(object = NMFfit,value = matrix): Sets the the coefficient matrix of an NMF model fitted with function nmf.

  It is a shortcut for .coef(fit(object)) <- value, dispatching the call to the .coef<- method of the actual NMF model. It is not meant to be used by the user, except when developing NMF algorithms, to update the coefficient matrix in the seed object before returning it.

basis:

• basis(object = ANY): Default method returns the value of S3 slot or attribute 'basis'. It returns NULL if none of these are set.

  Arguments ... are not used by this method.

• basis(object = NMFfitXn): Returns the basis matrix of the best fit amongst all the fits stored in object. It is a shortcut for basis(fit(object)).

basis<-:

• basis<-(object = NMF): Default methods that calls .basis<- and check the validity of the updated object.

coef:

• coef(object = NMFfitXn): Returns the coefficient matrix of the best fit amongst all the fits stored in object. It is a shortcut for coef(fit(object)).

coef<-:

• coef<-(object = NMF): Default methods that calls .coef<- and check the validity of the updated object.

coefficients:

• coefficients(object = NMF): Alias to coef,NMF, therefore also pure virtual.

See Also

Other NMF-interface: NMF-class, nmfModel(), rnmf()

Examples

# Scaled coefficient matrix
x <- rnmf(3, 10, 5)
scoef(x)
scoef(x, 100)

renozao/NMF documentation built on June 14, 2020, 9:35 p.m.