# Python 软件包介绍
本文档给出了有关 xgboost python 软件包的基本演练.
**_其他有用的链接列表_**
* [Python 演练代码集合](https://github.com/tqchen/xgboost/blob/master/demo/guide-python)
* [Python API 参考](python_api.html)
## 安装 XGBoost
要安装 XGBoost, 请执行以下步骤:
* 您需要在项目的根目录下运行 `make` 命令
* 在 `python-package` 目录下运行
```
python setup.py install
```
```
import xgboost as xgb
```
## 数据接口
XGBoost python 模块能够使用以下方式加载数据:
* libsvm txt format file（libsvm 文本格式的文件）
* Numpy 2D array, and（Numpy 2维数组, 以及）
* xgboost binary buffer file. （xgboost 二进制缓冲文件）
这些数据将会被存在一个名为 `DMatrix` 的对象中.
* 要加载 ligbsvm 文本格式或者 XGBoost 二进制文件到 `DMatrix` 对象中. 代码如下:
```
dtrain = xgb.DMatrix('train.svm.txt')
dtest = xgb.DMatrix('test.svm.buffer')
```
* 要加载 numpy 的数组到 `DMatrix` 对象中, 代码如下:
```
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)
```
* 要加载 scpiy.sparse 数组到 `DMatrix` 对象中, 代码如下:
```
csr = scipy.sparse.csr_matrix((dat, (row, col)))
dtrain = xgb.DMatrix(csr)
```
* 保存 `DMatrix` 到 XGBoost 二进制文件中后, 会在下次加载时更快:
```
dtrain = xgb.DMatrix('train.svm.txt')
dtrain.save_binary("train.buffer")
```
* 要处理 `DMatrix` 中的缺失值, 您可以通过指定缺失值的参数来初始化 `DMatrix`:
```
dtrain = xgb.DMatrix(data, label=label, missing = -999.0)
```
* 在需要时可以设置权重:
```
w = np.random.rand(5, 1)
dtrain = xgb.DMatrix(data, label=label, missing = -999.0, weight=w)
```
## 设置参数
XGBoost 使用 pair 格式的 list 来保存 [_参数_](../parameter.html). 例如:
* Booster（提升）参数
```
param = {'bst:max_depth':2, 'bst:eta':1, 'silent':1, 'objective':'binary:logistic' }
param['nthread'] = 4
param['eval_metric'] = 'auc'
```
* 您也可以指定多个评估的指标:
```
param['eval_metric'] = ['auc', 'ams@0']
# alternativly:
# plst = param.items()
# plst += [('eval_metric', 'ams@0')]
```
* 指定验证集以观察性能
```
evallist = [(dtest,'eval'), (dtrain,'train')]
```
## 训练
有用参数列表和数据以后, 您现在可以训练一个模型了.
* 训练
```
num_round = 10
bst = xgb.train( plst, dtrain, num_round, evallist )
```
* 保存模型 训练之后，您可以保存模型并将其转储出去.
```
bst.save_model('0001.model')
```
* 转储模型和特征映射 您可以将模型转储到 txt 文件并查看模型的含义
```
# 转存模型
bst.dump_model('dump.raw.txt')
# 转储模型和特征映射
bst.dump_model('dump.raw.txt','featmap.txt')
```
* 加载模型 当您保存模型后, 您可以使用如下方式在任何时候加载模型文件
```
bst = xgb.Booster({'nthread':4}) #init model
bst.load_model("model.bin") # load data
```
## 提前停止
如果您有一个验证集, 你可以使用提前停止找到最佳数量的 boosting rounds（梯度次数）. 提前停止至少需要一个 `evals` 集合. 如果有多个, 它将使用最后一个.
`train(..., evals=evals, early_stopping_rounds=10)`
该模型将开始训练, 直到验证得分停止提高为止. 验证错误需要至少每个 `early_stopping_rounds` 减少以继续训练.
如果提前停止，模型将有三个额外的字段: `bst.best_score`, `bst.best_iteration` 和 `bst.best_ntree_limit`. 请注意 `train()` 将从上一次迭代中返回一个模型, 而不是最好的一个.
这与两个度量标准一起使用以达到最小化（RMSE, 对数损失等）和最大化（MAP, NDCG, AUC）. 请注意, 如果您指定多个评估指标, 则 `param ['eval_metric']` 中的最后一个用于提前停止.
## 预测
当您 训练/加载 一个模型并且准备好数据之后, 即可以开始做预测了.
```
# 7 个样本, 每一个包含 10 个特征
data = np.random.rand(7, 10)
dtest = xgb.DMatrix(data)
ypred = bst.predict(xgmat)
```
如果在训练过程中提前停止, 可以用 `bst.best_ntree_limit` 从最佳迭代中获得预测结果:
```
ypred = bst.predict(xgmat,ntree_limit=bst.best_ntree_limit)
```
## 绘图
您可以使用 plotting（绘图）模块来绘制出 importance（重要性）以及输出的 tree（树）.
要绘制出 importance（重要性）, 可以使用 `plot_importance`. 该函数需要安装 `matplotlib`.
```
xgb.plot_importance(bst)
```
输出的 tree（树）会通过 `matplotlib` 来展示, 使用 `plot_tree` 指定 target tree（目标树）的序号. 该函数需要 `graphviz` 和 `matplotlib`.
```
xgb.plot_tree(bst, num_trees=2)
```
当您使用 `IPython` 时, 你可以使用 `to_graphviz` 函数, 它可以将 target tree（目标树）转换成 `graphviz` 实例. `graphviz` 实例会自动的在 `IPython` 上呈现.
```
xgb.to_graphviz(bst, num_trees=2)
```
