algorithmic: Generic Interface for Algorithms

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

Generic Interface for Algorithms

Description

The functions documented here are S4 generics that define an general interface for – optimisation – algorithms.

This interface builds upon the broad definition of an algorithm as a workhorse function to which is associated auxiliary objects such as an underlying model or an objective function that measures the adequation of the model with observed data. It aims at complementing the interface provided by the stats package.

Usage

  algorithm(object, ...)

  algorithm(object, ...)<-value

  seeding(object, ...)

  seeding(object, ...)<-value

  niter(object, ...)

  niter(object, ...)<-value

  nrun(object, ...)

  objective(object, ...)

  objective(object, ...)<-value

  runtime(object, ...)

  runtime.all(object, ...)

  seqtime(object, ...)

  modelname(object, ...)

  run(object, y, x, ...)

  logs(object, ...)

  compare(object, ...)

Arguments

object	an object computed using some algorithm, or that describes an algorithm itself.
value	replacement value
...	extra arguments to allow extension
y	data object, e.g. a target matrix
x	a model object used as a starting point by the algorithm, e.g. a non-empty NMF model.

Details

algorithm and algorithm<- get/set an object that describes the algorithm used to compute another object, or with which it is associated. It may be a simple character string that gives the algorithm's names, or an object that includes the algorithm's definition itself (e.g. an NMFStrategy object).

seeding get/set the seeding method used to initialise the computation of an object, i.e. usually the function that sets the starting point of an algorithm.

niter and niter<- get/set the number of iterations performed to compute an object. The function niter<- would usually be called just before returning the result of an algorithm, when putting together data about the fit.

nrun returns the number of times the algorithm has been run to compute an object. Usually this will be 1, but may be be more if the algorithm involves multiple starting points.

objective and objective<- get/set the objective function associated with an object. Some methods for objective may also compute the objective value with respect to some target/observed data.

runtime returns the CPU time required to compute an object. This would generally be an object of class proc_time.

runtime.all returns the CPU time required to compute a collection of objects, e.g. a sequence of independent fits.

seqtime returns the sequential CPU time – that would be – required to compute a collection of objects. It would differ from runtime.all if the computations were performed in parallel.

modelname returns a the type of model associated with an object.

run calls the workhorse function that actually implements a strategy/algorithm, and run it on some data object.

logs returns the log messages output during the computation of an object.

compare compares objects obtained from running separate algorithms.

Methods

algorithm

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

algorithm

signature(object = "NMFList"): Returns the method names used to compute the NMF fits in the list. It returns NULL if the list is empty.

See algorithm,NMFList-method for more details.

algorithm

signature(object = "NMFfitXn"): Returns the name of the common NMF algorithm used to compute all fits stored in object

Since all fits are computed with the same algorithm, this method returns the name of algorithm that computed the first fit. It returns NULL if the object is empty.

algorithm

signature(object = "NMFSeed"): Returns the workhorse function of the seeding method described by object.

algorithm

signature(object = "NMFStrategyFunction"): Returns the single R function that implements the NMF algorithm – as stored in slot algorithm.

algorithm<-

signature(object = "NMFSeed", value = "function"): Sets the workhorse function of the seeding method described by object.

algorithm<-

signature(object = "NMFStrategyFunction", value = "function"): Sets the function that implements the NMF algorithm, stored in slot algorithm.

compare

signature(object = "NMFfitXn"): Compares the fits obtained by separate runs of NMF, in a single call to nmf.

logs

signature(object = "ANY"): Default method that returns the value of attribute/slot 'logs' or, if this latter does not exists, the value of element 'logs' if object is a list. It returns NULL if no logging data was found.

modelname

signature(object = "ANY"): Default method which returns the class name(s) of object. This should work for objects representing models on their own.

For NMF objects, this is the type of NMF model, that corresponds to the name of the S4 sub-class of NMF, inherited by object.

modelname

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

modelname

signature(object = "NMFfitXn"): Returns the common type NMF model of all fits stored in object

Since all fits are from the same NMF model, this method returns the model type of the first fit. It returns NULL if the object is empty.

modelname

signature(object = "NMFStrategy"): Returns the model(s) that an NMF algorithm can fit.

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).

nrun

signature(object = "ANY"): Default method that returns the value of attribute ‘nrun’.

Such an attribute my be attached to objects to keep track of data about the parent fit object (e.g. by method consensus), which can be used by subsequent function calls such as plot functions (e.g. see consensusmap). This method returns NULL if no suitable data was found.

nrun

signature(object = "NMFfitX"): Returns the number of NMF runs performed to create object.

It is a pure virtual method defined to ensure nrun is defined for sub-classes of NMFfitX, which throws an error if called.

Note that because the nmf function allows to run the NMF computation keeping only the best fit, nrun may return a value greater than one, while only the result of the best run is stored in the object (cf. option 'k' in method nmf).

nrun

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

nrun

signature(object = "NMFfitX1"): Returns the number of NMF runs performed, amongst which object was selected as the best fit.

nrun

signature(object = "NMFfitXn"): Returns the number of runs performed to compute the fits stored in the list (i.e. the length of the list itself).

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.

See objective,NMFfit-method for more details.

runtime

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

runtime

signature(object = "NMFList"): Returns the CPU time required to compute all NMF fits in the list. It returns NULL if the list is empty. If no timing data are available, the sequential time is returned.

See runtime,NMFList-method for more details.

runtime.all

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

runtime.all

signature(object = "NMFfitX"): Returns the CPU time required to compute all the NMF runs. It returns NULL if no CPU data is available.

runtime.all

signature(object = "NMFfitXn"): If no time data is available from in slot ‘runtime.all’ and argument null=TRUE, then the sequential time as computed by seqtime is returned, and a warning is thrown unless warning=FALSE.

See runtime.all,NMFfitXn-method for more details.

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.

seeding

signature(object = "NMFfitXn"): Returns the name of the common seeding method used the computation of all fits stored in object

Since all fits are seeded using the same method, this method returns the name of the seeding method used for the first fit. It returns NULL if the object is empty.

seqtime

signature(object = "NMFList"): Returns the CPU time that would be required to sequentially compute all NMF fits stored in object.

This method calls the function runtime on each fit and sum up the results. It returns NULL on an empty object.

seqtime

signature(object = "NMFfitXn"): Returns the CPU time that would be required to sequentially compute all NMF fits stored in object.

This method calls the function runtime on each fit and sum up the results. It returns NULL on an empty object.

Interface fo NMF algorithms

This interface is implemented for NMF algorithms by the classes NMFfit, NMFfitX and NMFStrategy, and their respective sub-classes. The examples given in this documentation page are mainly based on this implementation.

Examples

#----------
# modelname,ANY-method
#----------
# get the type of an NMF model
modelname(nmfModel(3))
modelname(nmfModel(3, model='NMFns'))
modelname(nmfModel(3, model='NMFOffset'))

#----------
# modelname,NMFStrategy-method
#----------
# get the type of model(s) associated with an NMF algorithm
modelname( nmfAlgorithm('brunet') )
modelname( nmfAlgorithm('nsNMF') )
modelname( nmfAlgorithm('offset') )

NMF documentation built on March 31, 2023, 6:55 p.m.