[Docs] improve data format.

4T-Shirt · Jul 12, 2017 · 2bfb35b · 2bfb35b
1 parent b22c8dc
commit 2bfb35b
Show file tree

Hide file tree

Showing 7 changed files with 82 additions and 75 deletions.
diff --git a/docs/algo/data_format.md b/docs/algo/data_format.md
@@ -0,0 +1,48 @@
+# Angel数据格式
+
+## 1 libsvm格式
+
+每行文本表示一个样本，每个样本的格式为
+```
+label index1:value1 index2:value1 index3:value3 ...
+```
+
+其中
+* label字段：
+  - 字段类型：Int
+  - 当输入数据是训练数据，label为样本的标签，二分类算法label是{0, 1}，多分类算法label是{0, 1, 2, ..., n} ；
+  - 当输入数据是预测数据，label是样本的index；
+* index:value字段：
+  - 特征index对应的value，index类型为Int，value类型为Double
+  - 特征的index，从0开始计数
+* 与标准的libsvm格式唯一的不同是：标准的libsvm要求index从1开始计数，而Angel的libsvm格式是从0开始计数。
+
+```
+# libsvm样例数据
+ 1 1:0.5 3:3.1 7:1.0
+ 0 2:0.1 3:2.3 5:2.0
+ 1 4:0.2 7:1.1 9:0.0
+    ....
+```
+
+## 2 dummy格式
+
+每一行为一条记录(一个样本)，每个字段以","分隔，每行的文本格式
+```
+"label,index1,index2,index3"
+```
+* label字段
+  - 字段类型：Int
+  - 当输入数据是训练数据，label为样本的标签，二分类算法label是{0, 1}，多分类算法label是{0, 1, 2, ..., n} ；
+  - 当输入数据是预测数据，label是样本的index；
+* index字段
+  - 字段类型：Int/Long
+  - 特征的index，从0开始计数
+  - 这些是特征值为1的index，其他的就是特征值为0的index
+
+```
+# 数据格式样例
+0,3,7,999,666
+1,0,2,88,77
+  ...
+```
diff --git a/docs/algo/dummy_libsvm.md b/docs/algo/dummy_libsvm.md
diff --git a/docs/algo/gbdt_on_angel.md b/docs/algo/gbdt_on_angel.md
@@ -81,8 +81,8 @@ GBDT的流程包括几大步骤
 
 ### 输入格式
 
-* 数据的格式通过“ml.data.type”参数设置。GBDT on Angel支持“libsvm”、“dummy”两种数据格式，具体参考:[dummy & libSVM](dummy_libsvm.md)
-
+* 数据的格式通过“ml.data.type”参数设置。GBDT on Angel支持“libsvm”、“dummy”两种数据格式，具体参考:[Angel数据格式](data_format.md)
+
 * 特征向量的维度通过参数“ml.feature.num”设置。
 
 
@@ -118,11 +118,11 @@ GBDT的流程包括几大步骤
 | UserGender1  |    24GB    |   1250万  |   2570   | 二分类 |
 | UserGender2  |    145GB    |   1.2亿  |   33万   | 二分类 |
 
-实验的目的，是预测用户的性别
-
-* 数据集 **UserGender1** 大小为24GB，包括1250万个训练数据，其中每个训练数据的特征纬度是2570；
-* 数据集 **UserGender2** 大小为145GB，包括1.2亿个训练数据，其中每个训练数据的特征纬度是33万。
-
+实验的目的，是预测用户的性别
+
+* 数据集 **UserGender1** 大小为24GB，包括1250万个训练数据，其中每个训练数据的特征纬度是2570；
+* 数据集 **UserGender2** 大小为145GB，包括1.2亿个训练数据，其中每个训练数据的特征纬度是33万。
+
 两个数据集都是高维稀疏数据集。
 
 * **实验环境**

diff --git a/docs/algo/kmeans_on_angel.md b/docs/algo/kmeans_on_angel.md
@@ -1,9 +1,9 @@
 # KMeans
-
-> KMeans是一种简单的聚类算法，将数据集划分为多个簇，K为簇的个数。传统的KMeans算法，有一定的性能瓶颈，通过PS实现的KMeans，在准确率一致的情况下，性能更佳。
-
+
+> KMeans是一种简单的聚类算法，将数据集划分为多个簇，K为簇的个数。传统的KMeans算法，有一定的性能瓶颈，通过PS实现的KMeans，在准确率一致的情况下，性能更佳。
+
 ## 1. 算法介绍
-
+
 每个样本被划分到距离最近的簇。每个簇所有样本的几何中心为这个簇的簇心，样本到簇心的距离为样本到簇的距离。Kmeans算法一般以迭代的方式训练，如下所示：  
 
 ![kmeans](../img/kmeans.png)   
