NMF (version 0.2.2)

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

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.

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.

Examples

# roxygen generated flag
options(R_CHECK_RUNNING_EXAMPLES_=TRUE)

#----------
# 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') )