grounding-search

![DOI]([] ![status]([] ![License]([***]

概述

亚细胞生物实体的识别是生物信息学分析工具和可访问生物研究应用程序使用与创建中的重要考虑因素。当研究信息被唯一且明确地识别时，能够实现数据的准确检索、交叉引用和集成。在实践中，生物实体通过与专门收集和组织该类型信息的知识库（如基因序列数据库）中的匹配记录相关联而被“识别”。本搜索服务提高了生物实体识别的效率和易用性，可用于支持研究应用和工具，这些应用和工具可接受常见的实体同义词作为输入。

例如，Biofactoid 使用此接地服务允许用户简单地指定其偏好的同义词来识别生物实体（如蛋白质）：

[***]

引用

若在论文中引用Pathway Commons接地搜索服务，请引用《Journal of Open Source Software》论文：

Franz et al., (2021). A flexible search system for high-accuracy identification of biological entities and molecules. Journal of Open Source Software, 6(67), 3756, [***]

在JOSS查看论文 或 直接查看PDF。

维护

Pathway Commons接地搜索服务是一个学术项目，由以下机构构建和维护： 多伦多大学Bader实验室、 哈佛Sander实验室 以及 俄勒冈健康与科学大学通路与组学实验室。

资金支持

本项目由美国国立卫生研究院（NIH）资助 [U41 HG006623, U41 HG003751, R01 HG009979 和 P41 GM103504]。

快速开始

通过Docker

安装 Docker (>=20.10.0) 和 Docker Compose (>=1.29.0)。

克隆此仓库或至少获取 docker-compose.yml 文件，然后运行：

docker-compose up

Swagger文档可通过 http://localhost:3000 访问。

注意：服务器启动需要一定时间，以便Elasticsearch初始化、接地数据检索和索引恢复。如果超过10分钟未启动，考虑增加Docker的分配内存：偏好设置 > 资源 > 内存，并删除docker-compose.yml中的此行：ES_JAVA_OPTS=-Xms2g -Xmx2g

通过源码

安装 Node.js (>=8) 和 Elasticsearch (>=6.6.0, <7) 并使用默认选项，在克隆的仓库副本中运行以下命令：

• npm install: 安装npm依赖
• npm run update: 下载并索引数据
• npm start: 启动服务器（默认端口3000）

文档

Swagger文档可在公共托管的服务实例上访问：[***]

请勿将 [***] 用于生产应用或脚本。

示例用法

以下提供主要搜索API在常见语言中的使用示例。有关更多详细信息，请参阅Swagger文档 [***]

JS中的搜索示例

const response = await fetch('[***] {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ // 搜索选项
    q: 'p53'
  })
});

const responseJSON = await response.json();

Python中的搜索示例

import requests

url = '[***]
body = {'q': 'p53'}

response = requests.post(url, data = body)

responseJSON = response.json()

通过curl的shell脚本示例

