DeepUX数据源

前言

对DeepUX组件来说，在当前的数据分析场景中，有较多情况是目前已有数据源是无法满足的：

• 当分析的数据需要基于模型中原始数据进行计算的情况下，如计算 A列+B列，该类计算能力从产品框架划分来看，应该是由计算层提供，但短期内可能无法上线以满足需求场景

• 当分析图表希望从多个数据模型中取数据时，如：展示A模型中的销售数据、B模型中的成本数据等，此类为多个数据模型作为数据源的需求

上述场景中，可能仅数据输入部分无法满足需求，如果能将Python的结果作为数据源输入到DeepUX组件中，将极大的减少需要自定义开发的功能数量，提高项目实施效率。

简单示例

一个可以作为DeepUX数据源的脚本，由如下部分组成

• 字段信息，即元数据信息

• 在main函数中返回符合元数据信息的 Pandas DataFrame

定义字段信息

例如需要定义如下数据的元数据信息：

id	description	cost	count	datetime	active	comment
00000000-0000-0000-0000-000000000001	{“zh-cn”: null, “en”: “a”}	1.1	1	2000-01-02 00:00:00	true	demo1
00000000-0000-0000-0000-000000000002	{“zh-cn”: null, “en”: “b”}	2.2	2	2000-02-03 00:00:00	false	demo2
00000000-0000-0000-0000-000000000003	{“zh-cn”: null, “en”: “c”}	3.3	3	2000-03-04 00:00:00	true	demo3

其中，id为UUID类型，description为json类型，datetime为日期类型

则可如下定义元数据结构

from deepfos.lib.deepux import Struct, UUID, Json, Float, Integer, DateTime, Boolean, String


class Data(Struct):
    id_ = UUID(name='id')
    desc = Json('description')
    cost = Float()
    count: Integer
    datetime: DateTime
    active: Boolean
    comment: String

从如上定义方式可以看出，在定义元数据的字段时，支持如下定义形式：

• 定义成员等于字段实例：在实例化时，可选择指定name作为字段名，如不使用kwargs的指定方式，则第一个入参即为字段名，如不指定，则以成员名为字段名

• 定义成员并声明其字段类型：成员名将作为字段名

组织数据

在main函数中返回符合元数据信息的 Pandas DataFrame，此处的 Pandas DataFrame 可以以任何方式组织，只需保证在main函数 return时，为 Pandas DataFrame 数据即可。

将定义的结构class作为as_datasource的 struct 字段，并装饰main函数，即为一个具有了提供元数据信息，并可返回实际数据的数据源了。

示例完整脚本

注意事项

DeepUX的功能目前处于逐步完善阶段，因此SDK中的deepux模块 只提供 返回元数据信息的功能，其余返回数据对入参的处理逻辑需要用户编写逻辑的细节。

使用效果

在DeepUX元素创建后选择python元素作为数据源

可以看到刚刚编辑的脚本的元数据信息呈现在了数据源的信息中：

进一步拖入图表并选取显示字段，可以看到脚本返回的数据显示在了画布中：

元数据

元数据，即DeepUX编辑时所需的字段信息，在选取Python元素作为DeepUX数据源时，需提供。

在deepfos.lib.deepux中，包装了作为图表数据源已支持的字段类型，只需将其进行初始化后作为 Struct 子类的类成员即可。

字段类型

Python类名	字段类型
String	文本
Integer	整数
Boolean	布尔值
Json	多语言文本(json)
Float	小数
DateTime	日期时间
UUID	uuid

备注

在定义元数据的字段时，支持如下定义形式：

• 定义成员等于字段实例：在实例化时，可选择指定name作为字段名，如不使用kwargs的指定方式，则第一个入参即为字段名，如不指定，则以成员名为字段名

• 定义成员并声明其字段类型：成员名将作为字段名

字段描述*(1.1.8新增)

在1.1.8版本后，针对返回的值需要显示可切换的列描述信息的需求，新增了对提供描述信息的支持，用法例如如下：

假设当前应用内，有维度example，其成员如下：

如果想要在DeepUX中显示数据来自该维度，且可切换描述信息，则可编写代码如下：

from deepfos.lib.deepux import to_desc, as_datasource
from deepfos.element import Dimension
import pandas as pd

class Data(Struct):
    text = String('v1')

@as_datasource(struct=Data)
def main(p2):
    dim = Dimension('example')
    res = dim.query('Descendant(#root,0)')
    # 使用deepux新增的方法
    # 将维度query返回值转换为
    # 符合预期格式的描述值
    desc = to_desc(res)
    # 指定v1及其列信息作为返回的第二个值
    return pd.DataFrame(
        {
            'v1': [dim.name for dim in res]
        }
    ), {'v1': desc}

在如上代码中，需注意的是，main 函数的返回值中，第一个值将被当作数据，第二个值，如果存在，则将被当作字段描述

字段描述预期为以字段名为键，值描述键值对为值的字典

图结构数据源*(1.1.31新增)

在1.1.31版本后，新增对图结构数据源的支持，可通过继承 NodeStruct 和 EdgeStruct 的方式提供图结构信息的元组

图结构的数据组成

• edges: 关系数据，固定必须提供的字段为 source (关系的来源) 和 target (关系的目标) ，其余自定义字段，可在UX中的“代码表达式”区域被引用

• nodes: 节点数据，固定必须提供的字段为 _id (节点主键)和 label (节点描述)，其余自定义字段，可在UX中的“代码表达式”区域被引用

例如需要声明节点数据包含了String类型的自定义字段field1的图结构，并返回数据，代码示例如下：

from deepfos.lib.deepux import NodeStruct, EdgeStruct, as_datasource, String
import pandas as pd
import uuid

# 声明节点内自定义字段
class NodeData(NodeStruct):
    # _id和label字段已在NodeStruct中定义, 无需声明
    field1: String

# EdgeStruct中已包含了source和target, 可以直接使用
@as_datasource(struct=(NodeData, EdgeStruct))
def main(p1, p2):
    nodes_df = pd.DataFrame(
        {
            '_id': ['0', '1'],
            'label': ['Node1', 'Node2'],
            'field1': ['xxx', 'yyy']
        }
    )
    edges_df = pd.DataFrame({'source': ['0'], 'target': ['1']})
    return nodes_df, edges_df

在UX中增加代码对应的Python元素作为数据源后，可见字段信息被识别：

在画布中拖入“图与树结构”控件，并选择刚刚导入的Python数据源，确认后展示如下：

而 field1 字段可在js表达式代码编辑过程中被使用：

保存后显示的描述中追加了 field1 的内容：