Description Usage Arguments Details Interface fo NMF algorithms Methods (by generic) Examples
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | algorithm(object, ...)
algorithm(object, ...) <- value
seeding(object, ...)
seeding(object, ...) <- value
niter(object, ...)
niter(object, ...) <- value
nrun(object, ...)
## S4 method for signature 'ANY'
nrun(object)
objective(object, ...)
objective(object, ...) <- value
runtime(object, ...)
runtime.all(object, ...)
seqtime(object, ...)
modelname(object, ...)
## S4 method for signature 'ANY'
modelname(object)
run(object, y, x, ...)
logs(object, ...)
## S4 method for signature 'ANY'
logs(object)
compare(object, ...)
|
object |
an object computed using some algorithm, or that describes an algorithm itself. |
... |
extra arguments to allow extension |
value |
replacement value |
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.
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.
algorithm:
algorithm(object = NMFfit)
: Returns the name of the algorithm that fitted the NMF model object
.
algorithm(object = NMFList)
: Returns the method names used to compute the NMF fits in the list.
It returns NULL
if the list is empty.
algorithm(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(object = NMFSeed)
: Returns the workhorse function of the seeding method described by object
.
algorithm(object = NMFStrategyFunction)
: Returns the single R function that implements the NMF algorithm – as stored in
slot algorithm
.
algorithm(object = NMFStrategyOctave)
: Returns the name of the Octave/Matlab function that implements the NMF algorithm – as stored in
slot algorithm
.
algorithm<-:
algorithm<-(object = NMFSeed,value = function)
: Sets the workhorse function of the seeding method described by object
.
algorithm<-(object = NMFStrategyFunction,value = function)
: Sets the function that implements the NMF algorithm, stored in slot algorithm
.
algorithm<-(object = NMFStrategyOctave,value = character)
: Sets the name of the Octave/Matlab function that implements the NMF algorithm.
It is stored in slot algorithm
.
compare:
compare(object = NMFfit)
: Compare multiple NMF fits passed as arguments.
compare(object = NMFfitXn)
: Compares the fits obtained by separate runs of NMF, in a single
call to nmf
.
compare(object = list)
: Compares multiple NMF fits passed as a standard list.
logs:
logs(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:
modelname(object = NMFfit)
: Returns the type of a fitted NMF model.
It is a shortcut for modelname(fit(object)
.
modelname(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(object = NMFStrategy)
: Returns the model(s) that an NMF algorithm can fit.
modelname(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
.
niter:
niter(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<-:
niter<-(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:
nrun(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(object = NMF)
: This default fallback method always returns 1L
.
nrun(object = NMFfit)
: This method returns the number of runs used to compute a fitted NMF model (in fit(object)
).
This will be 1L
most of the time, since an NMFfit
object is generally from a
single NMF run, except in special nested fits.
nrun(object = NMFfitX1)
: Returns the number of NMF runs performed, amongst which object
was
selected as the best fit.
nrun(object = NMFfitXn)
: Returns the number of runs performed to compute the fits stored in the list
(i.e. the length of the list itself).
nrun(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.
objective:
objective(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.
objective(object = NMFStrategy)
: Gets the objective function associated with an NMF algorithm.
It is used in deviance
to compute the objective value for an NMF model with respect to
a given target matrix.
objective<-:
objective<-(object = NMFStrategy,value = character)
: Sets the objective function associated with an NMF algorithm, with a character string
that must be a registered objective function.
objective<-(object = NMFStrategy,value = function)
: Sets the objective function associated with an NMF algorithm, with a function
that computes the approximation error between an NMF model and a target matrix.
run:
run(object = NMFStrategy,y = mMatrix,x = NMFfit)
: Pure virtual method defined for all NMF algorithms to ensure
that a method run
is defined by sub-classes of NMFStrategy
.
It throws an error if called directly.
run(object = NMFStrategy,y = mMatrix,x = NMF)
: Method to run an NMF algorithm directly starting from a given NMF model.
run(object = NMFStrategyFunction,y = matrix,x = NMFfit)
: Runs the NMF algorithms implemented by the single R function – and stored in slot 'algorithm'
of object
, on the data object y
, using x
as starting point.
It is equivalent to calling object@algorithm(y, x, ...)
.
This method is usually not called directly, but only via the function nmf
, which
takes care of many other details such as seeding the computation, handling RNG settings, or setting up
parallelisation.
run(object = NMFStrategyIterative,y = mMatrix,x = NMFfit)
: Runs an NMF iterative algorithm on a target matrix y
.
run(object = NMFStrategyOctave,y = matrix,x = NMFfit)
: Runs the NMF algorithms implemented by the Octave/Matlab function associated with the
strategy – and stored in slot 'algorithm'
of object
.
This method is usually not called directly, but only via the function nmf
, which
takes care of many other details such as seeding the computation, handling RNG settings,
or setting up parallel computations.
runtime:
runtime(object = NMFfit)
: Returns the CPU time required to compute a single NMF fit.
runtime(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.
runtime.all:
runtime.all(object = NMFfit)
: Identical to runtime
, since their is a single fit.
runtime.all(object = NMFfitX)
: Returns the CPU time required to compute all the NMF runs.
It returns NULL
if no CPU data is available.
runtime.all(object = NMFfitXn)
: Returns the CPU time used to perform all the NMF fits stored in object
.
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
.
seeding:
seeding(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(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:
seqtime(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(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.
1 2 3 4 |
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.