"Staging" for Snakemake

此包为Snakemake工作流程提供一个机制，可以将某些规则输出文件显式"移出"到公共存储库（如Zenodo），以便使用这些先前生成的工件更快地重新执行工作流程。这对于需要频繁重新运行的计算成本高的规则特别有用。

snakemake-staging是showyourwork项目的衍生项目，该项目为Snakemake工作流程提供“缓存”框架，以透明地避免重新执行已缓存到Zenodo的规则。然而，在showyourwork中实现此逻辑的方式相对脆弱且不可预测。在snakemake-staging中，我们采取了一种更明确的方法，其中“已移出”的规则总是明确执行或恢复。

安装

要在您的工作流程中使用snakemake-staging，您可以使用pip安装它（最好先根据Snakemake文档设置您的Snakemake安装）

python -m pip install snakemake-staging

快速入门

Snakefile

在测试时，最好使用Zenodo沙箱，而不是主站点，因为发布到Zenodo的任何存档都是永久的。要使用沙箱，您需要在SANDBOX_TOKEN环境变量中存储个人访问令牌。您可以在此处生成新令牌。

将此令牌添加到您的环境后，您可以编辑工作流程的Snakefile以使用snakemake-staging，如下所示。首先，在您的Snakefile顶部添加以下内容：

import snakemake_staging as staging

stage = staging.ZenodoStage(
    "zenodo-stage",
    config.get("restore", False)
)

创建一个名为 zenodo-stage 的新阶段。注意，这里我们从 Snakemake 配置中提取了一个 restore 标志，该标志将用于确定是否要恢复该阶段的文件。这意味着您可以通过命令行来控制此阶段的行为。通过将 --config restore=True 传递给 snakemake 命令行界面，所有由 zenodo-stage 阶段输出的文件将是从存档中恢复，而不是生成。

然后，要输出一个规则，您可以将阶段应用如下

rule expensive:
    input:
        ...
    output:
        stage(
            "path/to/output1.txt",
            "path/to/output2.txt",
        )
    shell:
        ...

最后，在定义您想要输出的所有规则之后，您必须添加以下 include，它定义了所有输出规则

include: staging.snakefile()

此时，这是完整的 Snakefile

import snakemake_staging as staging

stage = staging.ZenodoStage(
    "zenodo-stage",
    config.get("restore", False)
)

rule expensive:
    input:
        ...
    output:
        stage(
            "path/to/output1.txt",
            "path/to/output2.txt",
        )
    shell:
        ...

include: staging.snakefile()

用法

在上一节中定义了 Snakefile 后，您现在可以用以下三种方式运行您的流程

1. 正常执行：如果您运行类似 snakemake path/to/output1.txt（其中我省略了常用的 --cores 和 --conda 参数），则将按正常方式执行工作流程，而不会输出任何文件。

2. 阶段上传：如果您将 Snakemake 的目标设置为 staging__upload 规则，则会执行 expensive 规则，并将输出上传到 Zenodo，并将记录信息保存到 zenodo-stage.zenodo.json（此文件名可以通过将 info_file 参数传递给 ZenodoStage 构造函数来更改）。

3. 阶段恢复：最后，在这些输出已上传到 Zenodo 后，您可以调用 Snakemake --config restore=True 来禁用 expensive 规则，并强制从 Zenodo 恢复输出。