Added text on how probabilities are calculated (#36)

README.md

@@ -11,14 +11,14 @@
 
 ```python
 from albumentations import (
-    HorizontalFlip, IAAPerspective, ShiftScaleRotate, CLAHE, RandomRotate90,
-    Transpose, ShiftScaleRotate, Blur, OpticalDistortion, GridDistortion, HueSaturationValue,
-    IAAAdditiveGaussianNoise, GaussNoise, MotionBlur, MedianBlur, IAAPiecewiseAffine,
-    IAASharpen, IAAEmboss, RandomContrast, RandomBrightness, Flip, OneOf, Compose
+    CLAHE, RandomRotate90, Transpose, ShiftScaleRotate, Blur, OpticalDistortion, 
+    GridDistortion, HueSaturationValue, IAAAdditiveGaussianNoise, GaussNoise, MotionBlur, 
+    MedianBlur, IAAPiecewiseAffine, IAASharpen, IAAEmboss, RandomContrast, RandomBrightness, 
+    Flip, OneOf, Compose
 )
 import numpy as np
 
-def strong_aug(p=.5):
+def strong_aug(p=0.5):
     return Compose([
         RandomRotate90(),
         Flip(),
@@ -29,13 +29,13 @@ def strong_aug(p=.5):
         ], p=0.2),
         OneOf([
             MotionBlur(p=.2),
-            MedianBlur(blur_limit=3, p=.1),
-            Blur(blur_limit=3, p=.1),
+            MedianBlur(blur_limit=3, p=0.1),
+            Blur(blur_limit=3, p=0.1),
         ], p=0.2),
-        ShiftScaleRotate(shift_limit=0.0625, scale_limit=0.2, rotate_limit=45, p=.2),
+        ShiftScaleRotate(shift_limit=0.0625, scale_limit=0.2, rotate_limit=45, p=0.2),
         OneOf([
             OpticalDistortion(p=0.3),
-            GridDistortion(p=.1),
+            GridDistortion(p=0.1),
             IAAPiecewiseAffine(p=0.3),
         ], p=0.2),
         OneOf([

docs/examples.rst

@@ -14,7 +14,7 @@ Examples
    )
    import numpy as np
 
-   def strong_aug(p=.5):
+   def strong_aug(p=0.5):
        return Compose([
            RandomRotate90(),
            Flip(),
@@ -24,14 +24,14 @@ Examples
                GaussNoise(),
            ], p=0.2),
            OneOf([
-               MotionBlur(p=.2),
-               MedianBlur(blur_limit=3, p=.1),
-               Blur(blur_limit=3, p=.1),
+               MotionBlur(p=0.2),
+               MedianBlur(blur_limit=3, p=0.1),
+               Blur(blur_limit=3, p=0.1),
            ], p=0.2),
-           ShiftScaleRotate(shift_limit=0.0625, scale_limit=0.2, rotate_limit=45, p=.2),
+           ShiftScaleRotate(shift_limit=0.0625, scale_limit=0.2, rotate_limit=45, p=0.2),
            OneOf([
                OpticalDistortion(p=0.3),
-               GridDistortion(p=.1),
+               GridDistortion(p=0.1),
                IAAPiecewiseAffine(p=0.3),
            ], p=0.2),
            OneOf([

docs/index.rst

@@ -48,3 +48,4 @@ to adjust image augmentation parameters and see the resulting images.
    examples
    contributing
    api/index
+   probabilities

docs/probabilities.rst

@@ -0,0 +1,62 @@
+About probabilities.
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+
+Default probability values
+******************************
+
+**Compose**, **PadIfNeeded**, **CenterCrop**, **RandomCrop**, **Normalize**, **ToFloat**, **FromFloat**, **ToTensor** have default
+probability values equal to **1**. All other are equal to **0.5**
+
+
+.. code-block:: python
+
+   from albumentations import (
+       RandomRotate90, IAAAdditiveGaussianNoise, GaussNoise
+   )
+   import numpy as np
+
+   def aug(p1):
+       return Compose([
+           RandomRotate90(p=p2),
+           OneOf([
+               IAAAdditiveGaussianNoise(p=0.9),
+               GaussNoise(p=0.6),
+           ], p3=0.2)
+       ], p=p1)
+
+   image = np.ones((300, 300, 3), dtype=np.uint8)
+   mask = np.ones((300, 300), dtype=np.uint8)
+   whatever_data = "my name"
+   augmentation = aug(p=0.9)
+   data = {"image": image, "mask": mask, "whatever_data": whatever_data, "additional": "hello"}
+   augmented = augmentation(**data)
+   image, mask, whatever_data, additional = augmented["image"], augmented["mask"], augmented["whatever_data"], augmented["additional"]
+
+
+
+In the above augmentation pipeline, we have three types of probabilities. Combination of them is the primary factor that
+decides how often each of them will be applied.
+
+ 1. **p1**: decides if this augmentation will be applied. The most common case is **p1=1** means that we always apply the transformations from above. **p1=0** will mean that the transformation block will be ignored.
+ 2. **p2**: every augmentation has an option to be applied with some probability.
+ 3. **p3**: decide if **OneOf** will be applied.
+
+OneOf Block
+**************
+
+To decide which augmentation within **OneOf** block is used the following rule is applied.
+
+ 1. We normalize all probabilities within a block to one. After this we pick augmentation based on the normalized probabilities. In the example above **IAAAdditiveGaussianNoise** has probability **0.9** and **GaussNoise** probability **0.6**. After normalization, they become **0.6** and **0.4**. Which means that we decide if we should use **IAAAdditiveGaussianNoise** with probability **0.6** and **GaussNoise** otherwise.
+ 2. If we picked to consider **GaussNoise** the next step will be to decide if we should use it or not and **p=0.6** will be used in this case.
+
+Example calculations
+*******************
+Thus, each augmentation in the example above will be applied with the probability:
+
+ 1. **RandomRotate90**: `p1 * p2`
+ 2. **IAAAdditiveGaussianNoise**: `p1 * (0.9) / (0.9 + 0.6) * 0.9`
+ 3. **GaussianNoise**: `p1 * (0.6) / (0.9 + 0.6) * 0.6`