refscan

refscan是一个命令行工具，人们可以使用它来扫描NMDC MongoDB数据库中的引用完整性违规。

%% This is the source code of a Mermaid diagram, which GitHub will render as a diagram.
%% Note: PyPI does not render Mermaid diagrams, and instead displays their source code.
%%       Reference: https://github.com/pypi/warehouse/issues/13083
graph LR
    schema[LinkML<br>schema]
    database[(MongoDB<br>database)]
    script[["refscan.py"]]
    violations["List of<br>violations"]
    references["List of<br>references"]:::dashed_border
    schema --> script
    database --> script
    script -.-> references
    script --> violations
    
    classDef dashed_border stroke-dasharray: 5 5

目录

• refscan
  • 目录
  • 工作原理
  • 局限性
  • 使用方法
    • 安装
    • 运行
      • MongoDB连接字符串(--mongo-uri)
      • 模式(--schema)
      • 输出
    • 更新
    • 卸载
  • 开发
    • 克隆仓库
    • 创建虚拟环境
    • 安装依赖
    • 进行更改
    • 运行测试
    • 格式化代码
      • 检查格式
  • 构建和发布
    • 为生产构建
    • 在本地测试构建过程
  • 附录
    • refgraph

工作原理

refscan分两个阶段执行其任务

1. 它使用LinkML模式来确定符合该模式的MongoDB数据库中引用可以存在的位置。

   示例：模式可能规定，如果集合中的文档有一个名为associated_studies的字段，则该字段必须包含study_set集合中文档的id列表。

2. 它扫描MongoDB数据库以检查所有实际存在的引用的完整性。

   示例：对于biosample_set集合中每个有名为associated_studies字段的文档，对于该字段中的每个值，确认在study_set集合中存在具有该id的文档。

局限性

refscan是在以下假设下设计的：每个集合中每个由模式描述的document都有一个名为type的字段，其值为文档表示的实例的模式的class_uri。 refscan使用该class_uri值（在该type字段中）来确定该模式类的名称，然后使用该名称来确定该文档中可以包含引用的哪些字段。

使用方法

安装

假设您已安装pipx，您可以通过运行以下命令安装该工具

pipx install refscan

pipx是一个工具，人们可以使用它从PyPI托管的Python脚本中下载和安装脚本。您可以通过运行$ python -m pip install pipx来安装pipx。

运行

您可以通过运行来显示工具的--help片段

refscan --help

在撰写本文时，工具的--help片段是

 Usage: refscan [OPTIONS]

 Scans the NMDC MongoDB database for referential integrity violations.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ *  --schema                               FILE  Filesystem path at which the YAML file │
