# Factory Method for NMFStrategy Objects

## Description

Creates NMFStrategy objects that wraps implementation of NMF algorithms into a unified interface.

## Usage

```NMFStrategy(name, method, ...)

S4 (NMFStrategy,matrix,NMFfit)
`run`(object, y, x, ...)

S4 (NMFStrategy,matrix,NMF)
`run`(object, y, x, ...)

S4 (NMFStrategyFunction,matrix,NMFfit)
`run`(object, y, x, ...)

S4 (NMFStrategyIterative,matrix,NMFfit)
`run`(object, y, x, .stop = NULL, maxIter = 2000, ...)

S4 (NMFStrategyIterativeX,matrix,NMFfit)
`run`(object, y, x, maxIter, ...)

S4 (NMFStrategyOctave,matrix,NMFfit)
`run`(object, y, x, ...)```

## Arguments

name
name/key of an NMF algorithm.
method
definition of the algorithm
...
extra arguments passed to `new`.
.stop
specification of a stopping criterion, that is used instead of the one associated to the NMF algorithm. It may be specified as:
• the access key of a registered stopping criterion;
• a single integer that specifies the exact number of iterations to perform, which will be honoured unless a lower value is explicitly passed in argument `maxIter`.
• a single numeric value that specifies the stationnarity threshold for the objective function, used in with `nmf.stop.stationary`;
• a function with signature ```(object="NMFStrategy", i="integer", y="matrix", x="NMF", ...)```, where `object` is the `NMFStrategy` object that describes the algorithm being run, `i` is the current iteration, `y` is the target matrix and `x` is the current value of the NMF model.
maxIter
maximum number of iterations to perform.
object
an object computed using some algorithm, or that describes an algorithm itself.
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.

## Methods

1. NMFStrategy```signature(name = "character", method = "function")```: Creates an `NMFStrategyFunction` object that wraps the function `method` into a unified interface.

`method` must be a function with signature `(y="matrix", x="NMFfit", ...)`, and return an object of class `NMFfit-class`.

2. NMFStrategy```signature(name = "character", method = "NMFStrategy")```: Creates an `NMFStrategy` object based on a template object (Constructor-Copy).

3. NMFStrategy```signature(name = "NMFStrategy", method = "missing")```: Creates an `NMFStrategy` based on a template object (Constructor-Copy), in particular it uses the same name.

4. NMFStrategy```signature(name = "missing", method = "character")```: Creates an `NMFStrategy` based on a registered NMF algorithm that is used as a template (Constructor-Copy), in particular it uses the same name.

It is a shortcut for ```NMFStrategy(nmfAlgorithm(method, exact=TRUE), ...)```.

5. NMFStrategy```signature(name = "NULL", method = "NMFStrategy")```: Creates an `NMFStrategy` based on a template object (Constructor-Copy) but using a randomly generated name.

6. NMFStrategy```signature(name = "character", method = "character")```: Creates an `NMFStrategy` based on a registered NMF algorithm that is used as a template.

7. NMFStrategy```signature(name = "NULL", method = "character")```: Creates an `NMFStrategy` based on a registered NMF algorithm (Constructor-Copy) using a randomly generated name.

It is a shortcut for ```NMFStrategy(NULL, nmfAlgorithm(method), ...)```.

8. NMFStrategy```signature(name = "character", method = "missing")```: Creates an NMFStrategy, determining its type from the extra arguments passed in `...`: if there is an argument named `Update` then an `NMFStrategyIterative` is created, or if there is an argument named `algorithm` then an `NMFStrategyFunction` is created. Calls other than these generates an error.

9. run```signature(object = "NMFStrategy", y = "matrix", 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.

10. run```signature(object = "NMFStrategy", y = "matrix", x = "NMF")```: Method to run an NMF algorithm directly starting from a given NMF model.

11. run```signature(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.

12. run```signature(object = "NMFStrategyIterative", y = "matrix", x = "NMFfit")```: Runs an NMF iterative algorithm on a target matrix `y`.

13. run```signature(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.