Probability map
###############

Probability maps are rasters containing each band as a class. Each band represents
the probability of each pixel belonging to a given class in a [0; 1000] range. Band names are
sorted, for example:

+-------------+---+----+----+------+---+----+-----+---+---+
| band name   | 1 | 12 | 13 | 1597 | 2 | 25 | 236 | 3 | 4 |
+-------------+---+----+----+------+---+----+-----+---+---+
| band number | 1 | 2  | 3  | 4    | 5 | 6  | 7   | 8 | 9 |
+-------------+---+----+----+------+---+----+-----+---+---+


Parameters involved
===================

+-----------------------+-------------------+--------------------------+--------------+------------------------------------------+
|Parameter Key          |Parameter section  |Parameter Type            |Default value |Parameter purpose                         |
+=======================+===================+==========================+==============+==========================================+
|enable_probability_map |arg_classification |Boolean                   | False        |enable the probability map generation     |
+-----------------------+-------------------+--------------------------+--------------+------------------------------------------+

Parameters compatibility
========================

The probability maps can only be generated if the shark classifier is used during 
the run.

.. Warning:: 
    if ``enable_probability_map`` is ``True`` then ``classifier`` must be ``'sharkrf'``

Additionnal outputs
===================

Each classifications will generate it own probability map called ``PROBAMAP_TT_model_MM_seed_SS.tif``
in ``classif`` output iota2 directory where TT is the tile's name MM the model's name
and SS the seed number. Once all generated, they are merged under the
``ProbabilityMap_seed_SS.tif`` name into the ``final`` directory.

Internal choices
================

In some case, there is many classifier decisions to a given pixel. This section
detail internal choices in order to provide a probability map without NoData labels.

Post-classification fusion
**************************

By enabling the ``dempster_shafer_SAR_Opt_fusion`` parameter flag, iota2 will
class each pixels invoking the model built thanks to SAR data and the one built
by using optical data. Then, the dempster-shafer is used to attribute the final decision.

Here is the rules to attribute the vector of probability to each pixels

Consider :
    :math:`p`: the pixel of interest
    
    :math:`ProbaMapSAR`: the probability map provided by the SAR model
    
    :math:`ProbaMapOpt`: the probability map provided by the optical model
    
    :math:`ProbaMapOut`: the output probability map
    
    :math:`DS`: the dempster-shafer choice
    
    :math:`DS(p)` in :math:`{0, 1, 2, 3}`
        
        0 : no decision
        
        1 : choice is both
        
        2 : choice is SAR
        
        3 : choice is Optical

Then :
    :math:`ProbaMapOut(p) = 0` if :math:`DS(p) = 0`
    
    :math:`ProbaMapOut(p) = ProbaMapSAR(p)` if :math:`DS(p) = 2`
    
    :math:`ProbaMapOut(p) = ProbaMapOpt(p)` if :math:`DS(p) = 3`
    
    :math:`ProbaMapOut(p) = ProbaMapOpt(p)` if :math:`DS(p) = 1` and :math:`max(ProbaMapOpt(p)) > max(ProbaMapSAR(p))`
    
    :math:`ProbaMapOut(p) = ProbaMapSAR(p)` if :math:`DS(p) = 1` and :math:`max(ProbaMapSAR(p)) > max(ProbaMapOpt(p))`


Too huge regions
****************

Using both parameters ``classifMode`` to ``'separate'`` and ``mode_outside_RegionSplit`` to an integer value, 
many models will be built to a given region. Then each models will votes to each pixels inside the region and 
some fusion rules are involved. Here is the probability maps fusion rule :

the probability of a given class is the mean of all probability provided by each classifier.

Developers corner
=================

Some unit tests are involved by probability maps generation.

Tests
*****

unittests/iota2_tests_classifications.py:Iota2TestClassifications:test_reorder_proba_map
unittests/iota2_tests_optical_sar_fusion.py:Iota2TestOpticalSARFusion:test_compute_probamap_fusion