│                                                 representing the schema is located.    │
│                                                 [default: None]                        │
│                                                 [required]                             │
│    --database-name                        TEXT  Name of the database.                  │
│                                                 [default: nmdc]                        │
│    --mongo-uri                            TEXT  Connection string for accessing the    │
│                                                 MongoDB server. If you have Docker     │
│                                                 installed, you can spin up a temporary │
│                                                 MongoDB server at the default URI by   │
│                                                 running: $ docker run --rm --detach -p │
│                                                 27017:27017 mongo                      │
│                                                 [env var: MONGO_URI]                   │
│                                                 [default: mongodb://localhost:27017]   │
│    --verbose                                    Show verbose output.                   │
│    --skip-source-collection,--skip        TEXT  Name of collection you do not want to  │
│                                                 search for referring documents. Option │
│                                                 can be used multiple times.            │
│                                                 [default: None]                        │
│    --reference-report                     FILE  Filesystem path at which you want the  │
│                                                 program to generate its reference      │
│                                                 report.                                │
│                                                 [default: references.tsv]              │
│    --violation-report                     FILE  Filesystem path at which you want the  │
│                                                 program to generate its violation      │
│                                                 report.                                │
│                                                 [default: violations.tsv]              │
│    --version                                    Show version number and exit.          │
│    --no-scan                                    Generate a reference report, but do    │
│                                                 not scan the database for violations.  │
│    --locate-misplaced-documents                 For each referenced document not found │
│                                                 in any of the collections the schema   │
│                                                 allows, also search for it in all      │
│                                                 other collections.                     │
│    --help                                       Show this message and exit.            │
╰────────────────────────────────────────────────────────────────────────────────────────╯

注意：上面的片段是从宽度为90个字符的终端窗口中捕获的。

MongoDB连接字符串(--mongo-uri)

如上面--help片段中所述，您可以通过以下方式之一向工具提供MongoDB连接字符串：(a) 使用--mongo-uri选项；或(b) 使用名为MONGO_URI的环境变量。后者在MongoDB连接字符串包含您不希望出现在shell历史记录中的信息（如密码）时非常有用。

以下是创建该环境变量的方法

export MONGO_URI='mongodb://username:password@localhost:27017'

模式(--schema)

如上面--help片段中所述，您可以通过--schema选项将YAML格式的LinkML模式文件路径提供给工具。

# Download the raw content of https://github.com/{user_or_org}/{repo}/blob/{branch}/path/to/schema.yaml
curl -o schema.yaml https://raw.githubusercontent.com/{user_or_org}/{repo}/{branch}/path/to/schema.yaml

# Download the raw content of https://github.com/microbiomedata/berkeley-schema-fy24/blob/main/nmdc_schema/nmdc_materialized_patterns.yaml
curl -o schema.yaml https://raw.githubusercontent.com/microbiomedata/berkeley-schema-fy24/main/nmdc_schema/nmdc_materialized_patterns.yaml

输出

当refscan运行时，它将显示控制台输出，指示它正在做什么。

扫描完成后，引用报告（TSV文件）和违规报告（TSV文件）将在当前目录（或任何通过CLI选项指定的自定义目录中）中可用。

更新

您可以通过运行来将工具更新为PyPI上可用的最新版本

pipx upgrade refscan

卸载

您可以通过运行来从计算机中卸载该工具

pipx uninstall refscan

开发

我们使用Poetry来管理依赖关系并构建可发布的包，这些包可以发布到PyPI。

• pyproject.toml：Poetry和其他工具的配置文件（通过$ poetry init初始化）
• poetry.lock：直接和间接的依赖项列表

克隆仓库

git clone https://github.com/microbiomedata/refscan.git
cd refscan

创建虚拟环境

创建Poetry虚拟环境并将其附加到其shell

poetry shell

您可以通过运行：$ poetry env info来查看关于Poetry虚拟环境的信息

您可以通过运行：$ exit来从Poetry虚拟环境的shell中分离

从现在起，我将把Poetry虚拟环境的shell称为“Poetry shell”。

安装依赖

在Poetry shell中安装项目的依赖项

poetry install

进行更改

随意编辑工具的源代码和文档。

在编辑工具的源代码时，您可以像平时一样运行工具来测试功能。

refscan --help

运行测试

我们使用 pytest 作为 refscan 的测试框架。

测试定义在 tests 目录中。

您可以通过在仓库根目录下运行以下命令来运行测试

poetry run pytest

格式化代码

我们使用 black 作为 refscan 的代码格式化工具。

我们不使用其默认选项。相反，我们包含一个选项，允许行长度为120个字符，而不是默认的88个字符。该选项定义在 pyproject.toml 的 [tool.black] 部分。

您可以通过在仓库根目录下运行此命令来格式化仓库中的所有Python代码

poetry run black .

检查格式

您可以通过包括 --check 选项来 检查 Python代码的格式，如下所示

poetry run black --check .

构建和发布

为生产构建

每当有人在此仓库中发布一个 GitHub 发布 时，一个 GitHub Actions 工作流程 将自动构建一个包并将其发布到 PyPI。该包的版本标识符将与发布关联的Git标签名称匹配。

在本地测试构建过程

如果您想在本地测试构建过程，可以通过运行以下命令来实现

poetry build

这将创建 dist 目录中的源分发文件（以 .tar.gz 结尾）和 wheel 文件（以 .whl 结尾）。

附录

refgraph

当 pipx 安装 refscan 时，它还会安装一个名为 refgraph 的程序。 refgraph 是一个程序，您可以使用它来生成一个基于网页的、交互式的图（网络图），显示符合给定模式的数据库中文档之间可能存在的关联。它可以以数据库集合或模式类的方式来展示这些关联。

您可以通过运行以下命令来了解更多关于 refgraph 的信息

refgraph --help

注意： refgraph 还处于早期开发阶段，其功能和CLI可能会更改。