TrainDimensionalityReduction - Train Dimensionality Reduction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Train a dimensionality reduction model

Detailed description
--------------------

Trainer for dimensionality reduction algorithms (autoencoders, PCA, SOM). All input samples are used to compute the model, like other machine learning models.
The model can be used in the ImageDimensionalityReduction and VectorDimensionalityReduction applications.

Parameters
----------

This section describes in details the parameters available for this application. Table [#]_ presents a summary of these parameters and the parameters keys to be used in command-line and programming languages. Application key is *TrainDimensionalityReduction* .

.. [#] Table: Parameters table for Train Dimensionality Reduction.

+--------------------------------------+-------------------------------------------------+--------------------------+
|Parameter Key                         |Parameter Name                                   |Parameter Type            |
+======================================+=================================================+==========================+
|io                                    |Input and output data                            |Group                     |
+--------------------------------------+-------------------------------------------------+--------------------------+
|io.vd                                 |Input Vector Data                                |Input vector data         |
+--------------------------------------+-------------------------------------------------+--------------------------+
|io.out                                |Output model                                     |Output File name          |
+--------------------------------------+-------------------------------------------------+--------------------------+
|io.stats                              |Input XML image statistics file                  |Input File name           |
+--------------------------------------+-------------------------------------------------+--------------------------+
|feat                                  |Field names to be used for training.             |String list               |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm                             |algorithm to use for the training                |Choices                   |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm som                         |OTB SOM                                          | *Choice*                 |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm autoencoder                 |Shark Autoencoder                                | *Choice*                 |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm pca                         |Shark PCA                                        | *Choice*                 |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.som.s                       |Map size                                         |String list               |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.som.n                       |Neighborhood sizes                               |String list               |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.som.ni                      |NumberIteration                                  |Int                       |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.som.bi                      |BetaInit                                         |Float                     |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.som.bf                      |BetaFinal                                        |Float                     |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.som.iv                      |InitialValue                                     |Float                     |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.autoencoder.nbiter          |Maximum number of iterations during training     |Int                       |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.autoencoder.nbiterfinetuning|Maximum number of iterations during training     |Int                       |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.autoencoder.epsilon         |Epsilon                                          |Float                     |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.autoencoder.initfactor      |Weight initialization factor                     |Float                     |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.autoencoder.nbneuron        |Size                                             |String list               |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.autoencoder.regularization  |Strength of the regularization                   |String list               |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.autoencoder.noise           |Strength of the noise                            |String list               |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.autoencoder.rho             |Sparsity parameter                               |String list               |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.autoencoder.beta            |Sparsity regularization strength                 |String list               |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.autoencoder.learningcurve   |Learning curve                                   |Output File name          |
+--------------------------------------+-------------------------------------------------+--------------------------+
|algorithm.pca.dim                     |Dimension of the output of the pca transformation|Int                       |
+--------------------------------------+-------------------------------------------------+--------------------------+
|ram                                   |Available RAM (Mb)                               |Int                       |
+--------------------------------------+-------------------------------------------------+--------------------------+
|inxml                                 |Load otb application from xml file               |XML input parameters file |
+--------------------------------------+-------------------------------------------------+--------------------------+
|outxml                                |Save otb application to xml file                 |XML output parameters file|
+--------------------------------------+-------------------------------------------------+--------------------------+

**[Input and output data]**: This group of parameters allows setting input and output data.

- **Input Vector Data**: Input geometries used for training (note : all geometries from the layer will be used).
- **Output model**: Output file containing the estimated model (.txt format).
- **Input XML image statistics file**: XML file containing mean and variance of each feature.

**Field names to be used for training.**: List of field names in the input vector data used as features for training.

**algorithm to use for the training**: Choice of the dimensionality reduction algorithm to use for the training. Available choices are: 

- **OTB SOM**: This group of parameters allows setting SOM parameters. .

 * **Map size**: Sizes of the SOM map (one per dimension). For instance, [12;15] means a 2D map of size 12x15. Support2D to 5D maps.
 * **Neighborhood sizes**: Sizes of the initial neighborhood in the SOM map (one per dimension). The number of sizes should be the same as the map sizes.
 * **NumberIteration**: Number of iterations for SOM learning.
 * **BetaInit**: Initial learning coefficient.
 * **BetaFinal**: Final learning coefficient.
 * **InitialValue**: Maximum initial neuron weight.

- **Shark Autoencoder**: This group of parameters allows setting Shark autoencoder parameters. .

 * **Maximum number of iterations during training**: The maximum number of iterations used during training.
 * **Maximum number of iterations during training**: The maximum number of iterations used during fine tuning of the whole network.
 * **Epsilon**: Epsilon.
 * **Weight initialization factor**: Parameter that control the weight initialization of the autoencoder.
 * **Size**: The number of neurons in each hidden layer.
 * **Strength of the regularization**: Strength of the L2 regularization used during training.
 * **Strength of the noise**: Strength of the noise.
 * **Sparsity parameter**: Sparsity parameter.
 * **Sparsity regularization strength**: Sparsity regularization strength.
 * **Learning curve**: Learning error values.

- **Shark PCA**: This group of parameters allows setting Shark PCA parameters. .

 * **Dimension of the output of the pca transformation**: Dimension of the output of the pca transformation.


**Available RAM (Mb)**: Available memory for processing (in MB).

**Load otb application from xml file**: Load otb application from xml file.

**Save otb application to xml file**: Save otb application to xml file.



Example
-------

To run this example in command-line, use the following: 
::

	otbcli_TrainDimensionalityReduction -io.vd cuprite_samples.sqlite -io.out mode.ae -algorithm pca -algorithm.pca.dim 8 -feat value_0 value_1 value_2 value_3 value_4 value_5 value_6 value_7 value_8 value_9

To run this example from Python, use the following code snippet: 

::

	#!/usr/bin/python

	# Import the otb applications package
	import otbApplication

	# The following line creates an instance of the TrainDimensionalityReduction application 
	TrainDimensionalityReduction = otbApplication.Registry.CreateApplication("TrainDimensionalityReduction")

	# The following lines set all the application parameters:
	TrainDimensionalityReduction.SetParameterString("io.vd", "cuprite_samples.sqlite")

	TrainDimensionalityReduction.SetParameterString("io.out", "mode.ae")

	TrainDimensionalityReduction.SetParameterString("algorithm","pca")

	TrainDimensionalityReduction.SetParameterInt("algorithm.pca.dim", 8)

	TrainDimensionalityReduction.SetParameterStringList("feat", ['value_0', 'value_1', 'value_2', 'value_3', 'value_4', 'value_5', 'value_6', 'value_7', 'value_8', 'value_9'])

	# The following line execute the application
	TrainDimensionalityReduction.ExecuteAndWriteOutput()

Limitations
~~~~~~~~~~~

None

Authors
~~~~~~~

This application has been written by OTB-Team.

See Also
~~~~~~~~

These additional resources can be useful for further information: 
  | ImageDimensionalityReduction, VectorDimensionalityReduction