NMFfitXn-class: Structure for Storing All Fits from Multiple NMF Runs
In renozao/NMF: Algorithms and Framework for Nonnegative Matrix Factorization (NMF)

Description Usage Arguments Details Slots Methods (by generic) See Also Examples

This class is used to return the result from a multiple run of a single NMF algorithm performed with function nmf with option keep.all=TRUE (cf. nmf).

## S4 method for signature 'NMFfitXn'
show(object)

## S4 method for signature 'NMFfitXn'
nbasis(x, ...)

## S4 method for signature 'NMFfitXn'
nrun(object)

## S4 method for signature 'NMFfitXn'
algorithm(object)

## S4 method for signature 'NMFfitXn'
seeding(object)

## S4 method for signature 'NMFfitXn'
modelname(object)

## S4 method for signature 'NMFfitXn'
seqtime(object)

## S4 method for signature 'NMFfitXn'
runtime.all(object, null = FALSE, warning = TRUE)

## S4 method for signature 'NMFfitXn'
minfit(object)

## S4 method for signature 'NMFfitXn'
fit(object)

## S4 method for signature 'NMFfitXn'
consensus(object, ..., no.attrib = FALSE)

## S4 method for signature 'NMFfitXn,ANY'
purity(x, y, method = "best", ...)

## S4 method for signature 'NMFfitXn,ANY'
entropy(x, y, method = "best", ...)

`object`	an object of class `NMFfitXn`
`x`	an `NMFfitXn` object.
`...`	other arguments passed to subsequent calls of suitable methods, usually of the same generic.
`null`	a logical that indicates if the sequential time should be returned if no time data is available in slot ‘runtime.all’.
`warning`	a logical that indicates if a warning should be thrown if the sequential time is returned instead of the real CPU time.
`no.attrib`	a single logical that indicates that no extra attributes should be attached to the result matrix. If `TRUE`, then the following attributes are attached: `nrun`: number of algorithm runs performed; `nbasis`: number of basis components of the fitted model; Also, in this case, the result gains an extra S3 class `NMF.consensus`.
`y`	an object that act as a suitable reference for the computation of performance measures. For purity and entropy this would typically be a `factor` that indicates known column clusters.
`method`	a character string that specifies how the value is computed. It may be either `'best'` or `'mean'` to compute the best or mean purity respectively.

It extends both classes NMFfitX and list, and stores the result of each run (i.e. a NMFfit object) in its list structure.

IMPORTANT NOTE: This class is designed to be read-only, even though all the list-methods can be used on its instances. Adding or removing elements would most probably lead to incorrect results in subsequent calls. Capability for concatenating and merging NMF results is for the moment only used internally, and should be included and supported in the next release of the package.

.Data: standard slot that contains the S3 list object data. See R documentation on S3/S4 classes for more details (e.g., setOldClass).

dim(x = NMFfitXn): Returns the dimension common to all fits.

Since all fits have the same dimensions, it returns the dimension of the first fit. This method returns NULL if the object is empty.
coef(object = NMFfitXn): Returns the coefficient matrix of the best fit amongst all the fits stored in object. It is a shortcut for coef(fit(object)).
basis(object = NMFfitXn): Returns the basis matrix of the best fit amongst all the fits stored in object. It is a shortcut for basis(fit(object)).
getRNG1(object = NMFfitXn): Returns the RNG settings used for the first run.

This method throws an error if the object is empty.
.getRNG(object = NMFfitXn): Returns the RNG settings used for the best fit.

This method throws an error if the object is empty.
compare(object = NMFfitXn): Compares the fits obtained by separate runs of NMF, in a single call to nmf.
show(object = NMFfitXn): Show method for objects of class NMFfitXn
nbasis(x = NMFfitXn): Returns the number of basis components common to all fits.

Since all fits have been computed using the same rank, it returns the factorization rank of the first fit. This method returns NULL if the object is empty.
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).
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.
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.
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.
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.
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.
minfit(object = NMFfitXn): Returns the best NMF model in the list, i.e. the run that achieved the lower estimation residuals.

The model is selected based on its deviance value.
fit(object = NMFfitXn): Returns the best NMF fit object amongst all the fits stored in object, i.e. the fit that achieves the lowest estimation residuals.
consensus(object = NMFfitXn): Computes the consensus matrix of the set of fits stored in object, as the mean connectivity matrix across runs.

This method returns NULL on an empty object. The result is a matrix with several attributes attached, that are used by plotting functions such as consensusmap to annotate the plots.
purity(x = NMFfitXn,y = ANY): Computes the best or mean purity across all NMF fits stored in x.
entropy(x = NMFfitXn,y = ANY): Computes the best or mean entropy across all NMF fits stored in x.

Other multipleNMF: NMFfitX-class, NMFfitX1-class

# generate a synthetic dataset with known classes
n <- 20; counts <- c(5, 2, 3);
V <- syntheticNMF(n, counts)

# get the class factor
groups <- V$pData$Group

# perform multiple runs of one algorithm, keeping all the fits
res <- nmf(V, 3, nrun=3, .options='k') # .options=list(keep.all=TRUE) also works
res
 
summary(res)
# get more info
summary(res, target=V, class=groups)

# compute/show computational times
runtime.all(res)
seqtime(res)

# plot the consensus matrix, computed on the fly
## Not run:  consensusmap(res, annCol=groups)