add data_structure.md

docs/data_structure.md

@@ -1 +1,191 @@
 # 数据格式抽象
+
+初版需要支持如下几种基础组件：
+
+- 基本组件
+  - scalar
+  - histogram
+  - image
+  - audio
+  - text
+- 高级组件
+  - graph
+
+下面将对这些组件的数据类型进行抽象。
+
+# 宏观信息
+后端的日志会在每个周期追加到 `logdir` 中相应的log文件中，在追加信息的过程中，
+除了graph，其他所有组件均需要时间步等信息，依次下面列出这个过程必须的一些元信息：
+- `step_id` 追加的时间步
+- `UNIX time` 方便追踪速度
+- `tag` 类似TF，每个参与可视化的信息来源必须有一个唯一的命名（可以系统自动生成）
+  - tag会作为特定数据流从前端到后端统一的标识
+
+# 各组件数据抽象
+这里会抽象各组件数据必须存储的信息，为了便于沟通，使用了类似 `JSON` 的格式，
+实际使用中，前后端可以自由选择数据格式，以及数据压缩。
+
+## 抽样
+每个 `tag` 会对应一个log文件，其中会包含全量信息（可以优化），但前端可视化并不需要全量信息，
+这里后端就可以用 `蓄水池抽样` 来对全量数据进行抽样，组织好数据push给前端。
+
+## 增量更新数据
+考虑到前端可视化的动态更新，当前后端的全量数据应该只在第一次访问时才需要push给前端，
+中间状态，后端前端交互的都只需要传递增量数据，具体增量数据格式类似
+
+```javascript
+[
+  [
+    "step_id": 200,
+    "data": <data_type>
+  ]
+]
+```
+
+
+## 统一的数据表示
+上述除了group之外的所有组件的数据，都可以用下述数据格式表示
+
+```
+[
+  // data of each time-step
+  [
+    [
+      "step_id": 12,
+      "unix_time": 1234,
+      "data": [0.1, 0.2, ...]
+    ],
+    // ... other steps
+  ]
+  // meta info
+  [
+    // one of image, text, audio, scalar or histogram
+    "type": "image",
+    "size": [320, 270],
+    "tag": "some-name"
+  ]
+]
+```
+
+下面具体到单个组件，详细验证上述结构适用于每个组件
+
+## scalar
+
+```javascript
+[
+  // step_id is hidden in this array's offsets
+  [
+    "unix_time" : 23323,
+    "data": 23
+  ],
+  [
+    "unix_time" : 23325,
+    "data": 13
+  ]
+]
+```
+
+当然，上面的数据格式在最终存储时，可以折叠为
+
+```
+
+[
+  [23323, 23],
+  [23325, 13]
+]
+```
+这里只关注必要的信息，具体的优化暂不考虑，后续不再赘述。
+
+## histogram
+histogram 需要得到tensor的分布，因此会把完整的tensor 的数值存下，具体的分布可以后端实时（增量）计算
+
+后端存储的数据格式
+
+```javascript
+[
+  [
+    "step_id": 12,
+    "data": [0.12, 0.37, ...]
+  ],
+  [
+    "step_id": 13,
+    "data": [0.13, 0.38, ...]
+  ]
+]
+```
+
+后端会计算好每个时间步的数据分布push给前端，具体数据格式如下
+
+```javascript
+[
+  [
+    "step_id": 12,
+    // n-dim distribution
+    "data": [0.12, 0.23, ...]
+  ]
+]
+```
+
+## image
+考虑到图像为 `RGB` 格式，会对应至多3个矩阵，每个图片存储的数据格式如下
+```javascript
+[
+   "step_id": 12,
+   "type": "RGB",
+   "size": [345, 120],
+   "data": [0.1, 0.2, ...]
+]
+```
+
+## audio
+采样会是出的音频数据会是一个数组，因此类似如下格式
+
+```javascript
+[
+   "step_id": 12,
+   "type": "audio",
+   "size": [234],
+   "data": [...]
+]
+```
+
+## text
+后端直接生成 text便可
+
+```javascript
+[
+  "step_id": 12,
+  "data": "xx" // some text here
+]
+```
+
+## graph 
+graph 会复杂一些，可能无法借用上述类型
+
+```javascript
+[
+  "nodes": [
+    [
+      [
+        "name": "node1",
+        "group": "scope1"
+      ],
+      [
+        "name": "node2",
+        "group": "scope2"
+      ]
+    ]
+  ],
+  // one edge
+  [
+    "from" : 0,
+    "to": 1,
+    "type": "normal"
+  ],
+  [
+    "from" : 0,
+    "to": 1,
+    "type": "data"
+  ]
+]
+```