Merge pull request #13 from hitsz-ids/document-development

update development document

README.md

@@ -15,68 +15,16 @@ Synthetic Data Generator（SDG）是一个专注于结构化表格数据快速
 
 ## 目录
 
+
+- [快速开始](#快速开始)
 - [主要特性](#主要特性)
 - [算法列表](#算法列表)
 - [相关论文和数据集链接](#相关论文和数据集链接)
-- [安装](#安装)
-- [快速开始](#快速开始)
 - [API](#API)
 - [维护者](#维护者)
 - [如何贡献](#如何贡献)
 - [许可证](#许可证)
 
-## 主要特性
-
-+ 支持SOTA工作并进行性能优化
-  + 已支持单表和多表数据合成的10种先进算法，SDG会持续跟踪学术界和工业界的最新进展，及时引入支持优秀算法和模型；
-  + 针对实际生产需求进行优化，提升模型性能，降低内存开销，支持单机多卡、多机多卡等实用特性。
-+ 支持生产环境高效使用
-  + 提供自动化部署、容器化技术、自动化监控和报警等生产环境所需技术；
-  + 针对负载均衡和容错性进行专门优化，提升组件可用性。
-+ 支持中文敏感数据自动检测与匿名化
-  + 提供中文敏感数据自动识别能力，包括姓名、身份证号、人名等17种常见敏感字段；
-  + 实现对敏感字段的匿名化，保证合成数据的安全性。
-
-## 算法列表
-
-### 表1：单表合成算法效果对比(F1-score)
-
-|    模型    | Adult(二分类数据集)(%) | Satellite(多分类数据集)(%) |
-| :--------: | :--------------------: | :------------------------: |
-| 原始数据集 |          69.5          |           89.23           |
-|   CTGAN   |         60.38         |           69.43           |
-|    TVAE    |         59.52         |           83.58           |
-| table-GAN |         63.29         |           79.15           |
-|  CTAB-GAN  |         58.59         |           79.24           |
-|  OCT-GAN  |         55.18         |           80.98           |
-|  CorTGAN  |    **67.13**    |      **84.27**      |
-
-### 表2：多表合成算法效果对比
-
-|    模型    | Rossmann(回归数据集)(rmspe) | Telstra(分类数据集)(mlogloss) |
-| :--------: | :-------------------------: | :---------------------------: |
-| 原始数据集 |           0.2217           |            0.5381            |
-|    SDV    |           0.6897           |            1.1719            |
-|   CWAMT   |      **0.4348**      |        **0.818**        |
-
-### 相关论文和数据集链接
-
-#### 论文
-
-- CTGAN：[Modeling Tabular Data using Conditional GAN](https://proceedings.neurips.cc/paper/2019/hash/254ed7d2de3b23ab10936522dd547b78-Abstract.html)
-- TVAE：[Modeling Tabular Data using Conditional GAN](https://proceedings.neurips.cc/paper/2019/hash/254ed7d2de3b23ab10936522dd547b78-Abstract.html)
-- table-GAN：[Data Synthesis based on Generative Adversarial Networks](https://arxiv.org/pdf/1806.03384.pdf)
-- CTAB-GAN:[CTAB-GAN: Effective Table Data Synthesizing](https://proceedings.mlr.press/v157/zhao21a/zhao21a.pdf)
-- OCT-GAN: [OCT-GAN: Neural ODE-based Conditional Tabular GANs](https://arxiv.org/pdf/2105.14969.pdf)
-- SDV：[The Synthetic data vault](https://sci-hub.se/10.1109/DSAA.2016.49 "多表合成")
-
-#### 数据集
-
-- [Adult数据集](http://archive.ics.uci.edu/ml/datasets/adult)
-- [Satellite数据集](http://archive.ics.uci.edu/dataset/146/statlog+landsat+satellite)
-- [Rossmann数据集](https://www.kaggle.com/competitions/rossmann-store-sales/data)
-- [Telstra数据集](https://www.kaggle.com/competitions/telstra-recruiting-network/data)
-
 ## 快速开始
 
 ### 从Pypi安装
@@ -146,6 +94,59 @@ sampled_data = model.generate(1000)
 9   28         State-gov  837932  ...             99   United-States  <=50K
 ```
 
+## 主要特性
+
++ 支持SOTA工作并进行性能优化
+  + 已支持单表和多表数据合成的10种先进算法，SDG会持续跟踪学术界和工业界的最新进展，及时引入支持优秀算法和模型；
+  + 针对实际生产需求进行优化，提升模型性能，降低内存开销，支持单机多卡、多机多卡等实用特性。
++ 支持生产环境高效使用
+  + 提供自动化部署、容器化技术、自动化监控和报警等生产环境所需技术；
+  + 针对负载均衡和容错性进行专门优化，提升组件可用性。
++ 支持中文敏感数据自动检测与匿名化
+  + 提供中文敏感数据自动识别能力，包括姓名、身份证号、人名等17种常见敏感字段；
+  + 实现对敏感字段的匿名化，保证合成数据的安全性。
+
+## 算法列表
+
+### 表1：单表合成算法效果对比(F1-score)
+
+|    模型    | Adult(二分类数据集)(%) | Satellite(多分类数据集)(%) |
+| :--------: | :--------------------: | :------------------------: |
+| 原始数据集 |          69.5          |           89.23           |
+|   CTGAN   |         60.38         |           69.43           |
+|    TVAE    |         59.52         |           83.58           |
+| table-GAN |         63.29         |           79.15           |
+|  CTAB-GAN  |         58.59         |           79.24           |
+|  OCT-GAN  |         55.18         |           80.98           |
+|  CorTGAN  |    **67.13**    |      **84.27**      |
+
+### 表2：多表合成算法效果对比
+
+|    模型    | Rossmann(回归数据集)(rmspe) | Telstra(分类数据集)(mlogloss) |
+| :--------: | :-------------------------: | :---------------------------: |
+| 原始数据集 |           0.2217           |            0.5381            |
+|    SDV    |           0.6897           |            1.1719            |
+|   CWAMT   |      **0.4348**      |        **0.818**        |
+
+### 相关论文和数据集链接
+
+#### 论文
+
+- CTGAN：[Modeling Tabular Data using Conditional GAN](https://proceedings.neurips.cc/paper/2019/hash/254ed7d2de3b23ab10936522dd547b78-Abstract.html)
+- TVAE：[Modeling Tabular Data using Conditional GAN](https://proceedings.neurips.cc/paper/2019/hash/254ed7d2de3b23ab10936522dd547b78-Abstract.html)
+- table-GAN：[Data Synthesis based on Generative Adversarial Networks](https://arxiv.org/pdf/1806.03384.pdf)
+- CTAB-GAN:[CTAB-GAN: Effective Table Data Synthesizing](https://proceedings.mlr.press/v157/zhao21a/zhao21a.pdf)
+- OCT-GAN: [OCT-GAN: Neural ODE-based Conditional Tabular GANs](https://arxiv.org/pdf/2105.14969.pdf)
+- SDV：[The Synthetic data vault](https://sci-hub.se/10.1109/DSAA.2016.49 "多表合成")
+
+#### 数据集
+
+- [Adult数据集](http://archive.ics.uci.edu/ml/datasets/adult)
+- [Satellite数据集](http://archive.ics.uci.edu/dataset/146/statlog+landsat+satellite)
+- [Rossmann数据集](https://www.kaggle.com/competitions/rossmann-store-sales/data)
+- [Telstra数据集](https://www.kaggle.com/competitions/telstra-recruiting-network/data)
+
+
 ## API
 
 具体接口参数请参考 [API文档](https://SDG.readthedocs.io/en/latest/api/index.html) 【TBD】。

docs/develop/readme.md

@@ -0,0 +1,13 @@
+# 开发指南
+
+## 目录说明
+
+本目录中包含针对多种模型/模块的开发文档以及说明：
+
+- 单表模型（基于GAN的）：请见 [single_table_GAN.md](single_table_GAN.md)；
+- 单表模型（基于统计学方法的）：TBD
+- 多表模型：TBD
+- 序列模型：TBD
+- 其他：TBD
+
+后续我们将逐渐补全更多模型的开发文档。

docs/develop/single_table_GAN.md

@@ -0,0 +1,152 @@
+# SDG 模型开发文档
+
+## 为 SDG 开发可运行的单表模型模块
+
+本文档描述了如何开发模型算法模块，使得该模块可以在 sdgx 架构下被调用。
+
+要开发模块，需要执行以下 5 个步骤：
+
+1.  明确需要开发的模块类型；
+2.  算法模块需要继承`BaseSynthesizerModel`类，并完成几个指定的函数；
+3.  定义模型所需的`Discriminator`类（可选）；
+4.  定义模型所需的`Generator`类（可选）；
+5.  本地安装以及测试您的模型。
+
+在以下各节中，我们将通过 `CTGAN` 这一例子详细描述这 5 个步骤。
+
+## 第一步：明确需要开发的模块类型
+
+首先，您需要明确需要开发的模型类型，目前我们支持：
+
+- 单表模型（基于GAN的）
+- 单表模型（基于统计学方法的）
+- 多表模型
+- 序列模型
+- 其他
+
+目前，其他模块仍在开发中，我们目前给出了单表模块（基于GAN）的开发文档。
+
+如果您正在开发的基于GAN的单表模块，请继续往下看。
+
+
+## 第二步：定义您的模型类
+
+大体上讲，定义一个算法模块需要继承`BaseSynthesizerModel`基类，并完成几个指定的函数，即可成为您自己实现的模型模块。
+
+其具体步骤如下：
+
+1.  在 [single_tablem目录](../../sdgx/models/single_table/) 中创建名为 xxx.py 的 Python 脚本文件，其中 xxx 是您打算开发的模块。
+
+2.  继承 `BaseSynthesizerModel`基类 。
+
+      - 首先从 `sdgx/models/base.py` 中导入基类，并且导入其他必要的 Python 包，例如：
+        ```python
+            import warnings
+            import numpy as np
+            import pandas as pd
+            import torch
+            from torch import optim
+            from torch.nn import (
+                BatchNorm1d,
+                Dropout,
+                LeakyReLU,
+                Linear,
+                Module,
+                ReLU,
+                Sequential,
+                functional,
+            )
+            from sdgx.models.base import BaseSynthesizerModel
+            from sdgx.transform.sampler import DataSamplerCTGAN
+            from sdgx.transform.transformer import DataTransformerCTGAN
+        ```
+
+      - 完成您的模块中的 `__init__` 函数，并定义相应的类变量，以CTGAN为例：
+
+          ```python
+            class CTGAN(BaseSynthesizerModel):
+                def __init__(
+                    self,
+                    embedding_dim=128,
+                    generator_dim=(256, 256),
+                    discriminator_dim=(256, 256),
+                    generator_lr=2e-4,
+                    generator_decay=1e-6
+                    # ...
+                    # 本文档仅为示意，篇幅原因，更多参数已省略
+                ):
+                    assert batch_size % 2 == 0
+
+                    self._embedding_dim = embedding_dim
+                    self._generator_dim = generator_dim
+                    self._discriminator_dim = discriminator_dim
+
+                    self._generator_lr = generator_lr
+                    self._generator_decay = generator_decay
+                    self._discriminator_lr = discriminator_lr
+                    self._discriminator_decay = discriminator_decay
+
+                    # ...
+                    # 本文档仅为示意，篇幅原因，更多参数已省略
+          ```
+
+      - 为了顺利使用sdg，您必须完成 `fit` 与 `sample` 这两个方法，它们有关仿真数据模型训练与数据的生成。
+
+
+## 第三步：定义模型所需的`Discriminator`类（可选）
+
+仅在此模块需要使用生成对抗网络（GAN）技术时候才需要执行此步骤。
+
+您需要在同一个目录中定义`Discriminator`类，并实现 `__init__`、`calc_gradient_penalty``` 以及 `forward`方法。
+
+以CTGAN为例：
+
+```python
+class Discriminator(Module):
+
+    def __init__(self, input_dim, discriminator_dim, pac=10):
+        super(Discriminator, self).__init__()
+
+    def calc_gradient_penalty(self, real_data, fake_data, device="cpu", pac=10, lambda_=10):
+        alpha = torch.rand(real_data.size(0) // pac, 1, 1, device=device)
+        alpha = alpha.repeat(1, pac, real_data.size(1))
+        # 部分代码被省略
+
+        return gradient_penalty
+
+    def forward(self, input_):
+        assert input_.size()[0] % self.pac == 0
+        return self.seq(input_.view(-1, self.pacdim))
+```
+
+
+
+## 第四步：定义模型所需的`Generator`类（可选）
+
+仅在此模块需要使用生成对抗网络（GAN）技术时候才需要执行此步骤。
+
+您需要在同一个目录中定义`Generator`类，并实现 `__init__`以及 `forward`方法。
+
+以CTGAN为例：
+
+```python
+class Generator(Module):
+
+    def __init__(self, embedding_dim, generator_dim, data_dim):
+        super(Generator, self).__init__()
+        # 处于文档说明目的，部分代码被省略
+        self.seq = Sequential(*seq)
+
+    def forward(self, input_):
+        data = self.seq(input_)
+        return data
+```
+
+
+## 第五步: 本地安装以及测试您的模型
+
+在完成模块的代码编写后，您可以通过 `example/` 目录中的示例代码，将其中模型替换为您开发的模型，初步测试模型是否可用。
+
+单元测试模块将在后续工作中逐步补充。
+
+目前 Log 模块还尚未完成开发，未来，您还可以在以下路径中检查日志：`$PROJECT_DIR/log/{your jobid}`.

docs/quick_start.md → docs/readme.md

@@ -1,8 +1,9 @@
----
-sidebar_position: 1
----
 # 快速入门
 
+## 快速安装
+
+`pip install sdgx`
+
 ## 单表数据快速合成示例
 
 ```python