ros 0.119

请访问主页查看格式更优的版本。

概述

Ros执行查询图以协作构建知识网络。

虽然该语言提供了支持变量、模块化、可扩展性、模板和类型系统的常用构造，但它旨在解决创建 高度详细的知识图以实现推理和推断 的独特挑战。

用法

从命令行运行工作流程产生如下输出

并构建此知识图

• 概述
  • 用法
• 语言参考
  • 概述
  • 变量
  • 运算符
  • 图
  • 元数据
  • 模板
  • 模块
• 将所有内容整合在一起
  • 1. 定义一个模板
  • 2. 可选地建模输入和输出类型
  • 3. 构建工作流程
• 执行
• 入门
  • Docker
    • 要求
    • 开始
  • 用法 - 命令行
  • 用法 - 编程
  • 安装
  • NDEx
  • 帮助

语言参考

概述

工作流程是一系列步骤。步骤可以引用先前步骤的输出。通常，它们可以访问共享的图。它们还可以交换子图。步骤可以有相关元数据，描述其允许的输入和输出类型。

工作流程计算一个有向无环图（DAG），表示作业依赖关系，然后按DAG拓扑排序的顺序执行。

变量

传递给工作流程的变量（通过命令行或通过API）可以在运行时动态解析。在此示例中，$disease_name 引用执行上下文提供给此工作流程的参数。提供的值将在运行时替换。

以下示例中，disease_identifiers 是作业的名称。它生成一个图形。表示该图形的 JSON 对象将被存储为作业名称的值。该图形还将写入共享图形数据库。后续作业可以与任一表示进行交互。

code 标签告诉引擎执行哪个功能块。

args 部分列出此操作符的输入。

  disease_identifiers:
    doc: |
      Resolve an English disease name to an ontology identifier.
    code: bionames
    args:
      type: disease
      input: $disease_name

运算符

工作流程围绕图形操作符组织。每个操作符都可以访问 Ros 框架的所有功能，包括共享图形。

通常，工作流程作业有以下字段

• doc：文档字符串。
• code：提供功能的功能组件的名称。
• args：操作符的参数。

Ros 目前提供以下核心操作符

• get：在指定的资源上调用 HTTP GET 操作。
• union：将两个或多个结果合并为一个对象。

它还包括某些特定的翻译器模块。将来，这些将作为 Ros 插件实现

• biothings：BioThings 模块。目前是工作流程 1 的第 4 和第 5 个模块。
• gamma：调用 Gamma 推理器。以下示例使用不同的机器问题调用 Gamma 几次。它将被更新为使用新的快速 API 以增加灵活性。
• xray：XRay 推理器模块。目前是工作流程 1 的第 1 和第 2 个模块。

图

Ros 以两种基本模式提供图形

• 结果：可以引用先前工作流程步骤的结果作为传递给后续步骤的变量。可以使用 JSON Path 查询语法查询此图形。以下示例使用 Ros 框架的 json select 功能查询名为 condition 的变量

  diseases = event.select (
           query = "$.[*].result_list.[*].[*].result_graph.node_list.[*]",
           obj = event.conditions)
  

• 共享：一个共享图形，可通过 Cypher 查询语言访问，对所有操作符都可用。以下示例使用 Ros 框架对共享图形的生物链接模型概念进行 cypher 查询。

  diseases = event.context.graph.query ("match (a:disease) return  a")
  

每个操作符都收到由 Ros 框架提供的对象事件。事件提供框架服务，包括共享图形、图形操作工具以及操作符调用的参数。

这些功能使操作符能够在执行主要逻辑之前查询图形，并对其进行更新。

元数据

该语言支持元数据功能，使模块能够指定其输入和输出。

输入支持以下标签

• doc：文档。
• type：类型目前来自标准库，但将来将是可扩展和可组合的。
• required：参数是否必需。

输出支持以下标签

• doc：文档。
• type：返回对象的类型。

元数据的使用是可选的。

模板

模板允许通过组合现有库函数来扩展语言，以实现新的功能。模板在单独的模板部分中定义，也可以在单独的可重用模块中定义。

模块

可以通过 import 标签加载外部模块。

类似于其他高级编程语言的库路径控制库的加载位置。

自动验证

当工作流程运行完毕后，我们希望运行验证来测试我们所得到的答案的完整性。在第一个Ros版本中，我们支持有限的自动化验证形式。这些限制是为了使Ros更加安全。由于我们远程执行查询，从互联网上的客户端发布任意图查询并不现实。相反，我们提供了一个有限的查询语法，这仍然允许我们进行大量验证。该查询语法被称为Syfur——一个与Cypher类似的查询系统，但功能较弱。

以下是从 workflow_one 中的示例展示了Syfur的用法。

