[docs][python] made OS detection more reliable and little docs improv…

…ements (#1414)

* added missed description of plot_example in python_guide folder and fixed consistency for packages naming

* more reliable OS detection

* fixed grammar

* made pylint happy

CMakeLists.txt

@@ -24,7 +24,7 @@ elseif(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
     message(FATAL_ERROR "Insufficient Clang version")
   endif()
 elseif(CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang")
-    message(FATAL_ERROR "AppleClang wasn't supported. Please see https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#macos")
+    message(FATAL_ERROR "AppleClang isn't supported. Please see https://github.com/Microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#macos")
 endif()
 
 if(APPLE)

R-package/README.md

@@ -1,4 +1,4 @@
-LightGBM R Package
+LightGBM R-package
 ==================
 
 Installation
@@ -37,7 +37,7 @@ cd LightGBM/R-package
 R CMD INSTALL --build . --no-multiarch
 ```
 
-Or build a self-contained R package which can be installed afterwards:
+Or build a self-contained R-package which can be installed afterwards:
 
 ```sh
 git clone --recursive https://github.com/Microsoft/LightGBM
@@ -63,7 +63,7 @@ install_github("Microsoft/LightGBM", subdir = "R-package")
 
 If you are using a precompiled dll/lib locally, you can move the dll/lib into LightGBM root folder, modify `LightGBM/R-package/src/install.libs.R`'s 2nd line (change `use_precompile <- FALSE` to `use_precompile <- TRUE`), and install R-package as usual. **NOTE: If your R version is not smaller than 3.5.0, you should set `DUSE_R35=ON` in cmake options when build precompiled dll/lib**.
 
-When your package installation is done, you can check quickly if your LightGBM R package is working by running the following:
+When your package installation is done, you can check quickly if your LightGBM R-package is working by running the following:
 
 ```r
 library(lightgbm)
@@ -96,7 +96,7 @@ In addition, if you are using a Visual Studio precompiled DLL, assuming you do n
 
 Once you have all this setup, you can use `lgb.dl` from `lgbdl` package to install LightGBM from repository.
 
-For instance, you can install the R package from LightGBM master commit of GitHub with Visual Studio using the following from R:
+For instance, you can install the R-package from LightGBM master commit of GitHub with Visual Studio using the following from R:
 
 ```r
 lgb.dl(commit = "master",

README.md

@@ -54,7 +54,7 @@ More detailed update logs : [Key Events](https://github.com/Microsoft/LightGBM/b
 External (unofficial) Repositories
 ----------------------------------
 
-Julia Package: https://github.com/Allardvm/LightGBM.jl
+Julia-package: https://github.com/Allardvm/LightGBM.jl
 
 JPMML: https://github.com/jpmml/jpmml-lightgbm
 

docs/GPU-Tutorial.rst

@@ -85,7 +85,7 @@ If you want to use the Python interface of LightGBM, you can install it now (alo
 
 You need to set an additional parameter ``"device" : "gpu"`` (along with your other options like ``learning_rate``, ``num_leaves``, etc) to use GPU in Python.
 
-You can read our `Python Package Examples`_ for more information on how to use the Python interface.
+You can read our `Python-package Examples`_ for more information on how to use the Python interface.
 
 Dataset Preparation
 -------------------
@@ -194,7 +194,7 @@ Huan Zhang, Si Si and Cho-Jui Hsieh. "`GPU Acceleration for Large-scale Tree Boo
 
 .. _AMDGPU-Pro: http://support.amd.com/en-us/download/linux
 
-.. _Python Package Examples: https://github.com/Microsoft/LightGBM/tree/master/examples/python-guide
+.. _Python-package Examples: https://github.com/Microsoft/LightGBM/tree/master/examples/python-guide
 
 .. _GPU Acceleration for Large-scale Tree Boosting: https://arxiv.org/abs/1706.08359
 

docs/Key-Events.md

@@ -29,28 +29,28 @@ The list includes the commits where the major feature added is considered workin
 | 13/04/2017 | [ab55910](https://github.com/Microsoft/LightGBM/pull/404) | Feature | Speed Improvements for Prediction (Pull Request 404) |
 | 06/04/2017 | [bfb0217](https://github.com/Microsoft/LightGBM/pull/383) | Feature | Objective Transformations to the Objective (Pull Request 383) |
 | 05/04/2017 | [d4c4d9a](https://github.com/Microsoft/LightGBM/pull/381) | Feature | Regression Speed Improvements (Pull Request 381) |
-| 03/04/2017 | [b6c973a](https://github.com/Microsoft/LightGBM/pull/378) | Feature | Unloading Memory Fix support for R package (Pull Request 378) |
+| 03/04/2017 | [b6c973a](https://github.com/Microsoft/LightGBM/pull/378) | Feature | Unloading Memory Fix support for R-package (Pull Request 378) |
 | 17/03/2017 | [06a915a](https://github.com/Microsoft/LightGBM/pull/347) | Feature | RDS support for R pacakge (Pull Request 347) |
-| 10/03/2017 | [b7e5f07](https://github.com/Microsoft/LightGBM/pull/340) | Feature | Support Self-Contained R package (Pull Request 340) |
-| 02/03/2017 | [4d6ff28](https://github.com/Microsoft/LightGBM/pull/330) | Feature | Feature Contribution Plot for R package (Pull Request 330) |
-| 01/03/2017 | [166421e](https://github.com/Microsoft/LightGBM/pull/328) | Feature | Feature Importance Plot for R package (Pull Request 328) |
-| 27/02/2017 | [fddb52f](https://github.com/Microsoft/LightGBM/pull/323) | Feature | Feature Contribution for R package (Pull Request 323) |
+| 10/03/2017 | [b7e5f07](https://github.com/Microsoft/LightGBM/pull/340) | Feature | Support Self-Contained R-package (Pull Request 340) |
+| 02/03/2017 | [4d6ff28](https://github.com/Microsoft/LightGBM/pull/330) | Feature | Feature Contribution Plot for R-package (Pull Request 330) |
+| 01/03/2017 | [166421e](https://github.com/Microsoft/LightGBM/pull/328) | Feature | Feature Importance Plot for R-package (Pull Request 328) |
+| 27/02/2017 | [fddb52f](https://github.com/Microsoft/LightGBM/pull/323) | Feature | Feature Contribution for R-package (Pull Request 323) |
 | 20/02/2017 | [10212b5](https://github.com/Microsoft/LightGBM/pull/300) | Release | v2 (Pull Request 300) |
 | 12/02/2017 | [ea6bc0a](https://github.com/Microsoft/LightGBM/pull/290) | Release | v1 (Pull Request 290) |
 | 02/02/2017 | [8c8ed6c](https://github.com/Microsoft/LightGBM/pull/275) | Feature | Docker support (Pull Request 275) |
 | 30/01/2017 | [4f3e9d8](https://github.com/Microsoft/LightGBM/pull/270) | Feature | Poisson Objective support (Pull Request 270) |
-| 28/01/2017 | [5856554](https://github.com/Microsoft/LightGBM/pull/266) | Feature | Plot Metric support for Python package (Pull Request 266) |
-| 25/01/2017 | [8980fc7](https://github.com/Microsoft/LightGBM/pull/262) | Feature | Plot Tree support for Python package (Pull Request 262)<br>With original ([fafbcb3](https://github.com/Microsoft/LightGBM/pull/258) on 25/01/2017, Pull Request 258) |
-| 20/01/2017 | [abaefb5](https://github.com/Microsoft/LightGBM/pull/237) | Feature | Feature Importance Plot for Python package (Pull Request 237) |
-| 16/01/2017 | [a2ae838](https://github.com/Microsoft/LightGBM/pull/229) | Feature | Categorical Feature support for R package (Pull Request 229) |
-| 16/01/2017 | [57d5527](https://github.com/Microsoft/LightGBM/pull/218) | Feature | Pandas Categorical support for Python package (Pull Request 193)<br>With original ([a2ae838](https://github.com/Microsoft/LightGBM/pull/193) on 12/01/2017, Pull Request 193) |
+| 28/01/2017 | [5856554](https://github.com/Microsoft/LightGBM/pull/266) | Feature | Plot Metric support for Python-package (Pull Request 266) |
+| 25/01/2017 | [8980fc7](https://github.com/Microsoft/LightGBM/pull/262) | Feature | Plot Tree support for Python-package (Pull Request 262)<br>With original ([fafbcb3](https://github.com/Microsoft/LightGBM/pull/258) on 25/01/2017, Pull Request 258) |
+| 20/01/2017 | [abaefb5](https://github.com/Microsoft/LightGBM/pull/237) | Feature | Feature Importance Plot for Python-package (Pull Request 237) |
+| 16/01/2017 | [a2ae838](https://github.com/Microsoft/LightGBM/pull/229) | Feature | Categorical Feature support for R-package (Pull Request 229) |
+| 16/01/2017 | [57d5527](https://github.com/Microsoft/LightGBM/pull/218) | Feature | Pandas Categorical support for Python-package (Pull Request 193)<br>With original ([a2ae838](https://github.com/Microsoft/LightGBM/pull/193) on 12/01/2017, Pull Request 193) |
 | 10/01/2017 | [fb732c3](https://github.com/Microsoft/LightGBM/pull/180) | Feature | Fair Loss Objective support (Pull Request 180) |
 | 09/01/2017 | [27d3eb3](https://github.com/Microsoft/LightGBM/pull/178) | Feature | Huber Loss Objective support (Pull Request 178)<br>With original ([a87af87](https://github.com/Microsoft/LightGBM/pull/174) on 09/01/2017, Pull Request 174) |
 | 09/01/2017 | [9b2558d](https://github.com/Microsoft/LightGBM/pull/177) | Feature | devtools R Installation support (Pull Request 177) |
 | 09/01/2017 | [6219df7](https://github.com/Microsoft/LightGBM/pull/175) | Feature | L1 Loss Objective support (Pull Request 175) |
 | 08/01/2017 | [551d59c](https://github.com/Microsoft/LightGBM/pull/168) | Release | R support (Pull Request 168) |
 | 05/01/2017 | [96d08f4](https://github.com/Microsoft/LightGBM/pull/153) | Feature | PMML support (Pull Request 153) |
-| 01/01/2017 | [a034cee](https://github.com/Microsoft/LightGBM/pull/151) | Feature | Pickle support for Python package (Pull Request 151) |
+| 01/01/2017 | [a034cee](https://github.com/Microsoft/LightGBM/pull/151) | Feature | Pickle support for Python-package (Pull Request 151) |
 | 26/12/2016 | [96cba41](https://github.com/Microsoft/LightGBM/pull/139) | Parameter | DART xgboost support (Pull Request 139) |
 | 19/12/2016 | [99b483d](https://github.com/Microsoft/LightGBM/pull/133) | Parameter | Learning Rate in DART support (Pull Request 133) |
 | 01/12/2016 | [16d1853](https://github.com/Microsoft/LightGBM/pull/94) | Release | Python support (Pull Request 94) |
@@ -89,28 +89,28 @@ The list includes the commits where the major feature added is considered workin
 * 13/04/2017 ([Microsoft/LightGBM@ab55910](https://github.com/Microsoft/LightGBM/pull/404)): Feature: Speed Improvements for Prediction (Pull Request 404)
 * 06/04/2017 ([Microsoft/LightGBM@bfb0217](https://github.com/Microsoft/LightGBM/pull/383)): Feature: Objective Transformations to the Objective (Pull Request 383)
 * 05/04/2017 ([Microsoft/LightGBM@d4c4d9a](https://github.com/Microsoft/LightGBM/pull/381)): Feature: Regression Speed Improvements (Pull Request 381)
-* 03/04/2017 ([Microsoft/LightGBM@b6c973a](https://github.com/Microsoft/LightGBM/pull/378)): Feature: Unloading Memory Fix support for R package (Pull Request 378)
+* 03/04/2017 ([Microsoft/LightGBM@b6c973a](https://github.com/Microsoft/LightGBM/pull/378)): Feature: Unloading Memory Fix support for R-package (Pull Request 378)
 * 17/03/2017 ([Microsoft/LightGBM@06a915a](https://github.com/Microsoft/LightGBM/pull/347)): Feature: RDS support for R pacakge (Pull Request 347)
-* 10/03/2017 ([Microsoft/LightGBM@b7e5f07](https://github.com/Microsoft/LightGBM/pull/340)): Feature: Support Self-Contained R package (Pull Request 340)
-* 02/03/2017 ([Microsoft/LightGBM@4d6ff28](https://github.com/Microsoft/LightGBM/pull/330)): Feature: Feature Contribution Plot for R package (Pull Request 330)
-* 01/03/2017 ([Microsoft/LightGBM@166421e](https://github.com/Microsoft/LightGBM/pull/328)): Feature: Feature Importance Plot for R package (Pull Request 328)
-* 27/02/2017 ([Microsoft/LightGBM@fddb52f](https://github.com/Microsoft/LightGBM/pull/323)): Feature: Feature Contribution for R package (Pull Request 323)
+* 10/03/2017 ([Microsoft/LightGBM@b7e5f07](https://github.com/Microsoft/LightGBM/pull/340)): Feature: Support Self-Contained R-package (Pull Request 340)
+* 02/03/2017 ([Microsoft/LightGBM@4d6ff28](https://github.com/Microsoft/LightGBM/pull/330)): Feature: Feature Contribution Plot for R-package (Pull Request 330)
+* 01/03/2017 ([Microsoft/LightGBM@166421e](https://github.com/Microsoft/LightGBM/pull/328)): Feature: Feature Importance Plot for R-package (Pull Request 328)
+* 27/02/2017 ([Microsoft/LightGBM@fddb52f](https://github.com/Microsoft/LightGBM/pull/323)): Feature: Feature Contribution for R-package (Pull Request 323)
 * 20/02/2017 ([Microsoft/LightGBM@10212b5](https://github.com/Microsoft/LightGBM/pull/300)): Release: v2 (Pull Request 300)
 * 12/02/2017 ([Microsoft/LightGBM@ea6bc0a](https://github.com/Microsoft/LightGBM/pull/290)): Release: v1 (Pull Request 290)
 * 02/02/2017 ([Microsoft/LightGBM@8c8ed6c](https://github.com/Microsoft/LightGBM/pull/275)): Feature: Docker support (Pull Request 275)
 * 30/01/2017 ([Microsoft/LightGBM@4f3e9d8](https://github.com/Microsoft/LightGBM/pull/270)): Feature: Poisson Objective support (Pull Request 270)
-* 28/01/2017 ([Microsoft/LightGBM@5856554](https://github.com/Microsoft/LightGBM/pull/266)): Feature: Plot Metric support for Python package (Pull Request 266)
-* 25/01/2017 ([Microsoft/LightGBM@8980fc7](https://github.com/Microsoft/LightGBM/pull/262)): Feature: Plot Tree support for Python package (Pull Request 262) with original ([Microsoft/LightGBM@fafbcb3](https://github.com/Microsoft/LightGBM/pull/258) on 25/01/2017, Pull Request 258)
-* 20/01/2017 ([Microsoft/LightGBM@abaefb5](https://github.com/Microsoft/LightGBM/pull/237)): Feature: Feature Importance Plot for Python package (Pull Request 237)
-* 16/01/2017 ([Microsoft/LightGBM@a2ae838](https://github.com/Microsoft/LightGBM/pull/229)): Feature: Categorical Feature support for R package (Pull Request 229)
-* 16/01/2017 ([Microsoft/LightGBM@57d5527](https://github.com/Microsoft/LightGBM/pull/218)): Feature: Pandas Categorical support for Python package (Pull Request 193) with original ([Microsoft/LightGBM@a2ae838](https://github.com/Microsoft/LightGBM/pull/193) on 12/01/2017, Pull Request 193)
+* 28/01/2017 ([Microsoft/LightGBM@5856554](https://github.com/Microsoft/LightGBM/pull/266)): Feature: Plot Metric support for Python-package (Pull Request 266)
+* 25/01/2017 ([Microsoft/LightGBM@8980fc7](https://github.com/Microsoft/LightGBM/pull/262)): Feature: Plot Tree support for Python-package (Pull Request 262) with original ([Microsoft/LightGBM@fafbcb3](https://github.com/Microsoft/LightGBM/pull/258) on 25/01/2017, Pull Request 258)
+* 20/01/2017 ([Microsoft/LightGBM@abaefb5](https://github.com/Microsoft/LightGBM/pull/237)): Feature: Feature Importance Plot for Python-package (Pull Request 237)
+* 16/01/2017 ([Microsoft/LightGBM@a2ae838](https://github.com/Microsoft/LightGBM/pull/229)): Feature: Categorical Feature support for R-package (Pull Request 229)
+* 16/01/2017 ([Microsoft/LightGBM@57d5527](https://github.com/Microsoft/LightGBM/pull/218)): Feature: Pandas Categorical support for Python-package (Pull Request 193) with original ([Microsoft/LightGBM@a2ae838](https://github.com/Microsoft/LightGBM/pull/193) on 12/01/2017, Pull Request 193)
 * 10/01/2017 ([Microsoft/LightGBM@fb732c3](https://github.com/Microsoft/LightGBM/pull/180)): Feature: Fair Loss Objective support (Pull Request 180)
 * 09/01/2017 ([Microsoft/LightGBM@27d3eb3](https://github.com/Microsoft/LightGBM/pull/178)): Feature: Huber Loss Objective support (Pull Request 178) with original ([Microsoft/LightGBM@a87af87](https://github.com/Microsoft/LightGBM/pull/174) on 09/01/2017, Pull Request 174)
 * 09/01/2017 ([Microsoft/LightGBM@9b2558d](https://github.com/Microsoft/LightGBM/pull/177)): Feature: devtools R Installation support (Pull Request 177)
 * 09/01/2017 ([Microsoft/LightGBM@6219df7](https://github.com/Microsoft/LightGBM/pull/175)): Feature: L1 Loss Objective support (Pull Request 175)
 * 08/01/2017 ([Microsoft/LightGBM@551d59c](https://github.com/Microsoft/LightGBM/pull/168)): Release: R support (Pull Request 168)
 * 05/01/2017 ([Microsoft/LightGBM@96d08f4](https://github.com/Microsoft/LightGBM/pull/153)): Feature: PMML support (Pull Request 153)
-* 01/01/2017 ([Microsoft/LightGBM@a034cee](https://github.com/Microsoft/LightGBM/pull/151)): Feature: Pickle support for Python package (Pull Request 151)
+* 01/01/2017 ([Microsoft/LightGBM@a034cee](https://github.com/Microsoft/LightGBM/pull/151)): Feature: Pickle support for Python-package (Pull Request 151)
 * 26/12/2016 ([Microsoft/LightGBM@96cba41](https://github.com/Microsoft/LightGBM/pull/139)): Parameter: DART xgboost support (Pull Request 139)
 * 19/12/2016 ([Microsoft/LightGBM@99b483d](https://github.com/Microsoft/LightGBM/pull/133)): Parameter: Learning Rate in DART support (Pull Request 133)
 * 01/12/2016 ([Microsoft/LightGBM@16d1853](https://github.com/Microsoft/LightGBM/pull/94)): Release: Python support (Pull Request 94)

docs/Python-Intro.rst

@@ -1,4 +1,4 @@
-Python Package Introduction
+Python-package Introduction
 ===========================
 
 This document gives a basic walkthrough of LightGBM Python-package.

examples/README.md

@@ -3,7 +3,6 @@ Examples
 
 You can learn how to use LightGBM by these examples.
 
-
 Machine Learning Challenge Winning Solutions
 ============================================
 
@@ -25,4 +24,3 @@ Machine Learning Challenge Winning Solutions
 | 3rd     | [Dogs vs. Cats Redux: Kernels Edition](https://www.kaggle.com/c/dogs-vs-cats-redux-kernels-edition) | [link](http://blog.kaggle.com/2017/04/20/dogs-vs-cats-redux-playground-competition-3rd-place-interview-marco-lugo) | - |
 | 3rd     | [Bosch Production Line Performance](https://www.kaggle.com/c/bosch-production-line-performance) | [link](http://blog.kaggle.com/2016/12/15/bosch-production-line-performance-competition-winners-interview-3rd-place-team-data-property-avengers-darragh-marios-mathias-stanislav) | 2016.11 |
 | 1st     | [The 1st Di-Tech Competitions](http://research.xiaojukeji.com/competition/main.action?competitionId=DiTech2016) | - | 2016.7 |
-

examples/python-guide/README.md

@@ -1,4 +1,4 @@
-Python Package Examples
+Python-package Examples
 =======================
 
 Here is an example for LightGBM to use Python-package.
@@ -26,8 +26,10 @@ Examples include:
     - Early stopping
     - Save model to file
 - [sklearn_example.py](https://github.com/Microsoft/LightGBM/blob/master/examples/python-guide/sklearn_example.py)
+    - Create data for learning with sklearn interface 
     - Basic train and predict with sklearn interface
     - Feature importances with sklearn interface
+    - Find best parameters for the model with sklearn's GridSearchCV
 - [advanced_example.py](https://github.com/Microsoft/LightGBM/blob/master/examples/python-guide/advanced_example.py)
     - Set feature names
     - Directly use categorical features without one-hot encoding
@@ -38,11 +40,19 @@ Examples include:
     - Dump and load model with pickle
     - Load model file to continue training
     - Change learning rates during training
+    - Change any parameters during training
     - Self-defined objective function
     - Self-defined eval metric
     - Callback function
 - [logistic_regression.py](https://github.com/Microsoft/LightGBM/blob/master/examples/python-guide/logistic_regression.py)
     - Use objective `xentropy` or `binary`
     - Use `xentropy` with binary labels or probability labels
     - Use `binary` only with binary labels
-    - Compare speed of `xentropy` versus `binary`
+    - Compare speed of `xentropy` versus `binary`
+- [plot_example.py](https://github.com/Microsoft/LightGBM/blob/master/examples/python-guide/plot_example.py)
+    - Construct Dataset
+    - Train and record eval results for further plotting
+    - Plot metrics recorded during training
+    - Plot feature importances
+    - Plot one specified tree
+    - Plot one specified tree with Graphviz

examples/python-guide/logistic_regression.py

@@ -1,4 +1,5 @@
-# pylint: disable = no-name-in-module
+# coding: utf-8
+# pylint: disable = invalid-name, C0111
 '''
 BLUF: The `xentropy` objective does logistic regression and generalizes
 to the case where labels are probabilistic (i.e. numbers between 0 and 1).

examples/python-guide/plot_example.py

@@ -42,7 +42,7 @@
                 evals_result=evals_result,
                 verbose_eval=10)
 
-print('Plot metrics during training...')
+print('Plot metrics recorded during training...')
 ax = lgb.plot_metric(evals_result, metric='l1')
 plt.show()
 

helper/parameter_generator.py

@@ -1,3 +1,9 @@
+# coding: utf-8
+"""This script generates LightGBM/src/io/config_auto.cpp file
+with list of all parameters, aliases table and other routines
+along with parameters description in LightGBM/docs/Parameters.rst file
+from the information in LightGBM/include/LightGBM/config.h file.
+"""
 import os