@@ -18,23 +18,25 @@
 
 
 ## 2. 分布式实现 on Angel
-
+
 ### 模型存储
 Angel实现的KMeans算法将K个簇心存储在ParameterServer上，用一个K×N维的矩阵表示，其中：K为簇心的个数，N为数据的维度，即特征的个数。
-
+
 ### 模型更新
 KMeans on Angel以迭代的方式训练，每次训练以上文提到的mini-batch KMeans算法更新簇心。
-
+
 ### 算法逻辑
 KMeans on Angel的算法流程如下图所示：
 ![KMeans_on_Angel](../img/KMeans_on_Angel.png)  
-
-
-## 3. 运行 & 性能
-
-### 输入格式
-
-### 参数
+
+
+## 3. 运行 & 性能
+
+### 输入格式
+
+* 数据的格式通过“ml.data.type”参数设置。支持“libsvm”、“dummy”两种数据格式，具体参考:[Angel数据格式](data_format.md)
+
+### 参数
 * IO参数
   * angel.train.data.path：输入数据路径
   * ml.feature.num：数据特征个数
@@ -45,5 +47,5 @@ KMeans on Angel的算法流程如下图所示：
   * ml.kmeans.center.num：K值，即簇的个数
   * ml.kmeans.sample.ratio.perbath：每次迭代选择mini-batch样本的采样率
   * ml.kmeans.c：学习速率参数
-
-### 性能
+
+### 性能
diff --git a/docs/algo/lr_on_angel.md b/docs/algo/lr_on_angel.md
@@ -37,7 +37,7 @@
 
 ### 输入格式
 
-* 数据的格式通过“ml.data.type”参数设置，支持“libsvm”、“dummy”两种数据格式
+* 数据的格式通过“ml.data.type”参数设置。支持“libsvm”、“dummy”两种数据格式，具体参考:[Angel数据格式](data_format.md)
 * 特征向量的维度通过参数“ml.feature.num”设置
 
 
@@ -63,13 +63,13 @@
   * angel.worker.memory.mb：Worker申请内存大小    
   * angel.worker.task.number：每个Worker上的task的个数，默认为1    
   * angel.ps.number：PS个数    
-  * angel.ps.memory.mb：PS申请内存大小   
-
+  * angel.ps.memory.mb：PS申请内存大小   
+
 ### **输出说明** 
 
 ###  **提交命令**    
-
-* **训练任务**
+
+* **训练任务**
 
 ```java
 ./bin/angel-submit \
@@ -92,7 +92,7 @@
     --angel.ps.memory.mb 5000 \
     --angel.job.name=angel_lr_smalldata
 ```
-* **预测任务**
+* **预测任务**
 
 ```java
 ./bin/angel-submit \

diff --git a/docs/algo/sparselr_on_angel.md b/docs/algo/sparselr_on_angel.md
@@ -14,15 +14,7 @@ SparseLogisticRegression与LogisticRegression的区别在于SparseLogisticRegres
 
 数据的格式通过“ml.data.type”参数设置；数据特征的个数，即特征向量的维度通过参数“ml.feature.num”设置。
 
-SparseLR on Angel支持“libsvm”、“dummy”两种数据格式，分别如下所示：
-
-* **dummy格式**
-
-每行文本表示一个样本，每个样本的格式为"y index1 index2 index3 ..."。其中：index特征的ID；训练数据的y为样本的类别，可以取0、1两个值；
-
- * **libsvm格式**
-
-每行文本表示一个样本，每个样本的格式为"y index1:value1 index2:value1 index3:value3 ..."。其中：index为特征的ID,value为对应的特征值；训练数据的y为样本的类别，可以取0、1两个值
+SparseLR on Angel支持“libsvm”、“dummy”两种数据格式，具体参考:[Angel数据格式](data_format.md)
 
 ###  参数
 * 算法参数  

diff --git a/docs/algo/svm_on_angel.md b/docs/algo/svm_on_angel.md
@@ -1,6 +1,6 @@
 # Support Vector Machine(SVM)
 
-> SVM支持向量机器是一种常用的分类算法
+> SVM支持向量机器是一种常用的分类算法
 
 
 ## 1. 算法介绍
@@ -27,7 +27,7 @@ Angel MLLib提供了用mini-batch gradient descent优化方法求解的SVM二分
 ## 3. 运行 & 性能
 ### 输入格式
 
-* 数据的格式通过“ml.data.type”参数设置。GBDT on Angel支持“libsvm”、“dummy”两种数据格式，具体参考:[dummy & libSVM](dummy_libsvm.md)
+* 数据的格式通过“ml.data.type”参数设置。GBDT on Angel支持“libsvm”、“dummy”两种数据格式，具体参考:[Angel数据格式](data_format.md)
 
 * 特征向量的维度通过参数“ml.feature.num”设置