automated_validation:
  doc: |
    Automated Validation
       We can test the knowledge network with constraints including all, match, and none.
       The depends arg ensures the validation runs only after the graph is built.
       Each test has a name, documentation, a query, and an operator defining the constraint to enforce
    Syfur
       A principal virtue of Ros is the ability to remotely execute workflows.
       To make this possible, it must be secured against remote code execution attacks
       This includes cypher injection.
       It may be possible to accomplish some of this in other ways, but for now, we provide Syfur
       Syfur is a restricted DSL that translates to a subset of Cypher. See examples below.
  code: validate
  args:
    depends: $biothings_module_4_and_5
    tests:
      test_type_2_diabetes_exists:
        doc: Ensure type 2 diabetes mellitus and other conditions are present.
        items: "match type=disease return id"
        all: [ "OMIM:600001", "MONDO:0005148", "DOID:9352" ]
      test_pioglitazone:
        doc: Test attributes of a specific chemical. Ensure type 2 diabetes mellitus is present.
        items: "match type=chemical_substance id=CHEMBL.COMPOUND:CHEMBL595 return node_attributes"
        match:
          - .*Thiazolidinedione.*
          - ".*{'name': 'EPC', 'value': 'Peroxisome Proliferator Receptor gamma Agonist'}.*"
      test_absence_of_something:
        doc: Verify there is none of something in our graph.
        items: "match return id"
        none: [ 'BAD:123' ]

将所有内容整合在一起

下面是一个示例，以将所有这些内容置于上下文中。

1. 定义一个模板

我们从一个常见的用例开始，即将用户提供的文本转换为本体标识符。为此，我们创建了一个模板任务。

• 它扩展了内置的 get HTTP操作符，并将 pattern 参数设置为定义的值。
• 它保存在名为 bionames.ros 的文件中，该文件位于库路径上的目录中。

bionames 模板现在是一个可重用的组件，可以导入到各种工作流程中。

2. 可选地建模输入和输出类型

尽管目前是可选的，但模板还指定了

• meta 标签描述了操作符的元数据。
• 当未指定子操作符时，使用 main 操作符。
• 每个操作符都有输入和输出部分。
• 输入 部分指定了一系列输入值。
• 每个值可能包含 doc、type 和 required 标签。
• 输出 部分可能包含 doc 和 type 标签。
• 在两种情况下，type 的值（目前）必须来自 Ros 标准库，在别处有描述。

doc: |
  This module defines a reusable template.
  It can be imported into other workflows via the import directive.

templates:

  bionames:
    doc: |
      This template extends the built in get operator.
    code: get
    args:
      pattern: 'https://bionames.renci.org/lookup/{input}/{type}/'
    meta:
      main:
        args:
          input:
            doc: The name of the object to find identifiers for.
            type: string
            required: true
          type:
            doc: The intended biolink_model type of the resulting identifiers.
            type: biolink_model
            required: true
        output:
          doc: A Translator standard knowledge graph.
          type: knowledge_graph_standard

biolink_model 和 knowledge_graph_standard 类型目前在 Ros 标准库 中直接建模。

types:
  string :
    doc: A primitive string of characters.
    extends: primitive
  biolink_model:
    doc: An element from the Biolink-model 
    extends: string
  knowledge_graph_standard:
    doc: A Translator knowledge graph standard (KGS) knowledge graph.
    extends: primitive

3. 构建工作流程

接下来，我们将上面的模板导入到工作流程定义中。

doc: |
  NCATS Biomedical Translator - Workflow One
  
import:
  - bionames
  
workflow:

  disease_identifiers:
    doc: |
      Resolve an English disease name to an ontology identifier.
    code: bionames
    args:
      type: disease
      input: $disease_name
...

disease_identifiers 任务实例化了 bionames 模板。它提供了必要的参数，包括解决此工作流程特有的 disease_name 输入参数。

一旦此模块执行完毕，后续步骤就可以通过变量 $disease_identifiers 引用它所产生的图。

工作流程中的下一步将利用这一点，通过引用模板调用的输出。工作流程引擎看到这个引用，并使新作业依赖于引用的作业。这就是计算作业执行顺序的作业DAG（有向无环图）的方法。

  condition_to_drug:
    doc: |
      Module 1
        * What are the defining symptoms / phenotypes of [condition x]?
        * What conditions present [symptoms]?
        * Filter [conditions] to only keep ones with defined genetic causes.
        * What subset of conditions are most representative of [conditions]? (find archetypes)
      Module 2
        * What genes are implicated in [condition]?
        * What subset of genes are most representative of [conditions]?  (find archetypes)
        * What pathways/processes are [genes] involved in?
        * What genes are involved in [pathway/process]?
        * What drugs/compounds target gene products of [gene]?
      Invoke XRay module 1 and 2 given the disease identifier from bionames.
      The graph argument references the entire bionames response.
      The op argument specifies the XRay operation to execute.
    code: xray
    args:
      op: condition_expansion_to_gene_pathway_drug
      graph: $disease_identifiers

