NMFfit-class {NMF}

Base Class for to store Nonnegative Matrix Factorisation results

Description

Base class to handle the results of general Nonnegative Matrix Factorisation algorithms (NMF).

The function NMFfit is a factory method for NMFfit objects, that should not need to be called by the user. It is used internally by the functions nmf and seed to instantiate the starting point of NMF algorithms.

Usage

  NMFfit(fit = nmfModel(), ..., rng = NULL)

Arguments

fit

an NMF model

...

extra argument used to initialise slots in the instantiating NMFfit object.

rng

RNG settings specification (typically a suitable value for .Random.seed).

Details

It provides a general structure and generic functions to manage the results of NMF algorithms. It contains a slot with the fitted NMF model (see slot fit) as well as data about the methods and parameters used to compute the factorization.

The purpose of this class is to handle in a generic way the results of NMF algorithms. Its slot fit contains the fitted NMF model as an object of class NMF.

Other slots contains data about how the factorization has been computed, such as the algorithm and seeding method, the computation time, the final residuals, etc...

Class NMFfit acts as a wrapper class for its slot fit. It inherits from interface class NMF defined for generic NMF models. Therefore, all the methods defined by this interface can be called directly on objects of class NMFfit. The calls are simply dispatched on slot fit, i.e. the results are the same as if calling the methods directly on slot fit.

Slots

fit

An object that inherits from class NMF, and contains the fitted NMF model.

NB: class NMF is a virtual class. The default class for this slot is NMFstd, that implements the standard NMF model.

residuals

A numeric vector that contains the final residuals or the residuals track between the target matrix and its NMF estimate(s). Default value is numeric().

See method residuals for details on accessor methods and main interface nmf for details on how to compute NMF with residuals tracking.

method

a single character string that contains the name of the algorithm used to fit the model. Default value is ''.

seed

a single character string that contains the name of the seeding method used to seed the algorithm that fitted the NMF model. Default value is ''. See nmf for more details.

rng

an object that contains the RNG settings used for the fit. Currently the settings are stored as an integer vector, the value of .Random.seed at the time the object is created. It is initialized by the initialized method. See getRNG for more details.

distance

either a single "character" string that contains the name of the built-in objective function, or a function that measures the residuals between the target matrix and its NMF estimate. See objective and deviance,NMF-method.

parameters

a list that contains the extra parameters – usually specific to the algorithm – that were used to fit the model.

runtime

object of class "proc_time" that contains various measures of the time spent to fit the model. See system.time

options

a list that contains the options used to compute the object.

extra

a list that contains extra miscellaneous data for internal usage only. For example it can be used to store extra parameters or temporary data, without the need to explicitly extend the NMFfit class. Currently built-in algorithms only use this slot to store the number of iterations performed to fit the object.

Data that need to be easily accessible by the end-user should rather be set using the methods $<- that sets elements in the list slot misc – that is inherited from class NMF.

call

stored call to the last nmf method that generated the object.

Methods

algorithm

signature(object = "NMFfit"): Returns the name of the algorithm that fitted the NMF model object.

.basis

signature(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<-

signature(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

signature(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<-

signature(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.

compare

signature(object = "NMFfit"): Compare multiple NMF fits passed as arguments.

deviance

signature(object = "NMFfit"): Returns the deviance of a fitted NMF model.

This method returns the final residual value if the target matrix y is not supplied, or the approximation error between the fitted NMF model stored in object and y. In this case, the computation is performed using the objective function method if not missing, or the objective of the algorithm that fitted the model (stored in slot 'distance').

See deviance,NMFfit-method for more details.

fit

signature(object = "NMFfit"): Returns the NMF model object stored in slot 'fit'.

fit<-

signature(object = "NMFfit", value = "NMF"): Updates the NMF model object stored in slot 'fit' with a new value.

fitted

signature(object = "NMFfit"): Computes and return the estimated target matrix from an NMF model fitted with function nmf.

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

ibterms

signature(object = "NMFfit"): Method for single NMF fit objects, which returns the indexes of fixed basis terms from the fitted model.

icterms

signature(object = "NMFfit"): Method for single NMF fit objects, which returns the indexes of fixed coefficient terms from the fitted model.

icterms

signature(object = "NMFfit"): Method for multiple NMF fit objects, which returns the indexes of fixed coefficient terms from the best fitted model.

minfit

signature(object = "NMFfit"): Returns the object its self, since there it is the result of a single NMF run.

modelname

signature(object = "NMFfit"): Returns the type of a fitted NMF model. It is a shortcut for modelname(fit(object).

niter

signature(object = "NMFfit"): Returns the number of iteration performed to fit an NMF model, typically with function nmf.

Currently this data is stored in slot 'extra', but this might change in the future.

niter<-

signature(object = "NMFfit", value = "numeric"): Sets the number of iteration performed to fit an NMF model.

This function is used internally by the function nmf. It is not meant to be called by the user, except when developing new NMF algorithms implemented as single function, to set the number of iterations performed by the algorithm on the seed, before returning it (see NMFStrategyFunction).

nmf.equal

signature(x = "NMFfit", y = "NMF"): Compares two NMF models when at least one comes from a NMFfit object, i.e. an object returned by a single run of nmf.

nmf.equal

signature(x = "NMFfit", y = "NMFfit"): Compares two fitted NMF models, i.e. objects returned by single runs of nmf.

NMFfitX

signature(object = "NMFfit"): Creates an NMFfitX1 object from a single fit. This is used in nmf when only the best fit is kept in memory or on disk.

nrun

signature(object = "NMFfit"): This method always returns 1, since an NMFfit object is obtained from a single NMF run.

objective

signature(object = "NMFfit"): Returns the objective function associated with the algorithm that computed the fitted NMF model object, or the objective value with respect to a given target matrix y if it is supplied.

offset

signature(object = "NMFfit"): Returns the offset from the fitted model.

plot

signature(x = "NMFfit", y = "missing"): Plots the residual track computed at regular interval during the fit of the NMF model x.

residuals

signature(object = "NMFfit"): Returns the residuals – track – between the target matrix and the NMF fit object.

runtime

signature(object = "NMFfit"): Returns the CPU time required to compute a single NMF fit.

runtime.all

signature(object = "NMFfit"): Identical to runtime, since their is a single fit.

seeding

signature(object = "NMFfit"): Returns the name of the seeding method that generated the starting point for the NMF algorithm that fitted the NMF model object.

show

signature(object = "NMFfit"): Show method for objects of class NMFfit

summary

signature(object = "NMFfit"): Computes summary measures for a single fit from nmf.

This method adds the following measures to the measures computed by the method summary,NMF:

See summary,NMFfit-method for more details.

Examples

# run default NMF algorithm on a random matrix
n <- 50; r <- 3; p <- 20
V <- rmatrix(n, p)
res <- nmf(V, r)

# result class is NMFfit
class(res)
isNMFfit(res)

# show result
res

# compute summary measures
summary(res, target=V)