Spotfire® 用户指南

注册数据函数

可以使用数据函数将用 R 或其他语言编写的计算添加到分析中,从而增强 Spotfire 的功能。数据函数使用统计引擎来执行,例如 Spotfire® Enterprise Runtime for R(又名 TERR™)引擎、开源 R 引擎或 Python 解释器。注册了函数并将其保存到库中后,便可在任何分析中使用该函数,而且脚本作者以外的其他用户也可以使用该函数。

关于此任务

有关数据函数的介绍,另请参见什么是数据函数?编写数据函数
此示例显示了如何注册 TERR 数据函数,但您可以通过相同过程注册使用其他计算引擎的数据函数。
提示: 可以使用数据画布中的“编辑脚本”对话框(从 fx 节点访问)或者使用数据函数属性(使用已安装的客户端时)编辑之前添加的数据函数脚本。

开始之前

数据函数必须使用已安装的客户端进行编写。

过程

  1. 在已安装的 Spotfire 客户端中的菜单栏上,选择“工具” > “注册数据函数”
  2. “名称”字段中,键入函数的名称。
    如果要使用包,请记住,除非函数名称与包中使用的名称完全相同,否则 Spotfire 无法找到函数。有关包的更多信息,请参见相关服务的文档。
  3. “类型”下拉列表中,选择要使用的脚本类型,例如“R 脚本 - Spotfire Enterprise Runtime for R”。

    您可以访问的选项取决于您的管理员在 Spotfire 环境中提供的内容,或者您在本地安装的工具。

    对于预定义的 R 函数,请选择开源 R 函数。如果 Spotfire 中您要使用的函数已定义并已保存,则必须记下或记住其名称,以及所有所需输入和输出参数的名称。

    要定义新脚本,请选择 R 脚本 - 开源 R、R 脚本 - Spotfire Enterprise Runtime for R 或 Python 脚本。(您的公司可能还有其他可用选项。)

  4. 可选: 如果要包含统计包中的预定义函数,请在“包”字段中键入该函数所在的包的确切名称。
    “包”字段使您可以使用下载的包基于预定义的统计 R 函数或 TERR 函数创建数据函数。在此处,可以指定供当前数据函数使用的任何包,用分号分隔。有关包的更多信息,请参见相关服务的文档。

    例如,如果要基于预定义的统计 R 函数创建数据函数,请提供该包的名称并从 CRAN 下载该包(可选)。键入函数所在的包的确切名称。(仅当存储库中存在具有相同名称的多个函数,或包未自动加载时,才有必要进行上述操作。)

    对于本地 Python 脚本,该字段可让您列出可以预加载的 Python 包,以减少执行数据函数所需的时间。如果启用了使用热备用,则此字段地已安装的客户端中使用。它不会影响在 Web 客户端中运行的远程服务或数据函数。如果您不确定,请将该字段留空。必须在脚本中导入包并在此处指定它。

    如果需要多个包,则需要使用分号将包名称分隔开。

  5. 注册基于统计包中的预定义函数的数据函数时,请在“函数名称”字段中键入感兴趣的函数的确切名称(如果其已在包中定义)。
    此步骤不适用于基于脚本的数据函数。
  6. 提供函数的“说明”,以便其他用户更容易找到和使用该函数。
  7. 如果数据函数应基于脚本,请键入、粘贴脚本或将脚本导入到“脚本”选项卡。
  8. “输入参数”选项卡上,添加所有必需的输入参数。
    输入参数的处理方式是根据数据函数的执行来定义的。
  9. 如有必要,可移动输入参数,以便列表中的顺序反映输入参数的检索顺序。
  10. “输出参数”选项卡上,添加所有必需的输出参数。
    输出参数的处理方式是根据数据函数的执行来定义的。
  11. 可选: 选择一个“图标”来描述您的数据函数的作用。
    通过选择合适的类别,您可以让最终用户更轻松地在库中找到合适的数据函数。图标将出现在显示数据函数的不同界面中(例如,在“文件和数据”浮出控件、“f(x)”浮出控件和“数据画布”中)。您可以从许多预定义的类别图标中进行选择,或使用自定义可缩放矢量图形 (SVG) 图标。有关创建在 Spotfire 环境中使用的自定义图标的更多信息,请参阅 GitHub 上的为您的图表 mod 创建图标
  12. 将数据函数保存到库中。
    您可以在保存时指定关键字,以便于以后在库中定位函数。如果您选择了与默认图标不同的图标,则会自动将图标类别添加为关键字。
  13. 单击“关闭”

