Generic Interface for Algorithms
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.
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, ...)
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. |
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.
signature(object = "NMFfit"):
Returns the name of the algorithm that fitted the NMF
model object.
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.
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.
signature(object = "NMFSeed"):
Returns the workhorse function of the seeding method
described by object.
signature(object =
"NMFStrategyFunction"): Returns the single R function
that implements the NMF algorithm – as stored in slot
algorithm.
signature(object = "NMFSeed",
value = "function"): Sets the workhorse function of the
seeding method described by object.
signature(object =
"NMFStrategyFunction", value = "function"): Sets the
function that implements the NMF algorithm, stored in
slot algorithm.
signature(object = "NMFfitXn"):
Compares the fits obtained by separate runs of NMF, in a
single call to nmf.
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.
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.
signature(object = "NMFfit"):
Returns the type of a fitted NMF model. It is a shortcut
for modelname(fit(object).
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.
signature(object =
"NMFStrategy"): Returns the model(s) that an NMF
algorithm can fit.
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.
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).
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.
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).
signature(object = "NMFfit"): This
method always returns 1, since an NMFfit object is
obtained from a single NMF run.
signature(object = "NMFfitX1"):
Returns the number of NMF runs performed, amongst which
object was selected as the best fit.
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).
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.
signature(object = "NMFfit"):
Returns the CPU time required to compute a single NMF
fit.
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.
signature(object = "NMFfit"):
Identical to runtime, since their is a single fit.
signature(object = "NMFfitX"):
Returns the CPU time required to compute all the NMF
runs. It returns NULL if no CPU data is available.
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.
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.
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.
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.
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.
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.
#----------
# 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') )Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.