.. _DimensionalityReduction:

DimensionalityReduction
=======================





Perform Dimension reduction of the input image.

Description
-----------

Performs dimensionality reduction on input image. PCA,NA-PCA,MAF,ICA methods are available. It is also possible to compute the inverse transform to reconstruct the image and to optionally export the transformation matrix to a text file.

This application has several output images and supports "multi-writing". Instead of computing and writing each image independently, the streamed image blocks are written in a synchronous way for each output. The output images will be computed strip by strip, using the available RAM to compute the strip size, and a user defined streaming mode can be specified using the streaming extended filenames (type, mode and value). Note that multi-writing can be disabled using the multi-write extended filename option: &multiwrite=false, in this case the output images will be written one by one. Note that multi-writing is not supported for MPI writers.

Parameters
----------

.. contents:: :local:

.. |br| raw:: html

   <br />

.. |em| raw:: html

   &emsp;

**Input Image** :code:`-in image` *Mandatory* |br|
The input image to apply dimensionality reduction.

**Output Image** :code:`-out image [dtype]` |br|
output image. Components are ordered by decreasing eigenvalues.

**Rescale Output** :code:`-rescale [no|minmax]` *Default value: no* |br|
Enable rescaling of the reduced output image.

* **No rescale** |br| 

* **rescale to min max value** |br| 



rescale to min max value options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Output min value** :code:`-rescale.minmax.outmin float` *Default value: 0* |br|
Minimum value of the output image.

**Output max value** :code:`-rescale.minmax.outmax float` *Default value: 255* |br|
Maximum value of the output image.



------------

** Inverse Output Image** :code:`-outinv image [dtype]` |br|
reconstruct output image.

**Algorithm** :code:`-method [pca|napca|maf|ica]` *Default value: pca* |br|
Selection of the reduction dimension method.

* **PCA** |br| Principal Component Analysis.

* **NA-PCA** |br| Noise Adjusted Principal Component Analysis.

* **MAF** |br| Maximum Autocorrelation Factor.

* **ICA** |br| Independent Component Analysis using a stabilized fixed point FastICA algorithm.



PCA options
^^^^^^^^^^^

**Output file containing eigenvalues (txt format)** :code:`-method.pca.outeigenvalues filename [dtype]` |br|
Output file containing eigenvalues (txt format).

**Perform pca whitening** :code:`-method.pca.whiten bool` *Default value: true* |br|
Perform whitening and ensure uncorrelated outputs with unit component wise variances

NA-PCA options
^^^^^^^^^^^^^^

**Set the x radius of the sliding window** :code:`-method.napca.radiusx int` *Default value: 1* |br|


**Set the y radius of the sliding window** :code:`-method.napca.radiusy int` *Default value: 1* |br|


ICA options
^^^^^^^^^^^

**number of iterations** :code:`-method.ica.iter int` *Default value: 20* |br|


**Give the increment weight of W in [0, 1]** :code:`-method.ica.mu float` *Default value: 1* |br|


**Nonlinearity** :code:`-method.ica.g [tanh|exp|u3]` *Default value: tanh* |br|
Nonlinearity used in the FastICA algorithm

* **tanh** |br| g(x) = tanh(x)

* **exp** |br| g(x) = -exp(-x^2/2)

* **u^3** |br| g(x) = u^3(x)





------------

**Number of Components** :code:`-nbcomp int` *Default value: 0* |br|
Number of relevant components kept. By default all components are kept.

**Center and reduce data** :code:`-normalize bool` *Default value: false* |br|
Center and reduce data before Dimensionality reduction (if this parameter is set to false, the data will be centered but not reduced.

**Transformation matrix output (text format)** :code:`-outmatrix filename [dtype]` |br|
Filename to store the transformation matrix (csv format)

**Background Value** :code:`-bv float` |br|
Background value to ignore in computation of the transformation matrix. Note that all pixels will still be processed when applying the transformation.

**Available RAM (MB)** :code:`-ram int` *Default value: 256* |br|
Available memory for processing (in MB).



Examples
--------

From the command-line:

.. code-block:: bash

    otbcli_DimensionalityReduction -in cupriteSubHsi.tif -out FilterOutput.tif -method pca


From Python:

.. code-block:: python

	import otbApplication

	app = otbApplication.Registry.CreateApplication("DimensionalityReduction")

	app.SetParameterString("in", "cupriteSubHsi.tif")
	app.SetParameterString("out", "FilterOutput.tif")
	app.SetParameterString("method","pca")

	app.ExecuteAndWriteOutput()



Limitations
-----------

This application does not provide the inverse transform and the transformation matrix export for the MAF. the background value option is not supported for MAF and ICA.

See also
--------

| "Kernel maximum autocorrelation factor and minimum noise fraction transformations," IEEE Transactions on Image Processing, vol. 20, no. 3, pp. 612-624, (2011)