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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
# Definition of a generic interface for algorithms
#
# Author: Renaud Gaujoux
###############################################################################
#' 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 \code{\link{stats}} package.
#'
#' @section Interface fo NMF algorithms:
#' This interface is implemented for NMF algorithms by the classes \code{\link{NMFfit}},
#' \code{\link{NMFfitX}} and \code{\link{NMFStrategy}}, and their respective sub-classes.
#' The examples given in this documentation page are mainly based on this implementation.
#'
#' @param object an object computed using some algorithm, or that describes an algorithm
#' itself.
#' @param value replacement value
#' @param ... extra arguments to allow extension
#'
#' @name algorithmic-NMF
#' @rdname algorithmic
NULL
#' @details
#' \code{algorithm} and \code{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 \code{\link{NMFStrategy}} object).
#'
#' @export
#' @rdname algorithmic
setGeneric('algorithm', function(object, ...) standardGeneric('algorithm') )
#' @export
#' @rdname algorithmic
setGeneric('algorithm<-', function(object, ..., value) standardGeneric('algorithm<-') )
#' @details
#' \code{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.
#'
#' @export
#' @rdname algorithmic
setGeneric('seeding', function(object, ...) standardGeneric('seeding') )
#' @export
#' @rdname algorithmic
setGeneric('seeding<-', function(object, ..., value) standardGeneric('seeding<-') )
#' @details
#' \code{niter} and \code{niter<-} get/set the number of iterations performed
#' to compute an object.
#' The function \code{niter<-} would usually be called just before returning the result
#' of an algorithm, when putting together data about the fit.
#'
#' @export
#' @rdname algorithmic
setGeneric('niter', function(object, ...) standardGeneric('niter'))
#' @rdname algorithmic
#' @export
setGeneric('niter<-', function(object, ..., value) standardGeneric('niter<-'))
#' @details
#' \code{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.
#'
#' @export
#' @rdname algorithmic
setGeneric('nrun', function(object, ...) standardGeneric('nrun') )
#' Default method that returns the value of attribute \sQuote{nrun}.
#'
#' Such an attribute my be attached to objects to keep track of data about
#' the parent fit object (e.g. by method \code{\link{consensus}}), which
#' can be used by subsequent function calls such as plot functions
#' (e.g. see \code{\link{consensusmap}}).
#' This method returns \code{NULL} if no suitable data was found.
setMethod('nrun', 'ANY',
function(object){
attr(object, 'nrun')
}
)
#' @details
#' \code{objective} and \code{objective<-} get/set the objective function associated
#' with an object.
#' Some methods for \code{objective} may also compute the objective value with respect to
#' some target/observed data.
#'
#' @export
#' @rdname algorithmic
setGeneric('objective', function(object, ...) standardGeneric('objective'))
#' @export
#' @rdname algorithmic
setGeneric('objective<-', function(object, ..., value) standardGeneric('objective<-'))
#' @details
#' \code{runtime} returns the CPU time required to compute an object.
#' This would generally be an object of class \code{\link[=proc.time]{proc_time}}.
#'
#' @export
#' @rdname algorithmic
setGeneric('runtime', function(object, ...) standardGeneric('runtime') )
#' @details
#' \code{runtime.all} returns the CPU time required to compute a collection of
#' objects, e.g. a sequence of independent fits.
#'
#' @export
#' @rdname algorithmic
setGeneric('runtime.all', function(object, ...) standardGeneric('runtime.all') )
#' @details
#' \code{seqtime} returns the sequential CPU time -- that would be -- required
#' to compute a collection of objects.
#' It would differ from \code{runtime.all} if the computations were performed
#' in parallel.
#'
#' @export
#' @rdname algorithmic
setGeneric('seqtime', function(object, ...) standardGeneric('seqtime') )
#' @details
#' \code{modelname} returns a the type of model associated with an object.
#'
#' @rdname algorithmic
#' @export
setGeneric('modelname', function(object, ...) standardGeneric('modelname'))
#' Default method which returns the class name(s) of \code{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 \code{\linkS4class{NMF}}, inherited by \code{object}.
#'
#' @examples
#' # get the type of an NMF model
#' modelname(nmfModel(3))
#' modelname(nmfModel(3, model='NMFns'))
#' modelname(nmfModel(3, model='NMFOffset'))
#'
setMethod('modelname', 'ANY',
function(object)
{
as.character(class(object))
}
)
#' @details
#' \code{run} calls the workhorse function that actually implements a strategy/algorithm,
#' and run it on some data object.
#'
#' @param y data object, e.g. a target matrix
#' @param x a model object used as a starting point by the algorithm,
#' e.g. a non-empty NMF model.
#'
#' @export
#' @rdname algorithmic
setGeneric('run', function(object, y, x, ...) standardGeneric('run'))
#' @details
#' \code{logs} returns the log messages output during the computation of an
#' object.
#' @export
#' @rdname algorithmic
setGeneric('logs', function(object, ...) standardGeneric('logs'))
#' Default method that returns the value of attribute/slot \code{'logs'} or, if this latter
#' does not exists, the value of element \code{'logs'} if \code{object} is a \code{list}.
#' It returns \code{NULL} if no logging data was found.
setMethod('logs', 'ANY',
function(object)
{
res <- attr(object, 'logs')
if( !is.null(res) ) res
else if( is.list(object) ) object$logs
}
)
#' @details
#' \code{compare} compares objects obtained from running separate algorithms.
#'
#' @export
#' @rdname algorithmic
setGeneric('compare', function(object, ...) standardGeneric('compare') )
|