有关更多详细信息，请参阅整个 工作流程。

执行

对于所有工作流程，引擎通过检查每个作业以确定其依赖关系，构建作业的有向无环图（DAG）。

作业的拓扑排序提供了执行顺序。

执行是异步的。在您订阅的 “并发”和“并行””语义区分工作流程执行时，是并发的但不是并行的。

当前实现使用 Python 的 asyncio。这意味着多个操作能够在相同的时间窗口内取得进展。但这并不意味着操作真正地同时执行（运行CPU操作）。当前的操作配置是I/O受限而不是CPU受限，因此这种方法可能足够一段时间。几个任务可以在等待HTTP请求返回的同时，其他任务则使用处理器处理结果。

API 还使用 Sanic 和 Tornado 异步处理请求。

入门

Docker

要求

• Docker
• Docker Compose（包含在Mac上的Docker中）
• Git
• 端口7474、7687和5002可用

开始

git clone git@github.com:NCATS-Tangerine/ros.git
cd ros/deploy
source ros.env
docker-compose up

用法 - 命令行

• 连接到本地的Neo4J 浏览器
• 连接到API docker容器
• 通过API运行工作流程。

$ cd ../ros
$ PYTHONPATH=$PWD/.. python app.py --api --workflow workflows/workflow_one.ros -l workflows -i disease_name="type 2 diabetes mellitus" --out stdout

用法 - 编程

Ros 可以远程执行工作流并返回结果知识网络。客户端目前支持 JSON 和 NetowrkX 表示形式。

from ros.client import Client

ros = Client (url="http://localhost:5002")
response = ros.run (workflow='workflows/workflow_one.ros',
                    args = { "disease_name" : "type 2 diabetes mellitus" },
                    library_path = [ 'workflows' ])

graph = response.to_nx ()    
for n in graph.nodes (data=True):
    print (n)

安装

要求

• Python >3.7.x
• Neo4J >3.3.4

步骤

这些步骤安装软件包，打印帮助文本并执行工作流一。要运行此操作，您需要从存储库中获取 workflow_one.ros 和 bionames.ros。使用 -l workflows 标志命名包含工作流的目录。

$ pip install ros
$ ros --help
$ ros --workflow workflow_one.ros --arg disease_name="diabetes mellitus type 2" -l workflows

NDEx

将工作流保存到 NDEx。

• 创建一个 NDEx 账户。

• 创建一个类似的 ~/.ndex 凭据文件

  {
    "username" : "<username>",
    "password" : "<password>"
  }
  

• 运行具有 NDEx 输出的工作流

  ros flow --workflow workflow_one.ros --out output.json --ndex wf1
  

帮助

$ PYTHONPATH=$PWD/.. python app.py --help
usage: app.py [-h] [-a] [-w WORKFLOW] [-s SERVER] [-i ARG] [-o OUT]
              [-l LIBPATH] [-n NDEX] [--validate]

Ros Workflow CLI

optional arguments:
  -h, --help                        show this help message and exit
  -a, --api                         URL of the remote Ros server to use.
                                    (default: False)
  -w WORKFLOW, --workflow WORKFLOW  Workflow to execute. (default:
                                    workflow_one.ros)
  -s SERVER, --server SERVER        Hostname of api server (default:
                                    http://localhost:5002)
  -i ARG, --arg ARG                 Add an argument expressed as key=val
                                    (default: [])
  -o OUT, --out OUT                 Output the workflow result graph to a
                                    file. Use 'stdout' to print to terminal.
                                    (default: None)
  -l LIBPATH, --libpath LIBPATH     A directory containing workflow modules.
                                    (default: ['.'])
  -n NDEX, --ndex NDEX              Name of the graph to publish to NDEx.
                                    Requires valid ~/.ndex credential file.
                                    (default: None)
  --validate                        Validate inputs and outputs (default:
                                    False)

下一步

• 信息架构：开发
  • 受控词汇：特别是关于模块及其关系
  • 输入和输出签名：对于模块
  • 来源：在流程来源（哪个用户、多长时间等）和来源的元数据（SCEPIO？）方面
• 多态性：如果多个实体实现同一功能可以实现相同的 OpenAPI 接口，这将非常有帮助，以实现多态调用。这也有助于并行化。
• KGX：也许 KGX 应该是共享图，至少是可选的。只需要设计这个连接。
• 并发/并行/分布式：Ros 现在支持通过 Python async 的并发任务执行。如果这还不够，可以探索通过能够并行和可能分布执行的东西来运行。
• 可组合性：允许工作流导入和重用其他工作流。