结果

现在可以通过从“文件和数据”“f(x)”浮出控件或者从“数据函数属性” > “插入”(仅限已安装的客户端)运行数据函数来将其添加到分析中,或使用已安装的客户端将其添加为转换(有关更多信息,请参见从库中运行数据函数转换数据)。

“注册数据函数”对话框

“注册数据函数”对话框中,不仅可以注册全新的数据函数,还可以“打开”之前保存在库中的数据函数以便进行进一步的配置,“导入”您之前已导出到磁盘的脚本函数定义 (*.sfd),或使用其他脚本编辑工具创建的 Python 脚本文件 (*.py) 或 R 脚本文件 (*.r),而且可以将脚本函数定义“导出”到磁盘,这样便可以进行共享或在其他脚本编辑环境中进一步编辑。
注: 无法使用“注册数据函数”对话框创建任何 Statistica 数据函数。有关如何使用这些类型的数据函数的详细信息,请参见 Spotfire 与 Statistica 集成


如果单击“运行”,则可以指定输入和输出参数的设置,并执行当前数据函数。这主要是用作在将数据函数保存到库之前测试数据函数的快捷方式,并且在完成测试时应从分析中删除在测试时添加的嵌入式实例,以避免在分析中保存不必要的实例。

保存分析前,改为使用“f(x) - 分析工具”“文件和数据”或者使用“数据函数属性”(仅限已安装的客户端)中的“插入”来运行已保存的数据函数,以使数据函数能与日后库中出现的任何更新保持同步。

“允许缓存”指定在之前曾计算过输入值的相同子集时重复使用计算。如果某些输入数据来自当前分析之外的其他位置,并且您希望每次输入数据发生更改时(即使是对之前已计算的内容进行更改)都执行新计算,则清除此复选框。当输入取决于筛选值、已标记值或属性值时,输入数据可能会发生更改。

例如,如果数据函数包括随机数生成程序,您可能不希望缓存之前生成的随机数。相反,您可能希望在数据函数每次刷新时计算新的随机数。另一个关于何时清除复选框的示例是当数据函数包含当前日期或时间时。

“脚本”选项卡上,可以键入或粘贴使用指定脚本类型语言编写的脚本。也可以编辑导入的脚本。可以使用“工具” > “选项” > “字体”并选择“表达式和脚本编辑器”来更改“脚本”选项卡的字体设置。脚本编辑器可突出显示语法以及对语法自动着色,从而让脚本更易于编写和阅读。

“输入参数”选项卡上列出并定义脚本中使用的所有输入参数。此列表中输入参数的顺序决定了输入参数的检索顺序。

  • “输入参数名称”“名称”是在函数或脚本中引用的参数的名称。
  • “显示名称”是希望参数显示给最终用户时使用的参数名称。
  • “类型”决定输入类型,可以是“值”“列”“表”(数据表)。该类型定义了输入参数是一个或多个列,还是仅为单一值。
  • “允许的数据类型”指定此输入参数支持的数据类型。可以选择在定义输入参数时想要支持的所有数据类型。必须为每个输入参数选择至少一个数据类型。
  • “说明”可以选择性地包含有输入参数的详细信息,以帮助最终用户了解要提供的内容。
  • “所需参数”指定调用函数时所必需的参数。如果某参数不是必需的,则函数应在不使用该参数时仍可发挥作用。
“输出参数”选项卡上列出并定义脚本中使用的所有输出参数。

  • “结果参数名称”“名称”是在函数或脚本中引用的参数的名称。
  • “显示名称”是希望参数显示给最终用户时使用的参数名称。
  • “类型”决定输出类型,可以是“值”“列”“表”(数据表)。此项定义输出参数是一个或多个列,还是只是一个。
  • “说明”可以选择性地包含有输出参数的详细信息,以帮助最终用户了解将获得的内容。
提示: 如果要添加简单计算,可以按照创建表达式函数中所述,使用统计函数下提供的 TERR_* 函数直接采用表达式语言来添加 TERR 脚本。然后可以在计算的列和自定义函数中将这些脚本用作采用表达式语言的任何其他函数。但是,请注意,表达式函数不能在不同的分析之间共享。