Style fixes in Python documentation. (#1764)

doc/python/python_intro.md

@@ -8,14 +8,15 @@ This document gives a basic walkthrough of xgboost python package.
 
 Install XGBoost
 ---------------
-To install XGBoost, do the following steps:
+To install XGBoost, do the following:
 
-* You need to run `make` in the root directory of the project
-* In the  `python-package` directory run
+* Run `make` in the root directory of the project
+* In the  `python-package` directory, run
 ```shell
 python setup.py install
 ```
 
+To verify your installation, try to `import xgboost` in Python.
 ```python
 import xgboost as xgb
 ```
@@ -24,37 +25,37 @@ Data Interface
 --------------
 The XGBoost python module is able to load data from:
 - libsvm txt format file
-- Numpy 2D array, and 
-- xgboost binary buffer file. 
+- Numpy 2D array, and
+- xgboost binary buffer file.
 
-The data will be store in a ```DMatrix``` object.
+The data is stored in a ```DMatrix``` object.
 
-* To load a libsvm text file or a XGBoost binary file into ```DMatrix```, the command is:
+* To load a libsvm text file or a XGBoost binary file into ```DMatrix```:
 ```python
 dtrain = xgb.DMatrix('train.svm.txt')
 dtest = xgb.DMatrix('test.svm.buffer')
 ```
-* To load a numpy array into ```DMatrix```, the command is:
+* To load a numpy array into ```DMatrix```:
 ```python
 data = np.random.rand(5,10) # 5 entities, each contains 10 features
 label = np.random.randint(2, size=5) # binary target
 dtrain = xgb.DMatrix( data, label=label)
 ```
-* To load a scpiy.sparse array into ```DMatrix```, the command is:
+* To load a scpiy.sparse array into ```DMatrix```:
 ```python
 csr = scipy.sparse.csr_matrix((dat, (row, col)))
 dtrain = xgb.DMatrix(csr)
 ```
-* Saving ```DMatrix``` into XGBoost binary file will make loading faster in next time:
+* Saving ```DMatrix``` into a XGBoost binary file will make loading faster:
 ```python
 dtrain = xgb.DMatrix('train.svm.txt')
 dtrain.save_binary("train.buffer")
 ```
-* To handle missing value in ```DMatrix```, you can initialize the ```DMatrix``` by specifying missing values:
+* Missing values can be replaced by a default value in the ```DMatrix``` constructor:
 ```python
 dtrain = xgb.DMatrix(data, label=label, missing = -999.0)
 ```
-* Weight can be set when needed:
+* Weights can be set when needed:
 ```python
 w = np.random.rand(5, 1)
 dtrain = xgb.DMatrix(data, label=label, missing = -999.0, weight=w)
@@ -62,7 +63,7 @@ dtrain = xgb.DMatrix(data, label=label, missing = -999.0, weight=w)
 
 Setting Parameters
 ------------------
-XGBoost use list of pair to save [parameters](../parameter.md). Eg
+XGBoost can use either a list of pairs or a dictionary to set [parameters](../parameter.md). For instance:
 * Booster parameters
 ```python
 param = {'bst:max_depth':2, 'bst:eta':1, 'silent':1, 'objective':'binary:logistic' }
@@ -71,9 +72,9 @@ param['eval_metric'] = 'auc'
 ```
 * You can also specify multiple eval metrics:
 ```python
-param['eval_metric'] = ['auc', 'ams@0'] 
+param['eval_metric'] = ['auc', 'ams@0']
 
-# alternativly:
+# alternatively:
 # plst = param.items()
 # plst += [('eval_metric', 'ams@0')]
 ```
@@ -86,27 +87,23 @@ evallist  = [(dtest,'eval'), (dtrain,'train')]
 Training
 --------
 
-With parameter list and data, you are able to train a model.
-* Training
+Training a model requires a parameter list and data set.
 ```python
 num_round = 10
 bst = xgb.train( plst, dtrain, num_round, evallist )
 ```
-* Saving model
-After training, you can save model and dump it out.
+After training, the model can be saved.
 ```python
 bst.save_model('0001.model')
 ```
-* Dump Model and Feature Map
-You can dump the model to txt and review the meaning of model
+The model and its feature map can also be dumped to a text file.
 ```python
 # dump model
 bst.dump_model('dump.raw.txt')
 # dump model with feature map
 bst.dump_model('dump.raw.txt','featmap.txt')
 ```
-* Loading model
-After you save your model, you can load model file at anytime by using
+A saved model can be loaded as follows:
 ```python
 bst = xgb.Booster({'nthread':4}) #init model
 bst.load_model("model.bin") # load data
@@ -127,7 +124,7 @@ This works with both metrics to minimize (RMSE, log loss, etc.) and to maximize
 
 Prediction
 ----------
-After you training/loading a model and preparing the data, you can start to do prediction.
+A model that has been trained or loaded can perform predictions on data sets.
 ```python
 # 7 entities, each contains 10 features
 data = np.random.rand(7, 10)
@@ -135,7 +132,7 @@ dtest = xgb.DMatrix(data)
 ypred = bst.predict(xgmat)
 ```
 
-If early stopping is enabled during training, you can get predicticions from the best iteration with `bst.best_ntree_limit`:
+If early stopping is enabled during training, you can get predictions from the best iteration with `bst.best_ntree_limit`:
 ```python
 ypred = bst.predict(xgmat,ntree_limit=bst.best_ntree_limit)
 ```
@@ -151,14 +148,13 @@ To plot importance, use ``plot_importance``. This function requires ``matplotlib
 xgb.plot_importance(bst)
 ```
 
-To output tree via ``matplotlib``, use ``plot_tree`` specifying ordinal number of the target tree.
-This function requires ``graphviz`` and ``matplotlib``.
+To plot the output tree via ``matplotlib``, use ``plot_tree``, specifying the ordinal number of the target tree. This function requires ``graphviz`` and ``matplotlib``.
 
 ```python
 xgb.plot_tree(bst, num_trees=2)
 ```
 
-When you use ``IPython``, you can use ``to_graphviz`` function which converts the target tree to ``graphviz`` instance. ``graphviz`` instance is automatically rendered on ``IPython``.
+When you use ``IPython``, you can use the ``to_graphviz`` function, which converts the target tree to a ``graphviz`` instance. The ``graphviz`` instance is automatically rendered in ``IPython``.
 
 ```python
 xgb.to_graphviz(bst, num_trees=2)