[docs] added note about the spoiled probabilities (#2113)

docs/Parameters.rst

@@ -690,6 +690,8 @@ Objective Parameters
 
    -  set this to ``true`` if training data are unbalanced
 
+   -  **Note**: while enabling this should increase the overall performance metric of your model, it will also result in poor estimates of the individual class probabilities
+
    -  **Note**: this parameter cannot be used at the same time with ``scale_pos_weight``, choose only **one** of them
 
 -  ``scale_pos_weight`` :raw-html:`<a id="scale_pos_weight" title="Permalink to this parameter" href="#scale_pos_weight">&#x1F517;&#xFE0E;</a>`, default = ``1.0``, type = double, constraints: ``scale_pos_weight > 0.0``
@@ -698,6 +700,8 @@ Objective Parameters
 
    -  weight of labels with positive class
 
+   -  **Note**: while enabling this should increase the overall performance metric of your model, it will also result in poor estimates of the individual class probabilities
+
    -  **Note**: this parameter cannot be used at the same time with ``is_unbalance``, choose only **one** of them
 
 -  ``sigmoid`` :raw-html:`<a id="sigmoid" title="Permalink to this parameter" href="#sigmoid">&#x1F517;&#xFE0E;</a>`, default = ``1.0``, type = double, constraints: ``sigmoid > 0.0``

include/LightGBM/config.h

@@ -631,12 +631,14 @@ struct Config {
   // alias = unbalance, unbalanced_sets
   // desc = used only in ``binary`` application
   // desc = set this to ``true`` if training data are unbalanced
+  // desc = **Note**: while enabling this should increase the overall performance metric of your model, it will also result in poor estimates of the individual class probabilities
   // desc = **Note**: this parameter cannot be used at the same time with ``scale_pos_weight``, choose only **one** of them
   bool is_unbalance = false;
 
   // check = >0.0
   // desc = used only in ``binary`` application
   // desc = weight of labels with positive class
+  // desc = **Note**: while enabling this should increase the overall performance metric of your model, it will also result in poor estimates of the individual class probabilities
   // desc = **Note**: this parameter cannot be used at the same time with ``is_unbalance``, choose only **one** of them
   double scale_pos_weight = 1.0;
 

python-package/lightgbm/sklearn.py

@@ -170,6 +170,9 @@ class LGBMModel(_LGBMModelBase):
             Weights associated with classes in the form ``{class_label: weight}``.
             Use this parameter only for multi-class classification task;
             for binary classification task you may use ``is_unbalance`` or ``scale_pos_weight`` parameters.
+            Note, that the usage of all these parameters will result in poor estimates of the individual class probabilities.
+            You may want to consider performing probability calibration
+            (https://scikit-learn.org/stable/modules/calibration.html) of your model.
             The 'balanced' mode uses the values of y to automatically adjust weights
             inversely proportional to class frequencies in the input data as ``n_samples / (n_classes * np.bincount(y))``.
             If None, all classes are supposed to have weight one.