curl -X POST "[***]" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{  \"q\": \"p53\" }"

工具比较

以下总结了与Pathway Commons接地搜索服务主要用例有一定重叠的工具集。此表最后更新于2021年10月25日（2021-10-25）。

如果您在此领域开发了新工具或您的工具支持新功能，请通过拉取请求告知我们，我们将把您的修订添加到此表中。

接地数据

grounding-search 使用多个公共数据库提供的数据文件：

• NCBI Gene
  • 基因相关信息
  • 别名：ncbi
  • 数据文件：gene_info.gz
• ChEBI (chebi)
  • 生物相关小分子信息
  • 别名：chebi
  • 数据文件：chebi.owl
• UniProt (uniprot)
  • 蛋白质相关信息
  • 别名：uniprot
  • 数据文件：uniprot_sprot.xml.gz
• Famplex
  • 蛋白质家族相关信息
  • 别名：fplx
  • 数据文件：famplex-master.zip

从源数据库文件构建索引

如果您已按照快速开始中的“从源码运行”步骤操作，可以通过运行以下命令下载并索引 ncbi、chebi 和 uniprot 源数据库提供的数据：

npm run update

从Elasticsearch dump文件恢复索引

从源下载并构建索引可确保索引最新信息。或者，为快速检索和重建索引，已在 Zenodo 上发布了先前索引的Elasticsearch实例的dump文件，DOI：

![Zenodo]([***]

此数据根据 知识共享零版1.0通用许可 发布。

要恢复索引，启动Elasticsearch实例并运行：

npm run restore

要同时恢复索引并启动grounding-search服务器，运行：

npm run boot

注意：Zenodo上发布的索引dump仅用于演示目的。我们不保证此数据为最新或grounding-search软件版本与任何先前发布的dump数据兼容。要确保使用与grounding-search兼容的最新数据，请按照“从源数据库文件构建索引数据库”中的说明操作。

问题与反馈

如需报告软件问题或提供反馈，请 在GitHub上提交issue。

贡献

要为此项目做出贡献，请先 在GitHub上提交描述您提案的issue。提案准备就绪后，您可以创建 拉取请求。

配置

可使用以下环境变量配置服务器：

• NODE_ENV：环境模式，production（生产）或 development（开发，默认）
• LOG_LEVEL：日志文件级别（info、warn、error）
• PORT：服务器运行端口（默认3000）
• ELASTICSEARCH_HOST：指向Elasticsearch的 host:port
• MAX_SEARCH_ES：从Elasticsearch返回的最大结果数
• MAX_SEARCH_WS：Web服务返回的JSON最大结果数
• CHUNK_SIZE：批量插入Elasticsearch的接地条目块大小
• MAX_SIMULT_CHUNKS：同时插入Elasticsearch的最大块数
• INPUT_PATH：数据文件所在的输入文件夹路径
• INDEX：存储所有数据源数据的Elasticsearch索引名称
• UNIPROT_FILE_NAME：读取UniProt数据的文件名
• UNIPROT_URL：下载UniProt文件的URL
• CHEBI_FILE_NAME：读取ChEBI数据的文件名
• CHEBI_URL：下载ChEBI文件的URL
• NCBI_FILE_NAME：读取NCBI数据的文件名
• NCBI_URL：下载NCBI文件的URL
• NCBI_EUTILS_BASE_URL：NCBI EUTILS的URL
• NCBI_EUTILS_API_KEY：NCBI EUTILS的API密钥
• FAMPLEX_URL：下载FamPlex远程文件的URL
• FAMPLEX_FILE_NAME：读取FamPlex数据的文件名
• FAMPLEX_TYPE_FILTER：要包含的实体类型（protein、complex、all [默认]）
• ESDUMP_LOCATION：elasticdump文件的位置（URL、文件路径，注意以'/'结尾）
• ZENODO_API_URL：Zenodo的基础URL
• ZENODO_ACCESS_TOKEN：Zenodo REST API的访问令牌（范围：deposit:actions、deposit:write）
• ZENODO_BUCKET_ID：Zenodo deposition“bucket”的ID（Files API）
• ZENODO_DEPOSITION_ID：Zenodo deposition的ID（用于已发布数据集）

运行目标

• npm start：启动服务器
• npm stop：停止服务器
• npm run watch：监视模式（启用调试模式，自动重载）
• npm run refresh：运行清除、更新，然后启动
• npm test：运行只读方法的测试（如搜索和获取），假设数据已存在
• npm test:sample：使用示例数据运行测试
• npm run test:quality：运行搜索质量测试（需要完整数据库）
• npm run test:quality:csv：运行搜索质量测试并输出CSV文件
• npm run lint：检查项目代码规范
• npm run benchmark：运行所有基准测试
• npm run benchmark:source：运行 source（如 ncbi、chebi）的基准测试
• npm run clear：清除所有数据
• npm run clear:source：清除 source（如 ncbi、chebi）的数据
• npm run update：更新所有数据（下载然后索引）
• npm run update:source：更新Elasticsearch中 source（如 ncbi、chebi）的数据
• npm run download：下载所有数据
• npm run download:source：下载 source（如 ncbi、chebi）的数据
• npm run index：索引所有数据
• npm run index:source：索引Elasticsearch中 source（如 ncbi、chebi）的数据
• npm run test:inputgen：为每个 source（如 uniprot 等）生成输入测试文件
• npm run test:inputgen：为 source（如 uniprot 等）生成输入测试文件
• npm run dump：将 INDEX 的信息转储到 ESDUMP_LOCATION
• npm run restore：从 ESDUMP_LOCATION 恢复 INDEX 的信息
• npm run boot：运行 clear、restore 然后 start；出错时退出

使用Zenodo存储索引dump文件

Zenodo 允许存储和检索与科学项目或出版物相关的数字制品。此处，我们使用Zenodo存储Elasticsearch索引dump数据，用于快速重建grounding-search使用的索引。

创建和发布新记录沉积

简要来说，使用其 RESTful Web服务API，您可以创建一个“Deposition”记录，该记录具有一个由 ZENODO_BUCKET_ID 引用的“bucket”，您可以向其中上传和下载“文件”（即 <ZENODO_API_URL>api/files/<ZENODO_BUCKET_ID>/<filename>；通过 [***]<deposition id>/files 列出文件）。特别是，重建索引需要三个文件，对应Elasticsearch类型：data、mapping 和 analyzer。

设置步骤如下：

1. 通过创建“个人访问令牌”获取 ZENODO_ACCESS_TOKEN（详见文档）。确保添加 deposit:actions 和 deposit:write 范围。

2. 通过向 [***] 发送POST请求创建记录“Deposition”，至少包含以下信息，注意设置请求头 Authorization = Bearer <ZENODO_ACCESS_TOKEN>：

{
	"metadata": {
		"title": "Elasticsearch data for biofactoid.org grounding-search service",
		"upload_type": "dataset",
		"description": "This deposition contains files with data describing an Elasticsearch index ([***] The files were generated from the elasticdump npm package ([***] The data are the neccessary and sufficient information to populate an Elasticsearch index.",
		"creators": [
			{
				"name": "Biofactoid",
				"affiliation": "biofactoid.org"
			}
		],
		"access_right": "open",
		"license": "cc-zero"
	}
}

3. POST响应应在 links 对象中包含“bucket”（例如 "bucket": "[***]<uuid>"）。变量 ZENODO_BUCKET_ID 是示例URL中的 <uuid> 值。

4. 发布。您需要转储索引并上传到