File: NMFfit-class.R

package info (click to toggle)
r-cran-nmf 0.23.0-1
 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734 # Implementation of class NMFfit # # This class manages the result of a single run of a NMF algorithm. # # Author: Renaud Gaujoux ############################################################################### #' @include fixed-terms.R #' @include nmfModel.R NULL #' Base Class for to store Nonnegative Matrix Factorisation results #' #' Base class to handle the results of general \strong{Nonnegative Matrix #' Factorisation} algorithms (NMF). #' #' It provides a general structure and generic functions to manage the results #' of NMF algorithms. It contains a slot with the fitted NMF model (see slot #' \code{fit}) as well as data about the methods and parameters used to compute #' the factorization. #' #' The purpose of this class is to handle in a generic way the results of NMF #' algorithms. Its slot \code{fit} contains the fitted NMF model as an object #' of class \code{\linkS4class{NMF}}. #' #' Other slots contains data about how the factorization has been computed, #' such as the algorithm and seeding method, the computation time, the final #' residuals, etc\dots{} #' #' Class \code{NMFfit} acts as a wrapper class for its slot \code{fit}. It #' inherits from interface class \code{\linkS4class{NMF}} defined for generic #' NMF models. Therefore, all the methods defined by this interface can be #' called directly on objects of class \code{NMFfit}. The calls are simply #' dispatched on slot \code{fit}, i.e. the results are the same as if calling #' the methods directly on slot \code{fit}. #' #' @slot fit An object that inherits from class \code{\linkS4class{NMF}}, and #' contains the fitted NMF model. #' #' NB: class \code{NMF} is a virtual class. The default class for this #' slot is \code{NMFstd}, that implements the standard NMF model. #' #' @slot residuals A \code{numeric} vector that contains the final #' residuals or the residuals track between the target matrix and its NMF #' estimate(s). Default value is \code{numeric()}. #' #' See method \code{\link{residuals}} for details on accessor methods and main #' interface \code{\link{nmf}} for details on how to compute NMF with residuals #' tracking. #' #' @slot method a single \code{character} string that contains the #' name of the algorithm used to fit the model. #' Default value is \code{''}. #' #' @slot seed a single \code{character} string that contains the #' name of the seeding method used to seed the algorithm that fitted the NMF #' model. #' Default value is \code{''}. See \code{\link{nmf}} for more details. #' #' @slot rng an object that contains the RNG settings used for the #' fit. #' Currently the settings are stored as an integer vector, the value of #' \code{\link{.Random.seed}} at the time the object is created. #' It is initialized by the \code{initialized} method. #' See \code{\link{getRNG}} for more details. #' #' @slot distance either a single \code{"character"} string that #' contains the name of the built-in objective function, or a \code{function} #' that measures the residuals between the target matrix and its NMF estimate. #' See \code{\link{objective}} and \code{\link{deviance,NMF-method}}. #' #' @slot parameters a \code{list} that contains the extra parameters #' -- usually specific to the algorithm -- that were used to fit the model. #' #' @slot runtime object of class \code{"proc_time"} that contains #' various measures of the time spent to fit the model. #' See \code{\link[base]{system.time}} #' #' @slot options a \code{list} that contains the options used to #' compute the object. #' #' @slot extra a \code{list} that contains extra miscellaneous data #' for internal usage only. #' For example it can be used to store extra parameters or temporary data, #' without the need to explicitly extend the \code{NMFfit} class. #' Currently built-in algorithms only use this slot to #' store the number of iterations performed to fit the object. #' #' Data that need to be easily accessible by the end-user should rather be set #' using the methods \code{$<-} that sets elements in the \code{list} slot #' \code{misc} -- that is inherited from class \code{\linkS4class{NMF}}. #' #' @slot call stored call to the last \code{nmf} method that generated the #' object. #' #' @export #' @examples #' # run default NMF algorithm on a random matrix #' n <- 50; r <- 3; p <- 20 #' V <- rmatrix(n, p) #' res <- nmf(V, r) #' #' # result class is NMFfit #' class(res) #' isNMFfit(res) #' #' # show result #' res #' #' # compute summary measures #' summary(res, target=V) #' setClass('NMFfit' , representation( fit = 'NMF', # NMF model residuals = 'numeric', # residuals from the target matrix method = 'character', # method used to compute the factorization seed = 'character', # seeding method used to compute the factorization rng = 'ANY', # numerical random seed distance = '.functionSlotNULL', # method used to compute the distance between the target matrix and its NMF estimate parameters = 'list', # method used to compute the factorization runtime = 'proc_time', # running time to perform the NMF options = 'list', # run options extra = 'list' # extra list of results output by the method , call = 'call' # store last call to nmf() ) , prototype = prototype( residuals = numeric(), method = '', seed = '', parameters = list(), extra = list() ) , validity = function(object){ # slot 'objective' must either be a non-empty character string or a function obj <- objective(object) if( is.character(obj) && obj == '') return(paste("Slot 'objective' must either be a non-empty character string or a function definition", sep='')) # everything went fine: return TRUE TRUE } , contains = 'NMF' ) #' The function \code{NMFfit} is a factory method for NMFfit objects, that should #' not need to be called by the user. #' It is used internally by the functions \code{\link{nmf}} and \code{seed} to #' instantiate the starting point of NMF algorithms. #' #' @param fit an NMF model #' @param ... extra argument used to initialise slots in the instantiating #' \code{NMFfit} object. #' @param rng RNG settings specification (typically a suitable value for #' \code{\link{.Random.seed}}). #' #' @rdname NMFfit-class NMFfit <- function(fit=nmfModel(), ..., rng=NULL){ # use current RNG settings if not otherwise provided if( is.null(rng) ) rng <- getRNG() new('NMFfit', fit=fit, ..., rng=rng) } #' Computes and return the estimated target matrix from an NMF model fitted with #' function \code{\link{nmf}}. #' #' It is a shortcut for \code{fitted(fit(object), ...)}, dispatching the call to #' the \code{fitted} method of the actual NMF model. setMethod('fitted', signature(object='NMFfit'), function(object, ...){ fitted(fit(object), ...) } ) #' Returns the basis matrix from an NMF model fitted with #' function \code{\link{nmf}}. #' #' It is a shortcut for \code{.basis(fit(object), ...)}, dispatching the call to #' the \code{.basis} method of the actual NMF model. setMethod('.basis', signature(object='NMFfit'), function(object, ...){ .basis(fit(object), ...) } ) #' Sets the the basis matrix of an NMF model fitted with #' function \code{\link{nmf}}. #' #' It is a shortcut for \code{.basis(fit(object)) <- value}, dispatching the call to #' the \code{.basis<-} method of the actual NMF model. #' It is not meant to be used by the user, except when developing #' NMF algorithms, to update the basis matrix of the seed object before #' returning it. #' setReplaceMethod('.basis', signature(object='NMFfit', value='matrix'), function(object, value){ .basis(fit(object)) <- value object } ) #' Returns the the coefficient matrix from an NMF model fitted with #' function \code{\link{nmf}}. #' #' It is a shortcut for \code{.coef(fit(object), ...)}, dispatching the call to #' the \code{.coef} method of the actual NMF model. setMethod('.coef', signature(object='NMFfit'), function(object, ...){ .coef(fit(object), ...) } ) #' Sets the the coefficient matrix of an NMF model fitted with #' function \code{\link{nmf}}. #' #' It is a shortcut for \code{.coef(fit(object)) <- value}, dispatching the call to #' the \code{.coef<-} method of the actual NMF model. #' It is not meant to be used by the user, except when developing #' NMF algorithms, to update the coefficient matrix in the seed object before #' returning it. #' setReplaceMethod('.coef', signature(object='NMFfit', value='matrix'), function(object, value){ .coef(fit(object)) <- value object } ) #' Method for single NMF fit objects, which returns the indexes of fixed #' basis terms from the fitted model. setMethod('ibterms', 'NMFfit', function(object){ ibterms(fit(object)) } ) #' Method for single NMF fit objects, which returns the indexes of fixed #' coefficient terms from the fitted model. setMethod('icterms', 'NMFfit', function(object){ icterms(fit(object)) } ) #' Returns the offset from the fitted model. setMethod('offset', signature(object='NMFfit'), function(object){ offset(fit(object)) } ) #' Returns the number of iteration performed to fit an NMF model, typically #' with function \code{\link{nmf}}. #' #' Currently this data is stored in slot \code{'extra'}, but this might change #' in the future. setMethod('niter', signature(object='NMFfit'), function(object, ...){ object@extra$iteration } ) #' Sets the number of iteration performed to fit an NMF model. #' #' This function is used internally by the function \code{\link{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 \code{\linkS4class{NMFStrategyFunction}}). #' setReplaceMethod('niter', signature(object='NMFfit', value='numeric'), function(object, value){ if( (length(value) != 1) || value < 0 ) stop("NMF::niter - invalid value for 'niter': single non-negative value is required.", call.=FALSE) object@extra\$iteration <- value object } ) #' Show method for objects of class \code{NMFfit} setMethod('show', 'NMFfit', function(object) { cat("